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:
<@liferay_portlet["runtime"]
portletProviderAction=ACTION
portletProviderClassName="CLASS_NAME"
/>
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:
<@liferay_portlet["runtime"]
portletProviderAction=portletProviderAction.VIEW
portletProviderClassName="com.liferay.portal.kernel.servlet.taglib.ui.LanguageEntry"
/>
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.
-
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 theBasePortletProvider
class and implement the appropriate portlet provider interface based on the action you chose in your theme (e.g.,ViewPortletProvider
,BrowsePortletProvider
, etc.). -
Directly above the class’s declaration, insert the following annotation:
@Component( 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, yourservice
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. -
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()
andgetPlid(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:
<@liferay_portlet["runtime"]
instanceId="INSTANCE_ID"
portletName="PORTLET_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:
<@liferay_portlet["runtime"]
portletName="com_liferay_journal_content_web_portlet_JournalContentPortlet"
/>
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:
-
Retrieve portlet preferences using the
freeMarkerPortletPreferences
object. The example below retrieves thebarebone
portlet decorator:<#assign preferences = freeMarkerPortletPreferences.getPreferences( "portletSetupPortletDecoratorId", "barebone" ) />
-
Set the
defaultPreferences
attribute of the embedded portlet to thefreeMarkerPortletPreferences
object you just configured:<@liferay_portlet["runtime"] defaultPreferences="${preferences}" portletName="com_liferay_login_web_portlet_LoginPortlet" />
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!