Portlet Level Configuration

With the configuration framework, you can set your application’s configuration for different levels of scope. Where Instance and Site-scoped configurations use ConfigurationProvider, portlet scoped configurations use PortletDisplay as shown in the example below.

The configuration framework can be used in conjunction with portlet preferences so that an app can have both a configuration UI in system settings as well a preference UI in the portlet’s setup tab.

Note, an application’s configuration is overridden if portlet preferences are implemented and set by a user. See Portlet Preferences to learn more.

See the Example Code

  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 Sharing Localized Messages.

    curl -O
  3. From the module root, build and deploy.

    ./gradlew deploy$(docker ps -lq)


    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.x7y2.web_1.0.0 [1651]
  5. Verify that the example module is working. Open your browser to https://localhost:8080

  6. Deploy the X7Y2 Portlet to a page. You can find the example portlet under Sample Widgets. Notice that the default color is set to green.

  7. Navigate to Control PanelConfigurationSystem Settings. At the bottom under the Other section, click on the X7Y2 configuration.

    Navigate to the application's configuration in system settings.

    Select and save a different default color. Navigate back to the page with the deployed widget. The color variable is now updated.

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

    Select and save a different color. Close the window and now the portlet preference appears. Note that the application configuration set in system settings is no longer shown after a portlet preference has been selected.

Let’s examine how the application’s configuration works together with portlet preferences.

Create the Configuration Interface

First create the configuration interface file that auto-generates the configuration UI in system settings.

	category = "x7y2",
	scope = ExtendedObjectClassDefinition.Scope.PORTLET_INSTANCE
	id = "com.acme.x7y2.web.internal.configuration.X7Y2PortletInstanceConfiguration",
	name = "X7Y2 Portlet"
public interface X7Y2PortletInstanceConfiguration {

		deflt = "green", name = "color",
		optionLabels = {"Green", "Orange", "Purple"},
		optionValues = {"green", "orange", "purple"}, required = false
	public String color();


In this example, the scope is set to PORTLET_INSTANCE. The interface also defines the configuration options available in the drop-down list.

Note that this example also works with scope set at higher levels (i.e. Site, Instance, system scope). A best practice is to mark an application that you intend to use with portlet preferences as portlet scope.

To learn more, see Creating the Configuration Interface.

Add the Configuration Bean Declaration

Like ConfigurationProvider, PortletDisplay requires a configuration bean declaration file to register the configuration class. To learn more see configuration bean declarations.

Read the Configuration with PortletDisplay

Similar to reading configuration values from the Configuration Provider API, you can access the configuration values in your application with the Portlet Display API.

	configurationPid = "com.acme.x7y2.web.internal.configuration.X7Y2PortletInstanceConfiguration",
	property = {
		"javax.portlet.display-name=X7Y2 Portlet",
	service = Portlet.class
public class X7Y2Portlet extends MVCPortlet {

	public void render(
			RenderRequest renderRequest, RenderResponse renderResponse)
		throws IOException, PortletException {


		super.render(renderRequest, renderResponse);

	private X7Y2PortletInstanceConfiguration
			_getX7Y2PortletInstanceConfiguration(RenderRequest renderRequest)
		throws PortletException {

		ThemeDisplay themeDisplay = (ThemeDisplay)renderRequest.getAttribute(

		PortletDisplay portletDisplay = themeDisplay.getPortletDisplay();

		try {
			return portletDisplay.getPortletInstanceConfiguration(
		catch (ConfigurationException configurationException) {
			throw new PortletException(configurationException);


The X7Y2PortletInstanceConfiguration method uses PortletDisplay to obtain the portlet instance configuration. The render() method adds the configuration to the request object so that it can be read from the request of the JSP file.

Set up Portlet Preferences

For the portlet to have portlet preferences, you must also add a configuration JSP file and configuration action to your application. To learn more about how these files work in a portlet, see Portlet Preferences.