How to Build a URL-Based Portlet that Uses Parameter Passing

Oracle9iAS Portal Developer Kit
How to Build a URL-Based Portlet that Uses Parameter Passing

In the article How to Build a URL-Based Portlet, you learnt how to create a portlet that displayed the content of a URL-based application. The example used in that article was Google.com. Since many URL-based applications (including Google.com) can take in parameters (through GET or POST), you may want to pass parameters to your URL-based application. With PDK-URL Services, you can pass parameters to your URL-based portlet. The values for these parameters can be provided by the provider XML file, or by the portal user at runtime.

This article describes how to build a URL-based portlet that handles parameter passing. It extends the sample found in the article How to Build a URL-Based Portlet. Instead of using Google.com as the URL-based application, this article uses Yahoo! Maps (http://maps.yahoo.com).

ASSUMPTIONS

You have successfully installed the PDK-Java runtime and samples by following the article Installing the PDK-Java Framework and Samples.
You have successfully installed the PDK-URL Services runtime and samples by following the article Installing the PDK-URL Services Samples
You have successfully installed the Google.com URL-based portlet by following the article How to Build a URL-Based Portlet.

CREATING AN XML PROVIDER DEFINITION

This section explains how to create an XML provider definition for your URL-based portlet provider.

Using a text editor, create an XML file for your portlet provider.

The following sample is the same as that found in the article How to Build a URL-Based Portlet. However, for illustration purposes, the sample here has replaced Google.com with the URL for Yahoo! maps (http://maps.yahoo.com). In addition, it uses the inputParameter tag to specify the parameters that this portlet can receive. Please refer to the article Understanding provider.xml for PDK-URL Services for an explanation of the required XML tags and their functions.

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<?providerDefinition version="2.0"?>
<provider class="oracle.portal.provider.v1.http.URLProvider">
   <session>true</session>
   <proxyInfo class="oracle.portal.provider.v1.http.ProxyInformation">
      <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost>
      <httpProxyPort>80</httpProxyPort>
   </proxyInfo>
   <portlet class="oracle.portal.provider.v1.http.URLPortlet">
      <id>1</id>
      <name>Parameter Portlet</name>
      <title>Parameter Portlet</title>
      <description>Display Yahoo! Maps as a portlet.</description>
      <timeout>100</timeout>
      <timeoutMessage>Timed out waiting for Yahoo! Maps Portlet.</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>
      <inputParameter class="oracle.portal.provider.v1.URLPortletParameter">
         <name>csz</name>
         <isMandatory>false</isMandatory>
         <displayName>What location do you want a map for (City, State or Zip)?</displayName>
      </inputParameter>
      <renderer class="oracle.portal.provider.v1.RenderManager">
         <contentType>text/html</contentType>
         <showPage class="oracle.portal.provider.v1.http.URLRenderer">
            <contentType>text/html</contentType>
            <charSet>ISO-8859-1</charSet>
            <pageUrl>http://maps.yahoo.com/py/maps.py</pageUrl>
            <filter class="oracle.portal.provider.v1.http.HtmlFilter">
               <headerTrimTag>&lt;body</headerTrimTag>
               <footerTrimTag>/body></footerTrimTag>
               <inlineRendering>true</inlineRendering>
            </filter>
         </showPage>
      </renderer>
   </portlet>
</provider>

Save the file as "provider.xml", making sure it overwrites the provider.xml file you created in the article How to Build a URL-Based Portlet.

ADDING THE URL-BASED PORTLET TO A PAGE

You should have already configured and registered the Google.com
portlet provider according to the article How to Build a URL-Based Portlet.

You may reuse this provider and simply rename it to reflect the changes made above. To do this, you need to:

Stop and restart the Oracle HTTP Server
Edit the portlet provider via the Edit Provider screen, i.e. change the name from Google.com to "Yahoo! Maps" or "Paramater Passing Portlet Provider".

You are now ready to add the parameter passing portlet to a page.

SPECIAL OPTIONS

The parameter passing feature of PDK-URL Services provides a variety of options for passing parameters to your URL-based portlets.

Mandatory Parameters. The parameters declared in the inputParameter tag can be mandatory. If any mandatory parameter has not already been given a value by the user, then a message will appear in the portlet saying "Please provide mandatory provider information". Once the user submits a parameter value, the portlet passes the parameter to the URL and render the contents of the resulting submission. This behavior differs from non-mandatory parameters. If a non-mandatory parameter has not already been given a value by the user, the URL will still be displayed (along with the parameter submission form). Use the isMandatory tag to control whether a parameter is mandatory. For example,
```
      <inputParameter class="oracle.portal.provider.v1.URLPortletParameter">
         <name>csz</name>
         <isMandatory>true</isMandatory>
         <displayName>What location do you want a map for (City, State or Zip)?</displayName>
      </inputParameter>
```

Default Parameter Values. The parameters can be given default values in the provider.xml. If the portlet does not receive any parameters through the HTTP request, the default parameter value will be used. Use the value tag for this purpose. For example,

      <inputParameter class="oracle.portal.provider.v1.URLPortletParameter">
         <name>csz</name>
         <isMandatory>false</isMandatory>
         <displayName>What location do you want a map for (City, State or Zip)?</displayName>
         <value>94065</value>
      </inputParameter>

Customization. Parameter values can be customized in the portlet's edit mode. When a parameter value is specified in the portlet's edit mode, the value is persistent for the user. So the parameter supplied URL will be displayed for as long as the user does not change the parameter value (i.e., the user can refresh the page, logout/login without losing the parameter value). This feature is useful for URL-based portlets that might use parameter passing for single sign-on to external applications. To enable customization of portlet parameters, use the showEdit tag along with the editPage tag and the personalizationManager tag to specify that the portlet will have a customize mode. The class attribute of the editPage tag should be set to oracle.portal.provider.v1.http.URLEditRenderer, and the dataClass sub-tag of the personalizationManager tag should specify oracle.portal.provider.v1.http.URLPersonalizationObject. For example,
```
      <showEdit>true</showEdit>
      ...
      <inputParameter class="oracle.portal.provider.v1.URLPortletParameter">
         <name>csz</name>
         <isMandatory>true</isMandatory>
         <displayName>What location do you want a map for (City, State or Zip)?</displayName>
      </inputParameter>
      ...
      <editPage class="oracle.portal.provider.v1.http.URLEditRenderer">
      ...
      <personalizationManager class="oracle.portal.provider.v1.FilePersonalizationManager">
         <dataClass>oracle.portal.provider.v1.http.URLPersonalizationObject</dataClass>
         <useHashing>true</useHashing>
      </personalizationManager>
```

Whenever default parameter values or customization of parameter values are used, parameter values are determined by the following order of precedence:

Portlet page parameters received through the HTTP request.

Default values specified in provider.xml.

Customized parameter values.

Qualified Parameters. The parameters provided to URL-based portlets can be passed to a single URL-based portlet instance or to all of the portlets on the page. If the customization option is turned on, the user can check the box marked "Use Qualified Parameters" to ensure that parameters are passed only to the initiating portlet. If this box is left unchecked, all portlets will be affected by the parameters sent by any of the parameter passing URL-based portlets.

For more information and illustrated examples, see Understanding Portal Page and Portlet Parameters in PDK-URL Services.

Now that you have successfully added parameter passing to your URL-based portlet, please look for other portlet development articles that describe how to add extra features to your portlet, including single sign-on to external URL-based applications, HTML and XML filtering and more.

Here are some reference articles to help you better understand the architecture and technical details of PDK-URL Services:

A Primer on PDK-URL Services

Understanding PDK-URL Services Runtime

Understanding provider.xml for PDK-URL Services

Revision History:

November 2001