# Oracle9iAS Portal Developer Kit (PDK)
A Primer on Portal Parameters & Events

Last Update: | July 11, 2003
Status: | Production
Version: | PDK Release 2, (9.0.2 and later)

## Introduction

Oracle9iAS Portal 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 key benefits of this functionality 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.

## PARAMETERS

Parameters are name/value pairs determined at runtime from a combination of the page URL and page/portlet configuration data (entered at design time) stored in Portal.
Oracle9iAS Portal introduces three types of parameters - public portlet parameters, page parameters, and event parameters. These new parameters are exposed to the page designer through the user interface. Oracle9iAS Portal continues support for private portlet parameters that enable portlet developers to manage the internal state of portlets. “Private” means that only the portlet developer has knowledge of the parameters and they are not exposed to the page designer. Note that private portlet parameters were available in previous releases of Oracle Portal but were referred to as qualified portlet parameters.

### PUBLIC PORTLET PARAMETERS

Public portlet parameters allow the portlet developer to declare a public data input interface for the page designer to use. After placing a portlet on a page, the page designer may map different data input sources to the public portlet parameters. At run-time, the portlet will receive the values from the data source that the page designer specified at design time. The page designer thus has complete control over the data source while the portlet developer has complete control over how that data is used once transmitted to the portlet.

In general, a portlet developer can programmatically manipulate parameters used with only Java portlets exposed through a web provider, and not PL/SQL portlets exposed through database providers. However, when you build Portal DB Provider components, such as reports or charts, using the Oracle Portal 9.0.2 user interface, you can define public portlet parameters that can be mapped to page parameters. Since Portal DB Provider components are created through the Oracle Portal user interface and support a fixed selection of pre-defined public portlet parameters, the PL/SQL portlet developer will not be programmatically manipulating these parameters.

Public portlet parameters are declared in provider.xml and are visible to the page designer via the Parameters tab of the Page Properties. The page designer can view but not modify public portlet parameter definitions.

In Figure 1, the Stock Quote Portlet has a public portlet parameter stockId that is used to look up the stock price. The value that is assigned to stockId is not controlled by the portlet developer but by the page designer through the Parameters tab of Page Properties.

Figure 1 The Stock Quote Portlet uses the public portlet parameter stockId to determine which stock quote to display.

Figure 2 By looking at the Parameters tab of Page Properties, the page designer can see that the Stock Quote Portlet has one public portlet parameters, stockId. The page designer has assigned the constant value 'ORCL' to stockId.

The page designer can integrate the portlet into a page knowing only the declared parameters and the documented behavior of the portlet and has no need to be aware of the details of the implementation. Likewise, the portlet developer can simply declare a public data input interface using public portlet parameters, can document the behavior of the portlet, and then does not have to worry about on which exact pages the portlet will be placed.

### PAGE PARAMETERS

Page parameters allow the page designer to declare a public data input interface to a page. This interface can then be used to transmit data from page to portlet in a standardized method directly supported by Portal.

The page designer creates page parameters during page design time through the Parameter tab of Page Properties. Page parameters are not declared in a configuration file as public portlet parameters are in provider.xml - they are controlled and accessed solely through the user interface by the page developer . The portlet developer does not have access to page parameters.

Figure 3 The page designer has already created a page parameter param1 with the default value '2.71828' and is about to create a second page parameter param2.

When a page is rendered, its page parameters are assigned values from three potential sources in the following order of precedence:

1. URL parameter values.
2. User customization values entered in the Parameters tab of the page's Customize Parameters tab.
3. Default values entered in the Parameters tab of Page Properties.

### PUBLIC PORTLET PARAMETER MAPPING

When a page is rendered at run-time, public portlet parameters are assigned values by Oracle9iAS Portal. Specific values or classes of values are chosen by the page developer through the Parameters tab of Page Properties.

Figure 4 The public portlet parameter stockId has been mapped to take on the value of page parameter param1.

A public portlet parameter can be mapped to one of the following:

- Constant value, eg. 15.00
- System value, eg. USER_NAME
- Page parameter, e.g. param1
- Null

Note that multiple public portlet parameters can be mapped to the same page parameter.

Figure 5 Three different portlets each have their one public portlet parameter mapped to the stockId page parameter.

### PORTLET EVENTS AND EVENT PARAMETERS

Portlet events model the page navigation and the data output of a portlet when a user clicks on a link or submits a form. Portlet events are declared in provider.xml and have the following properties:

- Name, eg. Search
- Description, eg. This is a simple search portlet
- A set of parameters that will make up the “payload” of the event at runtime, eg. searchText, numResults

Portlet events and portlet event parameters can be used with Java portlets exposed through a web provider. They are not currently supported for PL/SQL portlets exposed through a database provider.

Figure 6 The Search Portlet declares a Search event with two event parameters and a Cancel event. The displayed portlet title is actually a public portlet parameter input.

