Public render parameters

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 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 the Back button and bookmarking.

• Public render parameters are generated between JSR portlets during the render phase and not the action phase.

• We can set shared render parameters as well as private render parameters during URL generation using the state API.

• Public render parameters can also be shared with remote portlets using the WSRP V 2.0 protocol, which is supported by WebSphere Portalv8.5, and later.

• Information about render parameters is normally encoded into the URL. Therefore their names and values should be as short as possible in order to not exceed the URL length restrictions set by the browser.

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 the parameter identifier is explicitly declared by the programmer in the portlet.xml deployment descriptor, along with one or more namespaced public names. As a result, a portal can decide which parameters of two portlets must 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>
  <qnamex:customerID</qname>
   </public-render-parameter>
</portlet-app>

This snippet 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. 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 globalized display names and descriptions for public render parameters in the application resource bundle. However, WebSphere Portal v8.5 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 that includes the namespace.
• The parameters are placed in the same scope.

The default scope for all public parameters is the global scope. Therefore, 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 case can occur if we have two pairs of navigator or viewer portlets on two different pages, where each pair must be coordinated. However, the pairs must not interfere across pages so the navigator on the first page does not influence the viewer on the second page. For such cases, the portal makes it possible 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 we set a value for this 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 page from being shared with other pages, we can set the parameter param.sharing.scope to the reserved value...

ibm.portal.sharing.scope.page

Specifying this value 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.

How to set the scope for specific public render parameters

The setting param.sharing.scope mentioned earlier sets the scope for all public render parameters. In addition, it is also possible to set the scope for specific public render parameters. The WebSphere Portal template pages use this approach. For example, the Basic page template specifies the following parameters:

<parameter name="param.sharing.scope.{http://www.ibm.com/xmlns/prod/datatype/content/resource-collections}" 
           type="string" update="set"><![CDATA[ibm.portal.sharing.scope.page]]></parameter>

<parameter name="param.sharing.scope.{http://www.ibm.com/xmlns/prod/datatype/content}" 
           type="string" 
           update="set"><![CDATA[ibm.portal.sharing.scope.page]]></parameter>

<parameter name="param.sharing.scope.{http://www.ibm.com/xmlns/prod/websphere/portal/v7.0/portal-contextual-portal}" 
           type="string" 
           update="set"><![CDATA[ibm.portal.sharing.scope.page]]></parameter>

<parameter name="param.sharing.scope.{http://www.ibm.com/xmlns/prod/websphere/portal/v8.0/portal-contextual-portal}" 
           type="string" 
           update="set"><![CDATA[ibm.portal.sharing.scope.page]]></parameter>

<parameter name="param.sharing.scope.{http://www.ibm.com/xmlns/prod/websphere/portal/publicparams}path-info" 
           type="string" 
           update="set"><![CDATA[ibm.portal.sharing.scope.page]]></parameter>

This snippet from a template sets the page scope for all public render parameters contained in the following name spaces:

http://www.ibm.com/xmlns/prod/datatype/content/resource-collections
http://www.ibm.com/xmlns/prod/datatype/content
http://www.ibm.com/xmlns/prod/websphere/portal/v7.0/portal-contextualportal
http://www.ibm.com/xmlns/prod/websphere/portal/v8.0/portal-contextualportal

It also sets the scope for the path-info parameter defined in the namespace

http://www.ibm.com/xmlns/prod/websphere/portal/publicparams

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 currently cannot 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

Parent Portlet communication

Related concepts:
Advanced URL generation for data exchange
Create a web content page with xmlaccess.sh
JSR 286 portlet events based communications