Public render parameters

Public render parameters allow JSR 286 portlets to share navigational state information. They are specially useful for coordinating the multiple navigation or viewer portlets that display different information items that are all related to the same parameter name. 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.

Parent: Portlet communication
Related:
Shared portlet state
Publish/subscribe message based communication
Special purpose techniques for data exchange
Portlet events based communications
Cooperative portlets
Interoperability between events and cooperative portlets
Event broker
Portlet wires
Known issues and restrictions with portlet communication

Concepts of the Java Portlet Specification 2.0

Programming details for public render parameters are defined in the Java Portlet Specification 2.0. 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 descriptors, 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 descriptors:

<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 v8.0 does not have a user interface that requires this information for display.

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 parameters declare the same global name including the namespace.

• The parameters are placed in the same scope.

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 us 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. We 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.

To prevent all render parameters used on a given page from being shared with other pages, we can set the parameter param.sharing.scope to the reserved value ibm.portal.sharing.scope.page. This produces the same result as using the unique object ID of the page, as generated internally by the portal, for the value of the param.sharing.scope parameter.

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; we can currently not control sharing of public render parameters at a more granular level than 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