This article needs updating. For more information, see Wiki - Need Updating.

Introduction #

Themes are developed using the Velocity template language. Liferay provides tools available within Velocity's context to perform special operations such as embedding a portlet. You can embed a built-in Liferay portlet or a plugin portlet, and you can also embed instanceable or non-instanceable portlets.

Here is an example of embedding the Navigation portlet into the theme.

Example #

Step One: Obtain the portlet nomenclature #

A portlet nomenclature consists of two parts: its unique ID string within the Liferay server, plus an instance identifier if necessary.

Every Liferay portlet has a unique Portlet ID, expressed as a String variable.

• For out-of-the-box portlets, the ID is a numeric value.  For example, the Navigation portlet has an ID# of "73".
• If the portlet is from a deployable plugin, the Portlet ID is more complex.  It will consist of the portlet's name, the string "WAR", and the name of the WAR file from which it is was deployed.  The complete form of the Portlet ID and how to construct one is defined in Theme Id or Portlet Id references in portal-ext.properties.

If the portlet is instanceable, then the nomenclature for the portlet must also contain an InstanceId in the form of a 4 character, alpha-numeric string, such as E3j7. The goal for this value is that it should be unique among the portlets of the same type (instance ID) on any given page.  The InstanceId is appended to the Portlet Id using the string "_INSTANCE_".

For our example, we are using the Navigation portlet, which has a Portlet ID of "73" and is instanceable, so we'll also need to give it an Instance Id as well.  Thus:

#set ($portlet_id = '73')
#set ($instance_id = 'E3j7')
#set ($my_portlet_id = "${portlet_id}_INSTANCE_${instance_id})

...which results in a portlet nomenclature of:

73_INSTANCE_E3j7

Step Two: Create the preferences for the portlet #

You can supply preferences for your embedded portlet as well.  Liferay provides a built-in VM variable called $velocityPortletPreferences for this purpose.

$velocityPortletPreferences is a Map<String, String>.  For each preference, pass its key string plus the value you desire.  The key may be one of Liferay's built-in portlet preference keys, or (for plugin portlets) one of your own that your portlet knows how to interpret.

For example, say we want to set the display style of the Navigation portlet to '1', and also we want the portlet to render itself borderless.  The latter is controlled by the key 'portlet-setup-show-borders'.  Thus:

#set ($VOID = $velocityPortletPreferences.setValue('display-style', '1'))
#set ($VOID = $velocityPortletPreferences.setValue('portlet-setup-show-borders', 'false'))}}}

Important: when you first pass preference values to a particular portlet instance on a page, Liferay will persist those values in the database.  From that point on, you cannot change the values in your Velocity macro.  See below for a discussion on how to cope with this feature.

Step Three: Create the runtime parameters #

In addition to preferences, you may also pass runtime parameters to your portlet, just as if they came from the query string.  These are set using basic URL parameter format, using "key=value" pairs separated by ampersands.  Your parameter names should not be namespaced to your portlet -- Liferay will take care of that for you.

For example, if you want to pass two parameters to your portlet called param1 and param2, you might construct the following string:

#set ($queryString = "param1=value1&param2=value2")

Step Four: Embed the portlet using //$taglibLiferay// #

Finally, we want to have the portlet invoked in some specific location on the theme.  Once again, Liferay pre-defines a VM variable for this purpose: $taglibLiferay.  You must pass the complete nomenclature of the portlet as the first argument.  The optional second argument is the runtime parameters (i.e., the query string), and the optional third argument are the portlet preferences, which need to be serialized to a string.  Thus, for our example:

$taglibLiferay.runtime($myPortletId, $queryString, $velocityPortletPreferences.toString())

Step Five: Cleanup #

If you plan to add more than one portlet to the page in this way, make sure to reset the preferences you created for each portlet:

#set ($VOID = $velocityPortletPreferences.reset())

You can then proceed with a different portlet.

Complete Example #

Here is a complete example for the Navigation portlet (ID=73) with two preferences and no runtime parameters:

#set ($VOID = $velocityPortletPreferences.setValue('display-style', '1'))
#set ($VOID = $velocityPortletPreferences.setValue('portlet-setup-show-borders', 'false'))
#set ($instanceId = 'E3j7')
#set ($myPortletId = "73_INSTANCE_${instanceId}")$taglibLiferay.runtime($myPortletId, '', $velocityPortletPreferences.toString())
#set ($VOID = $velocityPortletPreferences.reset())

Changing the Portlet Preferences #

Sometimes you will put a portlet into your theme using one set of preferences, and later wish to change the preference values.  Many Liferay developers are frustrated to find that they can't do this easily.  The reason has to do with how Liferay persists portlet preferences - essentially, once they are written to the database (which will happen the first time the portlet is created on a page), you can no longer change them in Velocity.  Liferay will always use the stored preferences in favor of the preferences argument you pass.

There are two ways around this problem.

The first, for instanceable portlets, is simply to change the Instance ID to a new four-character string.  Liferay will consider it a new portlet and ignore its saved values.  Beware: those old values will still be lurking in the database, so if you ever do create a portlet with the old name, right down to the instance ID, those saved values will be used.

The second, suggested by Artur Linhart on the Liferay forums (see http://www.liferay.com/community/forums/-/message_boards/message/772138) is to have Velocity erase the old DB preferences before providing new ones.  Note that you do not want to make a habit of this, since it involves a DB operation that over time can prove very costly in terms of your site's performance.  The following Velocity macro will do the trick - note that it takes a fourth argument, which specifies whether any previous preferences should be erased.  It is suggested that you set up your VM code to pass 'true' only in development, and 'false' in production.

#macro (embedPortletUsing, $portletId, $requestVars, $preferences, $overrideDbPrefs)
  #if ($overrideDbPrefs)
    #set ($locPortletPreferenceService = $serviceLocator.findService("com.liferay.portal.service.PortletPreferencesLocalService"))
    #set ($locPlidLong = $getterUtil.getLong($plid))
    $locPortletPreferenceService.deletePortletPreferences(0, 3, $locPlidLong, $portletId)
  #end

  $taglibLiferay.runtime($portletId, $requestVars, $preferences)
#end