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

PDK Release 2 (9.0.2 and later)

In the article How to Build a URL-Based Portlet, you learned 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

1. You have successfully installed the PDK framework by following the article Installing the PDK Framework and Samples.
2. You understand the steps required to display a URL-based portlet on a portal page.  Refer to the article Installing the URL-Based PDK Samples.

CREATING AN XML PROVIDER DEFINITION

Using a text editor, create an XML file for your portlet provider. Use the inputParameter tag to specify that the parameters that this portlet will pass to the URL. You may use the sample XML file below (you must change the httpProxyHost and httpProxyPort values to point to your own proxy server and port). Please refer to the article Understanding provider.xml for URL-Based Portlets for an explanation of the required XML tags and their functions.

After you have created the file, save it somewhere on your file system and call it "provider.xml".

<?xml version = '1.0' encoding = 'UTF-8'?> <?providerDefinition version="3.1"?> <provider class="oracle.portal.provider.v2.http.URLProviderDefinition"> <providerInstanceClass>oracle.portal.provider.v2.http.URLProviderInstance</providerInstanceClass> <session>true</session> <proxyInfo class="oracle.portal.provider.v2.ProxyInformation"> <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost> <httpProxyPort>80</httpProxyPort> </proxyInfo> <portlet class="oracle.portal.provider.v2.http.URLPortletDefinition"> <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.v2.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.v2.render.RenderManager"> <contentType>text/html</contentType> <showPage class="oracle.portal.provider.v2.render.http.URLRenderer"> <contentType>text/html</contentType> <pageUrl>http://maps.yahoo.com/py/maps.py</pageUrl> <filter class="oracle.portal.provider.v2.render.HtmlFilter"> <headerTrimTag>&#60;body</headerTrimTag> <footerTrimTag>/body></footerTrimTag> <inlineRendering>true</inlineRendering> </filter> </showPage> </renderer> </portlet> </provider>

DEPLOYING YOUR PROVIDER ON OC4J

To configure and deploy your provider on OC4J, please see the section called "Deploying Your Provider on OC4J" in the article, How to Build a URL-Based Portlet.

SPECIAL OPTIONS

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

• Mandatory Parameters.  Parameters declared in the inputParameter tag can be mandatory.  If any mandatory parameter has not already been given a value by the user, then this message appears in the portlet "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.v2.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.  Parameters can be given default values in provider.xml.  If the portlet does not receive any parameters through the HTTP request, the default parameter value is used.  Use the value tag for this purpose.  For example,

        <inputParameter class="oracle.portal.provider.v2.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 is 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.   For example,

        <showEdit>true</showEdit>
        ...
        <inputParameter class="oracle.portal.provider.v2.URLPortletParameter">
           <name>csz</name>
           <isMandatory>true</isMandatory>
           <displayName>What location do you want a map for (City, State or Zip)?</displayName>
        </inputParameter>
        ...
        <editPage>/htdocs/yahoo/edityahoo.jsp</editPage>
        ...
        <personalizationManager class="oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager">
           <dataClass>oracle.portal.provider.v2.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:

1. Portlet page parameters received through the HTTP request.
2. Default values specified in provider.xml.
3. Customized parameter values.

• Qualified Parameters.  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 are affected by the parameters sent by any of the parameter passing URL-based portlets.

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 URL-based portlets:

• A Primer on URL-Based Portlets

• Understanding the PDK Runtime for URL-Based Portlets

• Understanding the provider.xml for URL-Based Portlets

Revision History:

• January 2002