Understanding Portal Page and Portlet Parameters in PDK-URL Services

Oracle9iAS Portal Developer Kit
Understanding Portlet Parameters for URL-Based Portlets

PDK Release 2 (9.0.2 and later) - URL-Based

When building URL-based portlets, you can pass portlet parameters to the URL's you invoke as portlets. Portlet parameters give you more control over the behavior of your portlets. For example, using portlet parameters, you can provide a query string to a portlet returning content from a site like www.search.com.

This article explains how to configure and use portlet parameters in your URL-based portlets.

DECLARING PORTLET PARAMETERS

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

<portlet class="oracle.portal.provider.v2.http.URLPortletDefinition">
<id>3</id>

<name>MandatoryParamterPortlet</name>

<title>MandatoryParamterPortlet</title>

<description>Mandatory Parameter Portlet</description>

<timeout>30</timeout>

<timeoutMessage>Mandatory Parameter Portlet timed out</timeoutMessage>

<acceptContentType>text/html</acceptContentType>

<showEdit>false</showEdit>

<showEditToPublic>false</showEditToPublic>

<showEditDefault>false</showEditDefault>

<showPreview>false</showPreview>

<showDetails>false</showDetails>

<hasHelp>false</hasHelp>

<hasAbout>false</hasAbout>

<passAllUrlParams>true</passAllUrlParams>

<inputParameter class="oracle.portal.provider.v2.URLPortletParameter">

    <name>q</name>

    <displayName>Search search.com for </displayName>

    <value>JAVA</value>

    <isMandatory>true</isMandatory>

</inputParameter>

<renderer class="oracle.portal.provider.v2.render.RenderManager">

    <contentType>text/html</contentType>

    <showPage class="oracle.portal.provider.v2.render.http.URLRenderer">

      <contentType>text/html</contentType>

      <charSet>ISO-8859-1</charSet>

      <pageUrl>http://www.search.com/search</pageUrl>

      <filter class="oracle.portal.provider.v2.render.HtmlFilter">

        <headerTrimTag><body></headerTrimTag>

        <footerTrimTag></body></footerTrimTag>

        <inlineRendering>true</inlineRendering>

      </filter>

    </showPage>

    <editPage class="oracle.portal.provider.v2.render.http.URLEditRenderer"/>

</renderer>

<personalizationManager class="oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager">

    <dataClass>oracle.portal.provider.v2.URLPersonalizationObject</dataClass>

</personalizationManager>

</portlet>

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 which is false by default. Indicates not to show the portlet if this parameter is not received.

The example shown here uses a search engine URL. "q" is the name of the parameter used by this URL to indicate the string to be searched.

The specified page URL is http://www.search.com/search. After the portlet receives the parameter, it appends the parameter name-value pair to the URL and the URL then uses the parameter value to extract contents.

After appending the parameter the URL becomes http://www.search.com/search?q=JAVA

The second section shows how to add customization functionality to a URL-based portlet.

PROVIDING PARAMETER VALUES

After the parameters have been declared in the provider.xml file, values for these parameters can be provided through the UI provided within the portlet at runtime. The following figure shows how it can be done:

The red box indicates the form within the portlet that can be used for providing values to portlet parameters. Parameters can be submitted through either the GET or POST method. GET method parameters can be passed by using the UI provided or by appending parameter values directly 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 data source. 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 appears next to the parameter name. This parameter Edit screen is created automatically by the PDK based on provider.xml parameter information.

CUSTOMIZING PORTLET PARAMETERS

Portlet parameters can be customized through the Edit screen of the portlet. Various customization options are explained below:

The picture shown here is a typical customization screen for a URL-based portlet. Using this screen you can set the portlet title, edit parameter information, and decide whether you want to qualify parameters.

By qualifying a parameter you are confining its reach to the portlet which declares it. Though this parameter is submitted to all portlets through an HTTP request header, the parameter is filtered based on a hashing technique. Using portlet ID, provider ID and portlet reference, a unique ID is created which distinguishes a portlet parameter as particular to a specific instance of a portlet. This is useful when there are multiple portlets on the same page and only one of the portlets should be affected.

For URL-based portlets, the PDK looks for parameter values in the following order: from the HTTP request header, from the portlet's customized parameter value, and then from the default value provided by provider.xml. If it cannot find a parameter value from any of the above locations and the parameter is marked as mandatory, an error message is shown to the user to provide a parameter value. 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 and needs user authentication information in order to identify him/her. Without this parameter, the portlet cannot show anything.

The following picture shows the Error Message screen that is displayed when any mandatory parameters are missing:

Summary

For URL-based portlets, the PDK provides a platform for page designers to control portlet behavior through parameters.
Parameters must be declared in 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
April 2002