Embedding Portlets in Themes

You may occasionally want to embed a portlet in a theme, making the portlet visible on all pages where the theme is used. Since there are numerous drawbacks to hard-coding a specific portlet into place, the Portlet Providers framework offers an alternative that displays the appropriate portlet based on a given entity type and action.

In this tutorial, you’ll learn how to declare an entity type and action in a custom theme, and you’ll create a module that finds the correct portlet to use based on those given parameters. You’ll first learn how to embed portlets into a theme.

Adding a Portlet to a Custom Theme

The first thing you should do is open the template file for which you want to declare an embedded portlet. For example, the portal_normal.ftl template file is a popular place to declare embedded portlets. To avoid problems, it’s usually best to embed portlets with an entity type and action, but you may encounter circumstances where you’ll want to hard code it by portlet name. Both methods are covered here.

Embedding a Portlet by Entity Type and Action

Start by inserting the following declaration where you want the portlet embedded:


This declaration expects two parameters: the type of action and the class name of the entity type the portlet should handle. Here’s an example of an embedded portlet declaration that uses the class name:


This declares that the theme is requesting to view language entries. Liferay DXP determines which deployed portlet to use in this case by providing the portlet with the highest service ranking.

There are five different kinds of actions supported by the Portlet Providers framework: ADD, BROWSE, EDIT, PREVIEW, and VIEW. Specify the entity type and action in your theme’s runtime declaration.

Great! Your theme declaration is complete. However, the Portal is not yet configured to handle this request. You must create a module that can find the portlet that fits the theme’s request.

  1. Create an OSGi module.

  2. Create a unique package name in the module’s src directory, and create a new Java class in that package. To follow naming conventions, name the class based on the entity type and action type, followed by PortletProvider (e.g., SiteNavigationLanguageEntryViewPortletProvider). The class should extend the BasePortletProvider class and implement the appropriate portlet provider interface based on the action you chose in your theme (e.g., ViewPortletProvider, BrowsePortletProvider, etc.).

  3. Directly above the class’s declaration, insert the following annotation:

        immediate = true,
        property = {"model.class.name=CLASS_NAME"},
        service = INTERFACE.class

    The property element should match the entity type you specified in your theme declaration (e.g., com.liferay.portal.kernel.servlet.taglib.ui.LanguageEntry). Also, your service element should match the interface you’re implementing (e.g., ViewPortletProvider.class). You can view an example of a similar @Component annotation in the RolesSelectorEditPortletProvider class.

  4. Specify the methods you want to implement. Make sure to retrieve the portlet ID and page ID that should be provided when this service is called by your theme.

    A common use case is to implement the getPortletId() and getPlid(ThemeDisplay) methods. You can view the SiteNavigationLanguageViewPortletProvider for an example of how these methods can be implemented to provide a portlet for embedding in a theme. This example module returns the portlet ID of the Language portlet specified in SiteNavigationLanguagePortletKeys. It also returns the PLID, which is the ID that uniquely identifies a page used by your theme. By retrieving these, your theme will know which portlet to use, and which page to use it on.

The only thing left to do is generate the module’s JAR file and copy it to your Portal’s osgi/modules directory. Once the module is installed and activated in your Portal’s service registry, your embedded portlet is available for use wherever your theme is used.

You successfully requested a portlet based on the entity and action types required, and created and deployed a module that retrieves the portlet and embeds it in your theme.

Embedding a Portlet by Portlet Name

If you’d like to embed a specific portlet in the theme, you can hard code it by providing its instance ID and name:


The portlet name must be the same as javax.portlet.name’s value.

Here’s an example of an embedded portlet declaration that uses the portlet name to embed a web content portlet:


You can also set default preferences for an application. This process is covered next.

Setting Default Preferences for an Embedded Portlet

Follow these steps to set default portlet preferences for an embedded portlet:

  1. Retrieve portlet preferences using the freeMarkerPortletPreferences object. The example below retrieves the barebone portlet decorator:

    <#assign preferences = freeMarkerPortletPreferences.getPreferences(
      "portletSetupPortletDecoratorId", "barebone"
    ) />
  2. Set the defaultPreferences attribute of the embedded portlet to the freeMarkerPortletPreferences object you just configured:


Now you know how to set default preferences for embedded portlets! Next you can see the additional attributes you can use for your embedded portlets.

Additional Attributes for Portlets

Below are some additional attributes you can define for embedded portlets:

defaultPreferences: A string of Portlet Preferences for the application. This includes look and feel configurations.

instanceId: The instance ID for the app, if the application is instanceable.

persistSettings: Whether to have an application use its default settings, which will persist across layouts. The default value is true.

settingsScope: Specifies which settings to use for the application. The default value is portletInstance, but it can be set to group or company.

Now you know how to embed a portlet in your theme by class name and by portlet name and how to configure your embedded portlet!

Embedding Portlets in Themes


Service Builder

« Applying Portlet Decorators to Embedded PortletsClay CSS and Themes »
Este artigo foi útil?
Utilizadores que acharam útil: 0 de 0