Add Config Page to Portlet

(Redirected from How to Add a Configuration Page to a Portlet)
Tags: development

Introduction #

Most of the portlets that are provided with Liferay have an associated configuration page. This page lets the page administrator configure some parameters of the portlet to set up how it will be shown to all other users. Note that this is quite different to the standard edit preferences page, which is generally used to allow each user to configure their own preference and do not affect other users (note that there are some exceptions).

This article explains how to add a (Liferay specific) configuration page to custom portlets. Note that for this to work the portlet has to be developed in the Extension Environment (or be part of Liferay's source code).

Steps #

The following steps describe which configuration files have to be modified and which classes and JSPs have to be created in order to implement a configuration page for an existing portlet. Some knowledge of StrutsPortlet is recommended.

For these steps we'll use the example of a portlet named 'Reports' that is being developed in the extension environments, make the necessary changes for your specific case.

Step 1) Add a Struts mapping for the configuration page #

Edit ext/ext-web/docroot/WEB-INF/struts-config.xml and add a mapping entry for the configuration page.

  <action path="/reports/edit_configuration" type="com.foobar.portlet.reports.action.EditConfigurationAction">
    <forward name="portlet.reports.edit_configuration" path="portlet.reports.edit_configuration" />
    <forward name="portlet.reports.error" path="portlet.reports.error" />

Step 2) Create the tiles definitions referenced from the mapping #

In the example above two tiles definitions where referenced: portlet.reports.edit_configuration and portlet.reports.error. This could be defined as:

  <definition name="portlet.reports.edit_configuration" extends="portlet.portlet_configuration.edit_configuration">
    <put name="portlet_configuration_content" value="/portlet/reports/edit_configuration.jsp" />

  <definition name="portlet.reports.error" extends="portlet.reports">
    <put name="portlet_content" value="/portlet/reports/error.jsp" />

It is important to note that while the error view extends the regular portlet tiles definition, the edit_configuration definition extends portlet.portlet_configuration.edit_configuration. This extended definition is responsible for rendering the generic tabs such as "Look & Feel" and "Permissions".

Step 3) Create the JSP pages referenced from the tiles definitions #

In the tiles definition two JSP were referenced. Create these two files containing:

  • error.jsp: A message explaining that an error has occurred. You can provide information about the error through request attributes from the EditConfiguration class (see next step)
  • edit_configuration.jsp: The form that the page administrator will edit to set up the portlet. A very simple example would be:
  PortletPreferences prefs = PortletPreferencesFactory.getPortletSetup(
            request, portletResource, false, true);

  String emailFromName = prefs.getValue("setting1", "");

  <form action="<liferay-portlet:actionURL portletConfiguration="true" />" 
        method="post" name="<portlet:namespace />fm">
    Setting 1: <input name="<portlet:namespace />setting1" 
                      type="text" value="<%= setting1 %>" />

Step 4) Create a class to read and store the configuration values #

This class has to inherit from import com.liferay.portal.struts.PortletAction and implement the processAction(..) and render() methods as follows:

Render #

The render method is invoked when the user clicks the edit configuration icon and should show the configuration form. The easiest way to implement it is to do a forward to the tiles definition for the form:

  public ActionForward render(
      ActionMapping mapping, ActionForm form, PortletConfig config,
      RenderRequest req, RenderResponse res)
    throws Exception {

    return mapping.findForward("portlet.reports.edit_configuration");

Process Action #

The process action method is responsible for reading the information sent from the edit configuration form and storing it in the database. While any method can be used to store this information Liferay provides a very convenient way of doing it through a PortletPreferences object. To obtain that object the following method form PortletPreferencesFactory has to be invoked:

  public static PortletPreferences getPortletSetup(
      ActionRequest req, 
      String portletId, 
      boolean uniquePerLayout,
      boolean uniquePerGroup)

Here is a description of the parameters:

  • req: the request passed as a parameter to processAction
  • portletId: the originating portlet obtained by reading the parameter 'portletResource' (see the section on technical information below for more details)
  • uniquePerLayout: set to true to make this configuration unique for the current layout. Setting it to false will apply the same configuration to instances of this portlet in different pages.
  • uniquePerGroup: set to true to make this configuration unique for the current community. Setting it to false will apply the same configuration to instances of this portlet in all the communities of the portal. It is not common to set this parameter to false, for the implications in terms of authorization.

A very simple example of an implementation of processAction invoking this method would be:

  public void processAction(
      ActionMapping mapping, ActionForm form, PortletConfig config,
      ActionRequest req, ActionResponse res)
    throws Exception {
    String portletResource = ParamUtil.getString(
      req, "portletResource");

    PortletPreferences prefs = PortletPreferencesFactory.getPortletSetup(
      req, portletResource, false, true);

    ... read form parameters and set as preferences ...;

Usually this method will contain appropriate validation logic for the parameters received from the form.

Step 5) Register the struts mapping in the portlet definition #

Edit the portlet definition in ext/ext-web/docroot/WEB-INF/liferay-portlet-ext.xml and add the 'configuration-path' element pointing to the mapping that was defined in step 1.


This is it, now you are ready to test the portlet configuration.

Detailed technical information #

Determining the originating portlet when editing the configuration #

The configuration page is not accessed directly through the portlet it configures but through a special portlet (edit_configuration). This is mainly important when writing the form JSP and the corresponding action class. Nevertheless it is possible to obtain the id of the originating portlet by using the request parameter 'portletResource'

Related Articles #

How to Add Configuration Page to a Plugin Portlet

How To's

0 Attachments
Average (1 Vote)
The average rating is 2.0 stars out of 5.