Liferay is a Gartner Magic Quadrant Leader for the Sixth Year! Find out why
« Back to Development

Add Config Page to Plugin Portlet

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 that have been developed using the Liferay Plugins SDK. If you are working with portlets that have been developed in the Extension Environment, then please refer to this article.

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 new plugin portlet.

Create a new Plugin Portlet #

In the $PLUGINS_SDK/portlets folder run (on windows): create configuration-example "Configuration Example" or, on Linux/Mac: ./create.sh configuration-example "Configuration Example" (Where configuration-example is the name of the folder for your portlet and "Configuration Example" the display name)

Specify your Config Action Impl #

The configuration-action-class value is a class that implements com.liferay.portal.kernel.portlet.ConfigurationAction. This class is called to allow users to configure the portlet at runtime.

Open liferay-portlet.xml file in the $PLUGINS_SDK/portlets/configuration-example-portlet directory and add the <configuration-action-class> tag.

<portlet>
  <portlet-name>configuration-example</portlet-name>
  <icon>/icon.png</icon> 
  <configuration-action-class>com.sample.jsp.action.ConfigurationActionImpl</configuration-action-class> 
  <instanceable>true</instanceable> 
  <header-portlet-css>/css/test.css</header-portlet-css> 
  <footer-portlet-javascript>/js/test.js</footer-portlet-javascript> 
</portlet>

Implement your version of ConfigurationActionImpl #

We'll need to provide a class that implements the processAction(..) and render() methods as defined in the ConfigurationAction interface.

public class ConfigurationActionImpl implements ConfigurationAction {
   ...
   ...
   ...
}

Process Action #

The process action method is responsible for reading the information sent from the edit configuration form and storing it in the database. Usually this method will contain appropriate validation logic for the parameters received from the form. The following example, uses the PortletPreferences to store the configuration settings. The SessionMessages.add(..) method will display a success message if the update is successful.

public void processAction(PortletConfig config, ActionRequest actionRequest, ActionResponse actionResponse) throws Exception { 

  String portletResource = ParamUtil.getString(actionRequest, "portletResource"); 

  PortletPreferences prefs = PortletPreferencesFactoryUtil.getPortletSetup(actionRequest, portletResource); 

  //Read, validate, and then set form parameters as portlet preferences

  prefs.store();

  SessionMessages.add(actionRequest, portletConfig.getPortletName() + ".doConfigure");
}

Render #

The render method is invoked when the user clicks the edit configuration icon and should show the configuration form.

public String render(PortletConfig config, RenderRequest renderRequest, RenderResponse renderResponse) throws Exception { 

return "/configuration.jsp";
}

Create the JSP pages referenced from ConfigurationActionImpl #

In our ConfigurationActionImpl, a configuration.jsp was referenced. Create this file containing the form that the page administrator will edit to set up the portlet. A very simple example would be:

<%@ taglib uri="[[http://java.sun.com/portlet|http://java.sun.com/portlet]]" prefix="portlet" %> <%@ taglib uri="[[http://liferay.com/tld/portlet|http://liferay.com/tld/portlet]]" prefix="liferay-portlet" %> <%@ page import="com.liferay.portal.kernel.util.Constants" %> 

<portlet:defineObjects />

<form action="<liferay-portlet:actionURL portletConfiguration="true" />" method="post" name="<portlet:namespace />fm"> <input name="<portlet:namespace /><%=Constants.CMD%>" type="hidden" value="<%=Constants.UPDATE%>" /> 

Type: <select name="<portlet:namespace />type"> <option value="casual">Casual</option> <option value="formal">Formal</option> </select> <br/>

<input type="button" value="Save" onClick="submitForm(document.<portlet:namespace />fm);" /> </form>

Note the portletConfiguration attribute in the liferay-portlet:actionURL tag.

Deploy #

That's it, you are now ready to deploy and test the portlet configuration.

0 Attachments
88298 Views
Average (8 Votes)
The average rating is 4.375 stars out of 5.
Comments
Threaded Replies Author Date
Samuel,it is really a helpful demostration to... Kevin Liu August 26, 2010 2:09 AM
Is there any way to add config page for Spring... Mahesh Panchal June 30, 2011 9:24 AM
Hello, I have followed this tutorial; the... M Keehan July 22, 2011 5:46 AM
Nice Article !!!!!!! Thanks Jignesh Vachhani August 10, 2011 5:11 AM
how could I get PortletPreferences in render... kevin qian November 19, 2012 9:34 PM
You save my day! thanks! Víctor Salvans Montesó March 5, 2013 11:56 AM

Samuel,it is really a helpful demostration to give me a quick impression on the self-defined configuration of a portlet page, however, there are some mistakes in configuration.jsp,

<%@ taglib uri="[http://java.sun.com/portlet"] prefix="portlet" %>
<%@ taglib uri="[http://liferay.com/tld/portlet"] prefix="liferay-portlet" %>

should be replaced with
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>
<%@ taglib uri="http://liferay.com/tld/portlet" prefix="liferay-portlet" %>

Futhermore,for this configuration.jsp, could you give me
more explanation such as <portlet:defineObjects />,
<liferay-portlet:actionURL portletConfiguration="true" />?

Finally, I don't think it's a good idea to use create script, it gives some kind of confusion, just add/modify some files in the existing portlet developed based on liferay plugins sdk.
Posted on 8/26/10 2:09 AM.
Is there any way to add config page for Spring MVC portlet ?

Thanks,
Mahesh.
Posted on 6/30/11 9:24 AM.
Hello,

I have followed this tutorial; the config page displays correctly, but I am getting an 'invalid authentication token' error when I click submit. Can you help me with this? I've looked through the Liferay site but the only information I can find is to tell me how to switch authentication tokens off - I'd really prefer to know what's going on.
Posted on 7/22/11 5:46 AM.
Nice Article !!!!!!! Thanks
Posted on 8/10/11 5:11 AM.
how could I get PortletPreferences in render method?
Posted on 11/19/12 9:34 PM.
You save my day! thanks!
Posted on 3/5/13 11:56 AM.