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 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 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 (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 %>
  <p>
    Cor de fundo: <%= text_field_tag :background_color_preference, @preferences[:background_color_preference] %>
  </p>
  <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.