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

Introduction

• 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.

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 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

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

PORTLET EVENTS AND EVENT PARAMETERS

• 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.

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

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 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.

• 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.

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

• 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.

• 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.

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