Public render parameters

 

+

Search Tips   |   Advanced Search

 

Public render parameters allow JSR 286 portlets to share navigational state information. They are useful for coordinating the multiple navigation or viewer portlets that display different information items that are all related to the same key.

The portal stores all portlet render parameters, including public render parameters, as an encoded part of the current portal URL. Therefore public render parameters are correctly preserved by typical browser navigation actions such as Back button and bookmarking.

 

Concepts of the Java Portlet Specification 2.0

Programming details for public render parameters are defined in the Java Portlet Specification 2.0 (JSR 286). They are read as request parameters and set in render URLs or on an ActionResponse. For most purposes, public render parameters behave exactly like "normal" or private render parameters. The only difference is that the parameter identifier is explicitly declared by the programmer in the portlet.xml deployment descriptor, along with one or more namespaced public names, so that a portal can decide which parameters of two portlets should map to the same information.

Here is an example declaration in the deployment descriptor: 

<portlet-app xmlns:x="http://acme.com/portlet">

   <portlet>
      ...
      <supported-public-render-parameter>custID</supported-public-render-parameter>
   </portlet>

   <public-render-parameter>
       <identifier>custID</identifier>
       <qname>x:customerID</qname>
   </public-render-parameter>

</portlet-app>

This declares a public render parameter that is accessed with the parameter key custID.

Here is an example code snippet for reading the parameter: 

 String customerID = renderRequest.getParameter("custID");

The parameter is shared with the global name customerID in the namespace...

http://acme.com/portlet

This means that if another portlet declares a parameter with the same global name - regardless of the local identifier that it uses - that parameter can be mapped to the same data by the portal.

Portlets can declare localized display names and descriptions for public render parameters in the application resource bundle. However, WebSphere Portal V6.1 does not have a user interface that requires this information for display.

How to control parameter sharing in the portal

The portal implements the sharing of parameters by placing them in scopes: Two or more public render parameters from different portlets are mapped to the same data in the portlet URL, if and only if both of the following conditions apply:

The default scope for all public parameters is the global scope. This means that all public parameters with the same global name are shared by all portlets across all pages.

For some use cases it can be required to limit parameter sharing. For example, this can apply if you have two pairs of navigator or viewer portlets on two different pages, where each pair should be coordinated, but they should not interfere across pages so that the navigator on the first page does not influence the viewer on the second page. For such cases, the portal allows you to limit the sharing scope for public render parameters on a page basis. The parameter sharing scope for a page is controlled by a page parameter param.sharing.scope.

You can set it from the Page Properties view under Advanced options > I want to set parameters. If you set a value for this page parameter, portlets on the page share their public render parameters only with other portlets on the same page or on pages with the same scope.

Limitations

The following are known limitations to public render parameters:

  1. The sharing scope always applies to all parameters of all portlets on a page; you can currently not control sharing of public render parameters below the page level.

  2. The optional <alias> elements of public render parameter declarations are ignored. Currently, sharing of public render parameters is only controlled by the <name> or <qname> elements of the parameter declarations

 

Parent topic

Portlet communication

 

Related concepts

Shared portlet state
Publish/subscribe message based communication
Special purpose techniques for data exchange
Cooperative portlets
Event broker
Portlet wires

 

Related reference

Portlet events
Interoperability between events and cooperative portlets
Known issues and restrictions with portlet communication