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.112-ga112
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/dxp/latest/en/building-applications/developing-a-java-web-application/using-mvc/liferay-p1z2.zip -O
unzip liferay-p1z2.zip
-
From the module root, build and deploy.
./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
NoteThis 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 () and click Configuration. The portlet’s preferences window opens.
-
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
)