### PORTLET EVENT MAPPING

Portlet events are published by the portlet developer so that the page designer can control the details of page navigation and data output from a portlet. To use events, the page designer views a portlet’s events through the Events tab of the Page Properties and maps an event to display a particular page when the event is fired by the user. “Firing” an event means that the user performs an action such as clicking on a link or submitting a form. An unmapped event, i.e. one with no target page specified, will simply redisplay the current page when it is fired.

Figure 7 The page designer has mapped the Search event so that when it is fired then page1 is displayed. Page1's page parameters param1 and param2 take on the value of the Submit events searchText parameter and the system variable COMPANY_NAME, respectively.

The page designer can tailor page navigation for a portlet knowing only the declared events and event parameters and does not need to be aware of the details of the implementation. Likewise, the portlet developer can declare events and event parameters, and provide support for them when constructing links or forms, and then does not need to worry about what page the portlet is being placed on.

Figure 8 shows how each instance of a single portlet can have a unique set of data input and page navigation all created by the page designer.

Figure 8 The Search Portlet has been added twice to the same page with each portlet instance having a different displayed title. The Search event has been mapped to different pages for each of the instances. The Cancel event takes the user back to a Home Page.

### Private Portlet Parameters

Private portlet parameters allow the portlet developer to keep track of the internal state of a portlet when following a link back to the current page. Private portlet parameters are only required for internal state and are not available to the page and thus are not declared in provider.xml. Instead, they are defined and accessed only in the portlet implementation code.
The following example illustrates how a Record Viewer Portlet can use the private portlet parameter currRecord to keep track of the current record to be displayed. When first displayed, currRecord is null which the portlet interprets as meaning that the first record should be displayed. When the user presses Next, the page is redisplayed with currRecord passed on the URL and given a qualified name and a new, incremented value.

Figure 9 After pressing Next, the page is redisplayed with a new value for currRecord passed on the URL.

Each private portlet parameter that is passed on the URL must be uniquely qualified so that the following two cases are handled properly:

- The same portlet has been added twice to the same page.
- Two different portlets that have an identically name private portlet parameter have been added to the same page.

Figure 10 demonstrates an example of the first case - the Record Viewer Portlet has been added twice to the same page. Using a qualified private portlet parameter means that each instance of the Record Viewer Portlet can independently update its own copy of the private portlet parameter currRecord. Portal recognizes the qualifying identifier that is prepended to each copy of currRecord on the URL and sends the correct parameter value to the correct portlet. Unqualified portlet parameters are supported by Portal but should only be used in certain cases as outlined in the section ‘The passAllUrlParams Flag - Support for Old Style Parameter Passing’.

Figure 10 Each private portlet parameter on the URL is qualified by a prepended identifier to avoid sending the wrong data to the wrong portlet.

One important distinction between public and private portlet parameters is that the portlet developer is responsible for private portlet parameter management and must ensure that the correct value is being sent to the correct portlet by calling the correct PDK APIs. Public portlet parameters are handled by Portal and the portlet developer does not have to worry about issues involving multiple instances of the same portlet or involving two portlets with conflicting public portlet parameter names.

## Advanced Topics

### PAGE NAVIGATION AND PRESERVATION OF PARAMETERS

When a portlet renders a link or a form, the underlying URL may contain private portlet parameters, event parameters, page parameters, and Portal system parameters. If the URL for the link or form represents a simple navigation, i.e. no events involved, then the URL is simply used by the browser to display the target page and whatever parameters were placed on the URL will be passed to that page. If the URL represents an event navigation then Portal takes this URL, evaluates what event is being fired, and then decides which page to display and which parameters to place on the target page URL. For both the simple navigation case and the event navigation case, the underlying APIs used by the portlet developer to construct the URLs will properly manage parameter passing.
There are a number of rules to remember when analyzing what page parameters and private portlet parameters will have their values preserved when following a link or firing an event from a portlet:

- A page parameter URL value is preserved when

- Following a simple link to the same page (simple means no events are involved).
- Submitting a simple form to the same page.
- Firing an unmapped event (the current page is redisplayed when an event is unmapped).
- Firing an event that has the same page as its target and the page parameter has a null mapping on the Events tab of Page Properties

- A page parameter URL value is not preserved when

- Firing an event that has the same page as its target and the page parameter has a non-null mapping on the Events tab of Page Properties (the new page parameter URL value is taken from that mapping).

- A qualified private portlet parameter URL value is preserved when

- Following a simple link to the same page from another portlet instance, i.e. a portlet instance that does notown that qualified private portlet parameter.
- Submitting a simple form to the same page from another portlet instance.
- Firing an unmapped event from another portlet instance.
- Firing an event mapped to the same page by following a link from another portlet instance.
- Firing an event mapped to the same page by submitting a form from another portlet instance.

- A qualified private portlet parameter URL value is not preserved when

