This article explains the portal page as well as portlet parameters and how they can be configured and used in PDK-URL Services. It describes in detail the different types of parameters available and their how they can be used. Portlet parameters give the page designer more control over the behavior of portlets in a page.

Portlets are required to register their parameters through provider definition file (provider.xml). These are called public parameters which will be displayed to the page designer in order to assign values to them. Private parameters are used for internal tracking. Pages may declare parameters. When a portlet is placed on a page, the declared page parameters are be passed as values to the portlet parameters. A page parameter may have a default value, which may be specified in provider.xml. During page customization, a page parameter's default value may be customized. If a page parameter is passed in the HTTP request to display the page, this value takes precedence. If it is not passed, then the value will be determined from the customized value, and subsequently the default value.

The following sections will explain the different types parameters and how to declare them using provider.xml.

Registering portlet parameters

The following picture depicts how parameters can be specified in provider.xml.

The first section shows how parameters can be declared through the inputParameter tag. It has several child tags to define its attributes. name : Mandatory tag used which indicates the parameter name to be used in FORM submission. displayName : Optional tag. In many cases name of the parameter will not be very meaningful. Display name fills this gap. This name will be shown to the user in the rendered portlet while name will still be used while submitting the FORM. If no value is specified, name of the parameter will be displayed. value : Optional tag. Pre-populated value for this parameter. If the portlet doesn't receive this parameter through HTTP request or customized parameter list, it will be used as default. isMandatory : Optional tag by default which is false. Indicates not to show the portlet is this parameter is not received. The example shown here uses a search engine URL. "q" is the name of the parameter, understood by this server and used to indicate the string to be searched. Page url specified is http://www.search.com/search. After the portlet receives the parameter, it appends the parameter name-value pair to the URL and it will be used for extracting contents. After appending the parameter it becomes http://www.search.com/search?q=JAVA The second section shows how to add customization functionality to a PDK-URL Services portlet.

Portal page parameters

As the name suggests, these parameters are available to all portlet instances present on a page. Parameter declarative information comes from provider.xml. Values for these can be supplied through the UI provided. The following figure shows how it can be done:

The highlighted portion can be used for providing values to portlet parameters. Observe that the parameter information is coming directly from provider.xml. Parameters can be submitted through either the GET or POST method. GET method parameters can be passed using either the UI provided, or directly appended to the URL. Example: If http://my.portal.com/servlet/page?paramlist is the portal page URL, the user can directly append parameters to the URL. After adding parameters it looks like this: http://my.portal.com/servlet/page?paramlist&q=oracle Where q = name of a registered parameter This approach is useful if you want to create portlet links based on values fetched from a datasource. Lets say a portlet has Username and Password as registered parameters and these values come from a database. These values can be programmatically appended to the page URL to create personalized portlets.   If the parameter is a mandatory one, then a (*) character is used to indicate the same. This parameter Edit screen is created automatically by PDK-URL Services based on provider.xml parameter information.

 

Customizing portlet parameters

Portlet parameters can be customized through the Edit screen of the portlet. Again the parameters are the ones registered through provider.xml. Various customization options are explained below :

The picture shown here is a typical customization screen for a PDK-URL Services portlet. Using this we can set the portlet title, edit parameter information and specify qualify parameters. By qualifying a parameter we mean confining its reach to the portlet which declares it. Though this parameter is submitted to all portlets through a HTTP request header, they are filtered based on a hashing technique. Using portlet ID, provider ID and portlet reference, a unique ID is created which distinguishes a portlet from other instances.  This is useful when there are multiple portlets in the same page and other portlets should not be affected. PDK-URL Services first looks for portal page parameters, followed by customized parameters and then pre-populated values respectively. If it cannot find any of the above and the parameter is marked as mandatory, an error message is shown to the user to provide the same. This feature is useful in cases where a portlet is abstract without any parameters. A practical example would be a portlet which shows some user information. It needs user authentication information in order to identify him/her. Without this parameter, the portlet cannot show anything. This is the Error Message screen that is displayed when any mandatory parameters are missing:

Summary

• PDK-URL Services provides a platform for page designers to control portlet behavior through parameters.
• Parameters must be registered through provider.xml.
• Page designers can use portal page parameters, customized portlet parameters and published portlet parameters according to their needs.
• Portlet parameters can be qualified to make them private to the portlet which registered them. This is useful when multiple portlets are present on a single page and the other portlets must not be affected.
• If required, mandatory parameters can be specified. If parameter information is not passed to the portlet, an error message is rendered.

For more information and to implement an example, follow the article How to Build a URL-Based Portlet that Uses Parameter Passing.

Revision History:

• November 2001