Oracle9iAS Portal Developer Kit (PDK)
An Overview of Parameters and Events

Introduction

When you build web pages, it is a common requirement that portlets talk to each other. On Oracle9iAS Portal pages, portlets can pass parameters to other portlets on the same page or different pages and thus communicate with them.  Oracle9iAS Portal provides functionality for passing parameters between your portlets and using events to pass information to portal pages.  For example, you may want user information entered via one portlet to drive the content of another portlet or many portlets on the same page or different pages and this can be achieved by passing parameters and using events.

Imagine a scenario where an employee types her employee number into a portlet and after hitting Submit, all portlet display sales information for her entire team over a number of portlets on a page.  Imagine another scenario where an employee types his number into a portlet and selects one of the following radio buttons:  1) Expense Reporting 2) Personal Information 3) Payroll 4) Time Reporting.  The employee selects "Payroll" and is sent to the payroll page where they can see payroll information pertaining only to them.  With parameters and events, you can:

• pass parameters to the same portlet.

• pass parameters from one portlet to another.

• pass parameters and events from one portlet to multiple portlets on multiple pages.

This article provides a brief description of the features and benefits between the two styles of parameter passing.  With Oracle9iAS Portal, there are two main choices for parameter passing:

• Parameters and Events

• Portlet Parameters for URL-based Portlets

Parameters and Events

Oracle9iAS Portal Release 2 (9.0.2 and later) and the PDK introduce the concepts of page parameters, public portlet parameters, and events to allow portlet developers to produce reusable Java portlets and to allow page designers to construct reusable pages. These new features provide a well-defined data input interface for portlets and pages and also provide a well-defined page navigation mechanism. Using parameters and events, page designers can pull together portlets that have been built by someone else and include them in any of their pages.

Oracle9iAS Portal did not previously provide a clear distinction between a portlet’s implementation details and the context in which the portlet was being used on a page. The work of the page designer and the portlet designer was a collaborative effort that required semantically rich portlets to be custom tailored for each different scenario. For example, when designing a portlet that linked to another page, the portlet designer would have had to use hard-coded URLs that referenced the target page. The result was a portlet that worked for the situation for which it was designed but was not reusable.

In Oracle9iAS Portal, the reusability made possible by parameters and events allows the portlet developer and page designer to work independently of each other. A portlet developer can quickly design a public interface for data input and page navigation and can then spend the bulk of his time concentrating on the internal implementation details. Using the declared public interface, the page designer can control what data is sent to the portlet and can control the details of page navigation.

The following picture shows an enterprise portal where the parameter portlet (highlight in red) drives content to other portlets on the page.

The key benefits of Parameters and Events are:

• A page designer can tailor the data inputs, data outputs, and page navigation behavior for each instance of a portlet added to a page.
• A portlet developer can build fewer portlets, can concentrate more on the internal logic of each, and can leave the details of interaction with a page and other portlets to the page designer.
• A portal user can customize a page's data input values.
• Custom portlets exposed as Web providers can communicate with portal components such as portal forms, reports, charts, etc. all through the page UI.

For more information on building portlets using parameters and events review the following articles:

• A Primer on Portlet Parameters and Events
• Adding Parameters and Events to Portlets
• Designing Pages Using the Sample Event Web Provider
• Portlet Reusability Based on the Sample Event Web Provider
• Sample:  Sample Event Web Provider

Portlet Parameters for URL-Based Portlets

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.

Using URL-Based portlets within the PDK, you can pass parameters through the UI for such sites as www.search.com.  Simply enter information into a declarative XML provider defiintion file (provider.xml) such as URL and parameter names and the PDK automatically creates the forms needed to pass information to 3rd party websites. 

For example, www.search.com uses a parameter "q" to associate with the search value entered by users on their web site. 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 figure below shows the default form provided by the PDK and the results page displayed below the form.  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.

From the provider.xml, you can set the parameter portlet to only display the results portlet once the value has been entered.  For example, a user types "Oracle" into the textbox for www.dictionary.com.  Upon hitting Submit, the user only sees the results from dictionary.com.  This enables page designers to display results portlets from 3rd party websites such as financial news or stock information. 

The picture shown below 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.

Key benefits

• For URL-based portlets, the PDK provides a platform for page designers to control portlet behavior through parameters.
• Parameters are declared in XML provider definition files (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 on portlet parameters for URL-based portlets review:

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

 

Revision History:

Revision No Last Update