- Following a simple link to the same page from the owning portlet instance, i.e. the portlet instance that owns the qualified private portlet parameter.
- Submitting a simple form to the same page from the owning portlet instance.
- Firing an unmapped event from the owning portlet instance.
- Firing an event mapped to the same page by following a link from the owning portlet instance.

- An unqualified portlet parameter URL value is never preserved.

### THE passAllUrlParams FLAG: OLD-STYLE PARAMETER PASSING AND TRANSIENT URL PARAMETERS

Previous releases of Oracle9iAS Portal passed all URL parameters to every portlet on a page during the rendering of that page. In Oracle9iAS Portal, the default behavior of Portal will be to only pass to a portlet those parameters that it requires: the portlet’s public and private parameter values. A new flag, the passAllUrlParams flag, can be specified in a portlet’s declaration in provider.xml to do one or both of the following:

- Indicate that old-style parameter passing should be performed for that portlet.
- Make use of the transient nature of unqualified portlet parameters.

Old-style parameter passing for a portlet means that, when a page is rendered, that portlet will receive all parameter values from the page request URL plus all PDK system parameters.
Transience of unqualified portlet parameters refers to the fact that unqualified portlet parameters are never preserved when following a link to the same page. Read the following section for how transient unqualified portlet parameters can be used to implement one-time-only portlet actions.
If the passAllUrlParams flag is set to true then the following values are passed to a portlet:

- The PDK system parameters such as Provider ID, Portal ID, and the Page URL

- All parameters from the page request URL except for Portal system parameters

  - Portal system parameters include parameters like pageid, _dad, and _schema.

  - Qualified private portlet parameter will be passed as they appear on the URL - qualifying prefixes will not be removed.

If the passAllUrlParams flag is set to false, the default case, then the following values are passed to a portlet:

- The PDK system parameters such as Provider ID, Portal ID, and the Page URL

- All public portlet parameters for this portlet

- All private portlet parameters for this portlet with their qualifying prefixes removed.

For an example of how to use the passAllUrlParams flag review the article, Adding Parameters and Events to Portlets.

### PORTLET ACTIONS

A portlet developer will often have a requirement to implement a portlet that performs an action that should be performed once and only once per user request. An example would be a Bank Account Portlet that transfers money when the user presses on the Transfer button. Subsequent redisplaying of the page should not repeat the transfer of money if the user does not explicitly press on the Transfer button.

This type of behavior can be implemented by setting the passAllUrlParams flag to true in the portlet’s declaration in provider.xml and by using unqualified portlet parameters to pass a value indicating that an action should be performed. Setting passAllUrlParams to true will cause the portlet to be passed all URL parameter values including unqualified portlet parameters. The portlet developer can then create and use unqualified portlet parameters to have a portlet send messages to itself that an action must be performed. The transient nature of unqualified portlet parameters, i.e. they won’t be preserved when the page is redisplayed again, means that the action will be performed once and only once per user action.

Figure 11 shows the Bank Account Portlet with the Record Viewer Portlet on the same page. passAllUrlParams is set to true for the Bank Account Portlet and set to false for the Record Viewer Portlet The Bank Account Portlet receives all URL parameters while the Record Viewer Portlet only receives only its own public and private portlet parameters.

Figure 11 The unqualified portlet parameter ‘action’ is used to signal to the Bank Account Portlet that the transaction should be performed.

Note that the Record Viewer Portlet always receives its own private portlet parameters with the qualification prefix removed while the Bank Account Portlet always receives URL parameters as they are. The user presses Transfer and the page is redisplayed with an unqualified portlet parameter action being used to indicate that the transaction is to be performed. The private portlet parameter curr is preserved on the URL and is sent to both portlets.

Figure 12 shows what happens when the user subsequently presses Next on the Record Viewer Portlet. An incremented value for curr is placed on the URL and is sent to both portlets. Importantly, the value for action is not preserved meaning that when the page is redisplayed, the Bank Account Portlet transaction is not repeated which is the desired behavior.

Figure 12 The qualified private portlet parameter ‘curr’ is used to update the Record Viewer Portlet. The unqualified portlet parameter ‘action’ does not have its value preserved on the URL.

Note that if the Bank Account Portlet were to be added twice to the page then the portlet developer would have to name the unqualified portlet parameter action differently for each instance to avoid having the wrong portlet intercept the wrong value. The portlet developer must effectively qualify the private portlet parameter, but as long as the prefix of the private portlet parameter is not ‘_piref’ then Portal will not treat it as a qualified private portlet parameter and will continue to ensure that it is transient.

Future releases of Oracle9iAS Portal will support an integrated, automatic support for transient private portlet parameters.

Revision History:

February 27, 2002

April 24, 2002

Revision History: |
Revision No | Last Update
Created | July 30, 2002
1.0 |

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ | Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 | Copyright and Corporate Info