Liferay Portlet Configuration Page

---

Liferay Portlet Configuration Page is just an interface where we can configure the portlet in run time. In run time we can configure a portlet just by few clicks. Liferay Portlet Configuration Page uses preferences to store configuration information. In this article we will discuss various interesting facts about Liferay Portlet Configuration Page. By the end of this article you will understand

i) Concept of Liferay Portlet Configuration Page.

ii) Adding configuration page to a custom plugin portlet.

iii) How to configure a portlet by configuration page.

iv) Example of Custom Plugin Portlet with configuration page.

v) Some important code related to Liferay Portlet Configuration Page.

---

So before diving into the main topic lets see some some questions answers to make this topic more simpler.

1. Does every portlet has configuration page in liferay Portal?

Ans: No

2. How to know whether a portlet has configuration page or not?

Ans: Log in as Admin. Now go to a portlet and navigate as below

After clicking the configuration page it will open a pop up page like below. If a portlet has setup tab then its a configuration page.

3. Can we add configuration page to a custom portlet?

Ans: Yes

4. Do I need to do some extra stuff for adding configuration page?

Ans: Yes

5. I want to add configuration page to my custom portlet. Whats the first step for it?

Ans: We have to tell Liferay that we need a configuration page for the portlet. This is done by adding extra line in liferay-portlet.xml. We will discuss about it very soon.

6. Do we need configuration page for every custom portlet?

Ans: Its optional

---

Exercise

Now we have basic idea about the configuration page for a portlet. For understanding configuration stuff perfectly we will create a custom portlet and we will try to add configuration page step by step. In this custom portlet we will develop a configuration page where we will be able to pick a color of our own choice and as soon as we save the page, the content of the portlet will be refreshed with the color that we selected. Lets follow the steps

Step 1: Create a  new portlet

For the demonstration purpose we have created an instanceable portlet. The name of the portlet is configuration-page-demo-portlet. You can create any portlet with any name according to your choice.

Step 2: Add an entry to liferay-portlet.xml file
To add configuration page we must tell liferay by adding <configuration-action-class> tag in liferay-portlet.xml. See the full code

<?xml version="1.0"?>
<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 6.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_6_2_0.dtd">

<liferay-portlet-app>
	<portlet>
		<portlet-name>configuration-page-demo</portlet-name>
		<icon>/icon.png</icon>
		<configuration-action-class>com.proliferay.demo.config.ConfigurationActionImpl</configuration-action-class>
		<instanceable>true</instanceable>
		<header-portlet-css>/css/main.css</header-portlet-css>
		<footer-portlet-javascript>/js/main.js</footer-portlet-javascript>
		<css-class-wrapper>configuration-page-demo-portlet</css-class-wrapper>
	</portlet>
	<role-mapper>
		<role-name>administrator</role-name>
		<role-link>Administrator</role-link>
	</role-mapper>
	<role-mapper>
		<role-name>guest</role-name>
		<role-link>Guest</role-link>
	</role-mapper>
	<role-mapper>
		<role-name>power-user</role-name>
		<role-link>Power User</role-link>
	</role-mapper>
	<role-mapper>
		<role-name>user</role-name>
		<role-link>User</role-link>
	</role-mapper>
</liferay-portlet-app>

Step 3: Write the Configuration Action Class
In the Step 1 we have added <configuration-action-class>com.proliferay.demo.config.ConfigurationActionImpl</configuration-action-class> ConfigurationActionImpl class should implement com.liferay.portal.kernel.portlet.ConfigurationAction interface. Below is the code. Read the code comments carefully.

package com.proliferay.demo.config;

import javax.portlet.ActionRequest;
import javax.portlet.ActionResponse;
import javax.portlet.PortletConfig;
import javax.portlet.PortletPreferences;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

import com.liferay.portal.kernel.portlet.ConfigurationAction;
import com.liferay.portal.kernel.servlet.SessionMessages;
import com.liferay.portal.kernel.util.ParamUtil;
import com.liferay.portlet.PortletPreferencesFactoryUtil;
/**
 *
 * @author Hamidul Islam
 *
 */

public class ConfigurationActionImpl implements ConfigurationAction {

	/**
	 * When save the configuration page this process action will be called.
	 * But not the portlet's process action
	 */

	@Override
	public void processAction(PortletConfig portletConfig,
			ActionRequest actionRequest, ActionResponse actionResponse)

	throws Exception {

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

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

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

		prefs.setValue("colorCode", colorCode);

		prefs.store();

		SessionMessages.add(actionRequest, "config-stored");

		/**
		 * The below line will refresh the view page of the portlet
		 */
		SessionMessages.add(actionRequest,portletConfig.getPortletName() + SessionMessages.KEY_SUFFIX_REFRESH_PORTLET,portletResource);

	}

	@Override
	public String render(PortletConfig portletConfig, RenderRequest renderRequest,
			RenderResponse renderResponse) throws Exception {
		/**
		 * When we click the setup tag in configuration page
		 * This page will be shown
		 */
		return "/configuration.jsp";
	}

}

Step 4: Designing the configuration.jsp

<%@ taglib uri="http://liferay.com/tld/portlet" prefix="liferay-portlet"%>
<%@ taglib uri="http://liferay.com/tld/ui" prefix="liferay-ui" %>
<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet"%>
<liferay-portlet:actionURL var="configurationURL" 	portletConfiguration="true" />
<portlet:defineObjects />
<% 	String colorCode = portletPreferences.getValue("colorCode", ""); %>

<div id="color" style="padding-left: 10px;"></div>

<script>
	YUI().use('aui-color-picker-popover', function(Y) {
		var colorPicker = new Y.ColorPickerPopover({
			trigger : '.myColorPickerPopover'
		}).render();

		colorPicker.on('select', function(event) {
			event.trigger.setStyle('backgroundColor', event.color);
			Y.one('.colorCode').val(event.color);
		});

	});
</script>
<liferay-ui:success key="config-stored" message="Configuration Saved Successfully" />

<form name="fm" method="post" action="<%=configurationURL.toString()%>">
<input  class="myColorPickerPopover" type="text" value="Click me..." style="background-color: <%=colorCode%>">
Color Code: <input class="colorCode" type="text" name='<portlet:namespace/>colorCode' readonly value="<%=colorCode%>">
<input type="submit" value="Save">
</form>

Note 1: Look at the line where action url is created. We have used portletConfiguration=”true” . This is must for portlet configuration page.

Note 2: If we don’t mention portletConfiguration=”true” then the url will act like a normal action URL which will invoke portlet’s action URL.

 

Summery:

Download the source code and deploy it. Add the portlet multiple times in a single page. Go to the configuration page for each instance of the portlet. Choose different color for each of the instance and then save. Look at the each portlet instance. You will see different font color for each of the portlet instance.

Download Source Code