Embedding a portlet in the Theme_liferay

Original: Http://www.liferay.com/community/wiki/-/wiki/Main/Embedding+a+portlet+in+the+theme

Introduction #

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

This is a 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.

The

Every Liferay Portlet has a unique portlet ID, expressed as a String variable. For Out-of-the-box Portlets, the ID was a numeric value.  for example, The navigation portlet has a id# of "73". If the portlet is from a deployable plugin, The portlet id is more complex.  It would consist the Portlet ' s name, the string ' War ', and the name of the ' War file from which it's ' is ' deployed.  ' complete form of the  ; Portlet Id and to construct one is defined In theme ID or portlet IDs references in Portal-ext.properties.

If The portlet is instanceable, then the nomenclature for the Portlet must also contain a instanceid in the form of a 4 C Haracter, alpha-numeric string, such as E3J7.  The goal for this value was that it should to 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 "" and are instanceable, so we ' ll also NE  Ed to give it a Instance Id as. Thus:

#set ($portlet _id = ' _id ')
#set ($instance = ' 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. Liferay provides a built-in VM variable called$velocityportletpreferences for this purpose.

$velocityPortletPreferences is a map<string, string>  For each preference, pass it key string plus the value you desire. The key May is one of the Liferay ' s built-in portlet preference keys, or (for plugin portlets) One of your own that your PORTL ET knows to interpret.

For example, say we want to set the display style of the navigation portlets to ' 1 ', and also we want the portlets 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 the preference values to a particular portlets instance on a page, Liferay'll persist those VA  Lues in the database.  From then, you cannot change the values in your Velocity macro. The "below for a" discussion on the how to cope with this feature. Step three:create the runtime parameters #

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

For example, if your want to pass two parameters to your portlets called param1 and param2, you might construct the Followin G 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. Liferay 5.2.x and Lower #

Liferay pre-defined VM variable for this purpose is $taglibLiferay.  On it runtime () method, your must pass the complete nomenclature of the portlet as the "the". The optional second argument is the runtime parameters (i.e., the query string), and the optional third argument the P  Ortlet preferences, which need to is serialized to a string. Thus for our example:

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

Liferay 6.x #

Liferay pre-defined VM variable for this purpose is $theme. On it runtime () method, your must pass the complete nomenclature of the portlet as the "the". The optional second argument is the runtime parameters (i.e., the query string), and the optional third argument the P Ortlet preferences, which need to is serialized to a string. Thus for our example:

$theme. Runtime ($myPortletId, $queryString, $velocityPortletPreferences. toString ())

Step Five:cleanup #

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

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

You can then proceed with a different portlet. Complete Example #

This is a complete example to the navigation Portlet (id=73) with two preferences and no runtime Parameters:liferay 5.2. X and Lower #

#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 ())

Liferay 6.x #

#set ($VOID = $velocityPortletPreferences. SetValue (' Display-style ', ' 1 ')
#set ($VOID = $ Velocityportletpreferences.setvalue (' Portlet-setup-show-borders ', ' false ')
#set ($instanceId = ' e3j7 ')
# Set ($myPortletId = "73_instance_${instanceid}") $theme. Runtime ($myPortletId, ', $ Velocityportletpreferences.tostring ())
#set ($VOID = $velocityPortletPreferences. Reset ())

Changing the Portlet Preferences #

Sometimes you'll put a portlets into your theme using one set of preferences, and later wish to change the preference Val  UEs.  Many Liferay developers are frustrated to find that they can ' t does this easily. The reason has to doing with the Liferay persists Portlet preferences-essentially, once they are written to the database (W Liferay'll always use the stored preferences in favor of the preferences for you.

There are two ways around this problem.

The, for Instanceable Portlets, are simply to change the Instance ID to a new Four-character string.  Y would consider it a new portlet and ignore its saved values.  beware:those old values would still be lurking in the Database, so if you are ever do create a portlets with the ' old ' name, right down to the instance ID, those saved values would be Used.

The second, suggested by Artur Linhart on the Liferay forums (see http://www.liferay.com/community/forums/-/mess age_boards/message/772138) is to have Velocity erase the old DB preferences before providing new ones.  Do not want to make a habit of this, since it involves a DB operation and over time can prove very costly in terms of yo Your site ' s performance.  the following Velocity macro the trick-note that it takes a fourth argument, which Specifies whether any previous preferences should the It is erased.  It are the set up suggested VM code to pass ' t Rue ' 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

0 Annex 29659 View