Portlet Preferences

You can give administrators and users a way to customize a portlet with portlet preferences. Portlet preferences can be added to any MVC Portlet to give users a UI to access and set their preferences.

Note, portlet preferences are properties that are stored separately from an application’s configuration. To learn more see Portlet Level Configuration.

See a Sample Implementation

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip the example.

curl https://resources.learn.liferay.com/examples/liferay-p1z2.zip -O

unzip liferay-p1z2.zip

From the module root, build and deploy.
```
./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
```
Note

This command is the same as copying the deployed jars to /opt/liferay/osgi/modules on the Docker container.
Confirm the deployment in the Liferay Docker container console.
```
STARTED com.acme.p1z2.web_1.0.0 [2725]
```
Verify that the example module is working. Open your browser to https://localhost:8080
Add the P1Z2 portlet to a page. You can find the example portlet under Sample Widgets. Note the default color variable is set to blue.
Click the portlet’s options icon () in the widget header → Configuration. The portlet’s preferences window opens.

Note

Before Liferay DXP 2025.Q1/Portal GA132, the Configuration option appeared in the widget’s top-right corner.
Select a different color and click Save. Close the preferences menu and now the portlet shows your new selection.

Here’s how the preferences work.

Create the Configuration JSP

The user interface for portlet preferences is provided by the configuration.jsp file.

<portlet:defineObjects />

<liferay-portlet:actionURL portletConfiguration="<%= true %>" var="configurationActionURL" />

<aui:form action="<%= configurationActionURL %>" method="post" name="fm">
	<aui:input name="<%= Constants.CMD %>" type="hidden" value="<%= Constants.UPDATE %>" />

	<liferay-portlet:renderURL portletConfiguration="<%= true %>" var="configurationRenderURL" />

	<aui:input name="redirect" type="hidden" value="<%= configurationRenderURL %>" />

	<aui:fieldset>
		<aui:select label="color" name="color" value='<%= (String)portletPreferences.getValue("color", "blue") %>'>
			<aui:option label="Blue" value="blue" />
			<aui:option label="Red" value="red" />
			<aui:option label="Yellow" value="yellow" />
		</aui:select>
	</aui:fieldset>

	<aui:button-row>
		<aui:button type="submit" />
	</aui:button-row>
</aui:form>

The JSP file uses <liferay-portlet:actionURL /> and <liferay-portlet:renderURL /> tags to construct URLs in the variables configurationActionURL and configurationRenderURL.

When someone submits the form, the configurationActionURL is invoked, which triggers the application’s processAction method with the color variable included as a request parameter.

A URL parameter named cmd is supplied indicating the purpose of the request. The value of the cmd parameter is update.

Create the Configuration Action

Create a custom configuration action class to be able to access the portlet’s preferences.

@Component(
	property = "javax.portlet.name=com_acme_p1z2_web_internal_portlet_P1Z2Portlet",
	service = ConfigurationAction.class
)
public class P1Z2ConfigurationAction extends DefaultConfigurationAction {

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

		setPreference(
			actionRequest, "color",
			ParamUtil.getString(actionRequest, "color"));

		super.processAction(portletConfig, actionRequest, actionResponse);
	}

}

In the @Component annotation, specify the portlet the action class applies to with a property tag.

Add the processAction() method which reads the portlet preferences from the configuration form and stores them in the database. In the sample portlet, the method reads the color URL parameter and sets the value as a portlet preference.

Add the Preference Logic

Add some logic to the view.jsp file to access the portlet’s preference.

<h4>P1Z2 Portlet</h4>

The JSP file checks for the selected portlet preference and returns the value. If no value has yet been saved, blue is returned as the default value.

Note that the <portlet:defineObjects /> tag makes portletPreferences available, which you use to retrieve the color preference in the JSP.

Add the Portlet’s Path Parameters

In the portlet’s @Component annotation, add the view template and configuration template path parameters.

@Component(
	property = {
		"com.liferay.portlet.display-category=category.sample",
		"javax.portlet.display-name=P1Z2 Portlet",
		"javax.portlet.init-param.config-template=/configuration.jsp",
		"javax.portlet.init-param.view-template=/view.jsp",
		"javax.portlet.name=com_acme_p1z2_web_internal_portlet_P1Z2Portlet"
	},
	service = Portlet.class
)