Documentation

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

  1. Start Liferay DXP. If you don’t already have a docker container, use

    docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.1-ga2
    

    If you’re running a different Liferay Portal version or Liferay DXP, adjust the above command accordingly.

  2. Download and unzip Portlet Preferences.

    curl https://learn.liferay.com/dxp/latest/en/developing-applications/developing-a-java-web-application/using-mvc/liferay-p1z2.zip -O
    
    unzip liferay-p1z2.zip
    
  3. 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.

  4. Confirm the deployment in the Liferay Docker container console.

    STARTED com.acme.p1z2.web_1.0.0 [2725]
    
  5. Verify that the example module is working. Open your browser to https://localhost:8080

  6. 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.

  7. Click the portlet’s options icon (options icon) and click Configuration. The portlet’s preferences window opens.

    Open the portlet's preferences by clicking configuration

  8. 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(
	configurationPolicy = ConfigurationPolicy.OPTIONAL,
	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
)