Caterpillar is a developer tool to help building and deploying Rails applications for Liferay portlets. The aim is to minimize the needed additions to the Rails framework and interfere with the developer workflow.

Main features:

• installs the portlet JAR to Liferay's [+CLASSPATH+]
• dynamic portlet XML creation based on named routes
• deploys the generated XML to Liferay, requires Liferay restart
• implements session security by shared key authentication

For developers:

• portlet test bench
• a Rails view helper which lists portlets during development

= Quickstart Install the Caterpillar gem from rubygems.org:

$ gem install caterpillar

Start up a new Rails project:

$ rails example $ cd example $ caterpillar pluginize

Activate Caterpillar routes by updating RAILS_ROOT/config/routes.rb to read as follows:

ActionController::Routing::Routes.draw do |map| map.caterpillar # add this line

... other routes ...

This route mapping is also needed to use portlet security features to prevent UID faking. Update ApplicationController: class ApplicationController < ActionController::Base include Caterpillar::Security secure_portlet_sessions

If you are connecting to the Liferay database, add lportal[http://lportal.rubyforge.org/] in the Rails startup: $ echo "require 'lportal'" > config/initializers/lportal.rb And set up the database connection.

Now run caterpillar portlets to check if the installation is working. The output should include these lines:

• Portlet configuration *** Caterpillar Rails-portlet test bench "portlet_test_bench" []

Then you can start up the server (./script/server) and navigate to http://localhost:3000/caterpillar/test_bench

== Good to know The command-line tool caterpillar should be executed in the Rails project root directory. You can install and upgrade the rails-portlet JAR and generate dynamic portlet XML and also deploy them. See the task description below - and you can also run caterpillar --describe.

The optional Caterpillar Rails plugin offers specialized helpers and views for better Liferay integration and to ease the development. Not to mention the portlet test bench application.

Developers should know that this is required to successfully run the rails-portlet test suite, where JUnit tests do actual requests to the Rails app.

You can take plugins into use by running $ caterpillar pluginize in the Rails directory, but you need to remember that with each subsequent upgrade of Caterpillar, you would need to rm vendor/plugins/caterpillar && caterpillar pluginize each time. Rails is quite picky where it will load the views - security issue.

Maybe caterpillar could have an upgrade task to handle this?

== Useful tasks Here are the most useful tasks; see the rdoc documentation and caterpillar --describe for the full feature list.

makexml:: processes the portlet XML configuration in accordance with the named routes

xml:deploy:: deploys the created XML to the J2EE portlet container

jar:install:: installs the Rails-portlet JAR into Liferay's classpath

deploy:: warbles the application, updates the XML configuration and copies these to Liferay

pluginize:: copies caterpillar to vendor/plugins

fixtures:: imports live data from the production database for testing

Join the bugs mailing list (http://rubyforge.org/mailman/listinfo/rails-portlet-bugs) to request help.

= How to implement

== File Download

In order to use download links in your webpages, you need to use the method: send_file(file_path, :filename=>"filename")

For example, on DownloadController, 'start' method allows the download of 'image.jpg' file.
def start send_file('../images/image.jpg', :filename => "image.jpg") end

In your webpage, you should use the following method which will manage your urls: liferay_resource_url(:controller=> :controllerName, :action=> :methodName)

It should look like: <%= link_to "Download", liferay_resource_url(:controller => :download , :action => :start) %>

To access the +liferay_resource_url+ method you will need to include the Liferay module in your application_helper include Caterpillar::Helpers::Liferay

This method will generate a valid url for +serveResource+ method in liferay

== Portlet Preferences

To enable portlet preferences we need to set :edit_mode as true on portlet.rb file. We have two kinds of portlets, the instanceable ones and not instaceables ones. Each instaceable portlet holds it's own preferences otherwise not instanceable has just one definition, keeping the same data into all portlets of the kind. portlet.instances << { :name => 'test', :edit_mode => true, :instanceable => false }

Each mapped portlet requires a preferences method, by convention, which will handle the edit mode features. For example: def preferences if request.post? flash[:notice] = 'Success!' end end

If you want is possible to set the preferences_route in portlets.rb file. For example: portlet.instances << { :name => 'test', :edit_mode => true, :instanceable => true, :preferences_route => '/my_portlet/test/preferences' }

Rails-portlet will provide us a hash with all saved preferences, to access this method we need to include the Caterpillar::Helpers::Liferay module, like: include Caterpillar::Helpers::Liferay

This module will provide get_liferay_preferences method which returns the preferences hash. A good approach is to include this module on ApplicationController, like: class ApplicationController < ActionController::Base include Caterpillar::Helpers::Liferay

helper :all # include all helpers, all the time
protect_from_forgery # See ActionController::RequestForgeryProtection for details

before_filter :get_preferences

protected
def get_preferences
  preferences = get_liferay_preferences
  @preferences = preferences ? preferences : {}
end

end

In your erb file you will have a form like this, where each attribute (that has to be saved) needs to have sufix _preference on its name. For example: <% form_tag :controller => :test , :action => :preferences do %>

Cor de fundo: <%= text_field_tag :background_color_preference, @preferences[:background_color_preference] %>

<p>
  Tamanho fonte: <%= text_field_tag :font_size_preference, @preferences[:font_size_preference] %>
</p>
<p>
  Cor da fonte:  <%= text_field_tag :font_color_preference, @preferences[:font_color_preference] %>
</p>
<%= submit_tag "Salve" %>

<% end %>

== Public Render Parameters

To enable public parameters to your portlets, you must create the array public_render_parameters, in your portlets.rb instance configuration, where you will add the public variables (in our example, param1 and param2). portlet.instances << {
:name => 'home', :public_render_parameters => [:param1, :param2] }

In your erb file, for each public parameter, you must use the sufix _prp in it's name . For example, to use the public variable param1 in a textfield: <%= text_field_tag :param1_prp, '' %>

Watch it!

• You should not use the sufix _prp in portlets.rb.
• You must use the public render parameters in your erb file, in a form, using POST method. [It has to go through processAction]

• Even if you've got only one variable to add to public_render_parameters, you have to use the brackets.

  portlet.instances << {
  :name => 'home', :public_render_parameters => [:param1] }

• And remember, the _prp sufix is removed when the param is published, so "tag_prp" become just "tag" for the portlets that are listening to this parameter.