|
Oracle® Application Server Portal User's Guide
10g Release 2 (10.1.4) B13809-04 |
|
 Previous |
 Next |
|
Oracle® Application Server Portal User's Guide
10g Release 2 (10.1.4) B13809-04 |
|
|
Previous |
Next |
This chapter defines parameters and events as they are used in OracleAS Portal and describes how to use them.
Figure 23-1 Use Parameters and Events to Control Page Information
It includes the following subsections:
Intended Audience
The content of this chapter is intended for users with at least the Manage Content privilege on the pages they will work with. To work with Portal Templates, the Manage Template privilege is required on the page group. If a particular task requires, or can be performed under, different privileges, those privileges will be listed before the steps of that task. For more information on page privileges, see Section B.3, "Page and Tab Privileges".
For page groups, parameters and events are enabled by default. For more information, see Chapter 4, "Working with Page Groups". For information on how to add parameters and events to portlets, see the Oracle Application Server Portal Developer's Guide available on the Oracle Portal documentation page of the Oracle Technology Network at http://www.oracle.com/technology/products/ias/portal/documentation.html.
Two types of objects in OracleAS Portal can use parameters; pages and portlets. A page parameter stores a value for a page and a portlet parameter stores a value for a portlet.
The following sections describes page parameters and portlet parameters and how to use them in OracleAS Portal:
Page parameters accept and store values for a page. Their presence on a page means that page information can be different depending on where the page is called from, or who is viewing the page. For example, you could define a page parameter on a page that displays a stock ticker portlet so that a different portfolio is displayed depending on value of the page parameter. Page parameters can be defined for Standard, Mobile, and Search pages, custom pages that are based on these page types, and navigation pages.
In OracleAS Portal, parameters and events are enabled for page groups, by default. For information on enabling/disabling parameters and events in a page group, see Chapter 4, "Working with Page Groups".
A page parameter gets its value from (in order of precedence):
the URL used to access the page, for example:
http://myportal/mypage?a=1&b=2
Parameters are case-sensitive, so if your parameter name is a, entering a=1 will work, but A=1 will not.
the personalized value of the parameter, as specified by the current user
the default value of the parameter, as specified by the page designer
The following subsections describe how page parameters are used in URL pages and PL/SQL pages:
You can define page parameters for URL pages. The page parameters (and their values) are passed to the location that is specified by the URL page. For example, if the URL page myurlpage points to the URL http://www.yahoo.com/somepage and values are defined for page parameters a and b (a=1 and b=2), this URL is used to access the page in OracleAS Portal:
http://myportal/myurlpage?a=1&b=2
The parameter values are passed to the location specified for the page and this generates the following URL:
http://www.yahoo.com/somepage?a=1&b=2
You can define page parameter for PL/SQL pages. Values for these parameters are passed to bind variables in the PL/SQL code. For example, if the PL/SQL page myplsqlpage contains the PL/SQL statement a:=:param1; and a page parameter is specified named param1 with the value 123 (param1=123), this URL is used to access the PL/SQL page in OracleAS Portal:
http://myportal/myplsqlpage?param1=123
In the PL/SQL code, the bind variable a is assigned the value 123.
Portlet parameters accept and store values for portlets. This means that information displayed in a portlet can be specific to a particular page or user. A portlet's parameters are specified in the file provider.xml.
There are two types of portlet parameter, public and private:
Public portlet parameters are displayed to page designers. This allows page designers to assign appropriate parameter values and make the information displayed in the portlet specific to their page. The page designer can provide a specific value (constant), a system variable (for example, USER), or a page parameter.
To set values for portlet parameters, the page group setting Enable Parameters and Events must be enabled, see Chapter 4, "Working with Page Groups".
Private portlet parameters are used internally by the portlet, for example, to identify the current row displayed, or the current tab displayed. Private portlet parameters are not displayed to the page designer.
For example, a Stock Ticker portlet could have a public portlet parameter (ticker) that accepts a stock symbol as its value. When this portlet is placed on a page, the public ticker parameter is displayed on the Edit Page: Parameters tab. If the page designer sets the ticker parameter to a specific value, such as ORCL, the portlet shows stock information for this company when it is displayed.
Alternatively, the page designer could add a page parameter (for example, symbol) to the page, and pass that page parameter to the portlet parameter. If the page parameter is personalizable, users can set the stock ticker portlet to display stock information for any company they choose.
For information on how to add parameters to your portlets, see the Oracle Application Server Portal Developer's Guide available on the Oracle Portal documentation page of the Oracle Technology Network at http://www.oracle.com/technology/products/ias/portal/documentation.html.
An event is something that happens when a link or button is clicked in a portlet. A portlet's events are specified in the file provider.xml. When a portlet (with events) is placed on an OracleAS Portal page, the page designer can choose what happens when the event occurs. The options are:
Go to another page, and optionally pass values to that page's parameters.
Redisplay the current page.
For information on setting up a portlet event handler for your portlets, see the Oracle Application Server Portal Developer's Guide available on the OracleAS Portal documentation page of the Oracle Technology Network at http://www.oracle.com/technology/products/ias/portal/documentation.html.
Page parameters accept and store values for a page. This means that page information can be different depending on where the page is called from, or who is viewing the page.
In OracleAS Portal you can add page parameters to pages and Portal Templates. When you add page parameters to a Portal Template for pages, the parameters are inherited by every page based on the Portal Template. Page designers can edit the template's page parameters when they edit the template but not when they edit the pages based on this template. When you add parameters to a Portal Template for items, the parameter values become available to every portlet placed on the Portal Template. For more information, see Section 13.1.1, "What Are Portal Templates?".
To add a parameter to a page, or a Portal Template:
Go to the page, or template where you will add a parameter.
Switch to Edit mode.
Click the Properties link next to Page (or Template) in the page toolbar.
Be sure to click the link for the page (or template) rather than the page group.
On the Properties page, click the Parameters tab to bring it forward.
For page groups, parameters and events are enabled by default. If you cannot see the Parameters tab, the Enable Parameters and Events page group setting has been disabled. For more information, see Chapter 4, "Working with Page Groups".
In the Parameter Name field, enter a name for the parameter.
The name is case sensitive and must be unique within the page (or template). The name can contain up to 200 characters. The name can contain only alphanumeric characters (A-Z, a-z, 0-9) and the underscore (_) character. Do not use spaces or other special characters.
Click Add.
The parameter is added to the page (or template) and you can edit its properties in the Page Parameter Properties section.
In the Display Name field, enter a descriptive name for the parameter.
Use to 4000 characters of any kind, including spaces.
(Optional) In the Default Value field, enter the value that you want to have assigned to the parameter if no other value is provided.
This field is available only for Standard and Mobile pages and pages of custom types that are based on the Standard page type.
(Optional) Select Personalizable if you want users who personalize the page (or any page based on this template) to be able to provide their own value for the parameter.
This field is available only for Standard and Mobile pages and pages of custom types that are based on the Standard page type.
This option is not applicable for Portal Template for items.
(Optional) In the Description field, enter a description of the parameter.
If users can personalize the value of this page parameter (Personalizable check box is selected), use the description to provide users with hints or an example of the kind of value to provide for the parameter. The description can contain up to 4000 characters.
This option is not applicable for Portal Template for items.
Click Apply to save your changes and create another parameter, or click OK to save your changes and return to the page or template.
|
Note: If you want to add another parameter before you leave this page, click Apply before creating the next parameter; otherwise, you will lose any changes you made to the first parameter's properties. |
Portlets can accept values for their parameters from page parameters, system variables, or a constants passed from the page. This means that the information displayed within a portlet can be specific to a particular page or user. A portlet's parameters are specified in the file provider.xml.
You can pass values only to portlet parameters on Standard, Mobile, and Search pages, custom pages that are based on these page types, and navigation pages.
In OracleAS Portal you can specify portlet parameter values for a particular page or for a Portal Template. When you specify portlet parameter values for a Portal Template for pages, the values are inherited by every page based on the Portal Template. Page designers can edit the template's parameter values when they edit the template but not when they edit the pages based on this template. When you specify parameters values for a Portal Template for items, they become the default values for items displayed on that template. For more information, see Section 13.1.1, "What Are Portal Templates?".
To pass values to portlet parameters:
Go to the page (or template) that hosts the portlets to which you will pass parameter values.
Switch to Edit mode.
Click the Properties link next to Page (or Template) in the page toolbar.
Be sure to click the link for the page (or template) rather than the page group.
On the Properties page, click the Parameters tab to bring it forward.
For page groups, parameters and events are enabled by default. If you cannot see the Parameters tab, the Enable Parameters and Events page group setting has been disabled. For more information, see Chapter 4, "Working with Page Groups".
The Portlet Parameter Values section lists the portlets that are included on the page and indicates whether those portlets have any parameters.
Click the name of a portlet to expand the portlet and display its parameters. If a portlet does not have any parameters defined, it cannot be expanded in the list.
If you want to show the parameters for all the portlets on the page, click Expand All. However, if a portlet does not have any parameters, you cannot expand it in the list.
For each portlet parameter:
From the input parameter drop-down list, choose:
Null if you do not want to provide a value for the portlet parameter.
Page Parameter to pass the value of one of the page parameters to the portlet parameter.
System Variable to pass the value of a system variable to the portlet parameter. For example, USER_NAME.
Constant to pass a specific value to the portlet parameter.
In the value field or list, choose the page parameter or system variable whose value you want to pass to the portlet, or enter a constant value.
Click OK to save your changes and return to the page or template.
For information on adding parameters to a portlet, see the Oracle Application Server Portal Developer's Guide available on the Oracle Portal documentation page of the Oracle Technology Network at http://www.oracle.com/technology/products/ias/portal/documentation.html.
An event is something that happens when a link or button is clicked in a portlet. A portlet's events are specified in the file provider.xml.
You can set up events only on Standard or Mobile pages or custom pages that are based on the Standard page type. You can also set up events on Portal Templates.
To set up events on a page, or a Portal Template:
Go to the page or template where you will set up events.
Switch to Edit mode.
Click the Properties link next to Page (or Template) in the page toolbar.
Be sure to click the link for the page (or template) rather than the page group.
On the Properties page, click the Events tab to bring it forward.
For page groups, parameters and events are enabled by default. If you cannot see the Events tab, the Enable Parameters and Events page group setting has been disabled. For more information, see Chapter 4, "Working with Page Groups".
Click the name of the portlet you will work with.
If you want to show the events for all the portlets on the page, click Expand All; however, if a portlet does not have any events, you cannot expand it in the list.
Click the event for which you will specify an action.
Select:
Go to Page to display a particular page when the event occurs.
Click the Browse icon and select a page to display from the list provided.
Redisplay Page to refresh the page when the event occurs.
If you want to refresh the current page with new parameter values so they can be passed with an event, choose Go to Page and then choose the name of the current page. If you choose Redisplay Page, the current page is not refreshed with new parameter values (if there are any).
If you selected Go to Page in the previous step, the Page Input section lists any page parameters that are defined for the page. For each page parameter:
From the drop-down list, choose:
Null if you do not want to provide a value for the page parameter.
Event Output to pass the value of one of the portlet event output parameters to the page parameter when the event occurs.
System Variable to pass the value of a system variable to the page parameter when the event occurs; for example, USER_NAME.
Constant to pass a specific value to the page parameter when the event occurs.
In the value field or list, choose the event output or system variable whose value you want to pass to the page parameter, or enter a constant value.
Click OK to save your changes and return to the page or template.
For information on adding events to your portlets, see the see the Oracle Application Server Portal Developer's Guide available on the Oracle Portal documentation page of the Oracle Technology Network at http://www.oracle.com/technology/products/ias/portal/documentation.html.
When an item is assigned to a Portal Template, the item is always displayed within the context of that template. For more information, see Section 13.2.2, "Using Portal Templates with Items".
If the template contains one or more portlets, you can make the content of each portlet dependent on the item being displayed. You can configure items to pass parameter values to the template, and the surrounding portlets can decide whether or not to use the information to generate their content.
For example, consider the Portal Template for items illustrated in Figure 23-2. The center region contains the placeholder item type. The region on the left contains a navigation portlet that displays the navigation links relevant to the item being displayed on the template. On the right there are two portlets, one displaying Related Articles and the other Related Downloads. When an item is displayed with this template, it could pass parameters to the template. The parameters can pass values on to the portlets (Template properties: Parameter tab) such that all three portlets display content that is relevant to the item.
Figure 23-2 Portal Template for Items - Sample Layout
For example, when the item About Oracle 10g.html is displayed on the template, it passes parameters to the other portlets on the page as shown in Figure 23-3. Notice how links in the navigation portlet, related articles, and related downloads are all associated with the item in the center, that is, Oracle Database 10g.
Figure 23-3 Portal Template for Items - Sample Item
If you want portlets, placed on Portal Template for Items, to display information relevant to the item currently being displayed with the template, here is an overview of the steps required:
Design a suitable template for your items, see Section 13.2.2.1, "Creating Portal Templates for Items".
Ensure that the template contains a placeholder item type and the portlets to which your items will pass parameter values.
Add page parameters to the Portal Template and assign default parameter values to pass to portlets on the template, see Section 23.3, "Adding a Parameter to a Page or Portal Template".
Define parameter values for items assigned to the Portal Template, see Section 23.6.1, "Defining Parameter Values for Items Displayed on a Portal Template".
If a Portal Template for items contains page parameters, you can specify parameter values for each item that is assigned to the Portal Template. When the item is displayed on its designated Portal Template, the parameter values are passed to the portlets on the template, controlling the portlet content that is displayed.
To define parameter values for items assigned to a Portal Template:
Go to the page or template where you will add a parameter.
Switch to Edit mode.
Click the Page: Properties link in the toolbar at the top of the page.
On the resulting page, click the Items tab to bring it forward.
Select Use this portal template and then select the required Portal Template for the items on this page.
Page parameters for the selected template are displayed beneath this radio button (under Template Input). If no parameters are defined, you cannot assign parameter values. See Section 23.3, "Adding a Parameter to a Page or Portal Template".
From the drop-down list for the first parameter, choose:
Null if you do not want items on this page to provide a value for this page parameter.
Page to pass page details to the page parameter on the Portal Template.
System Variable to pass the value of a system variable to the page parameter on the Portal Template; for example, USER_NAME.
Constant to pass a specific value to the page parameter on the Portal Template.
In the value field or list, choose the page or system variable whose value you want to pass to the page parameter, or enter a constant value.
Define values for all remaining page parameters on the Portal Template.
Click OK to return to the page.
If a user clicks an item link on this page, these values are passed to the corresponding page parameters on the designated Portal Template for items.
You can specify different parameter values for individual items on the page if required, see Section 23.6.1.1, "Overriding Parameter Values for an Item Displayed on a Portal Template".
If you enable the page option Allow items on this page to use a different Portal Template, values for Portal Template parameters can be defined for each item. This enables you to override a Portal Template parameter value for a particular item on a page, should a different value be required.
Click the Page: Properties link in the toolbar at the top of the page.
On the resulting page, click the Items tab to bring it forward.
Select the Allow items on this page to use a different Portal Template check box.
(Optional) Select Use this portal template and then choose a default template for the items on this page. You can also specify default values for page parameters on the designated template if you wish. The defaults are assigned to each item on this page, but you can override the defaults for individual items as described in the following steps.
Click OK to return to the page.
Click the Edit icon beside the item to which you will assign specific page parameter values.
Select Use this portal template and then select the required Portal Template for items.
Page parameters for the selected Portal Template are displayed beneath this radio button (under Template Input). If no parameters are defined you cannot assign parameter values. See Section 23.3, "Adding a Parameter to a Page or Portal Template".
From the drop-down list for the first parameter, choose:
Null if you do not want this item to provide a value for this page parameter.
Page to pass page details to the page parameter on the Portal Template.
System Variable to pass the value of a system variable to the page parameter on the Portal Template; for example, USER_NAME.
Constant to pass a specific value to the page parameter on the Portal Template.
In the value field or list, choose the page or system variable whose value you want to pass to the page parameter, or enter a constant value.
Define values for all remaining page parameters on the Portal Template.
Click OK to return to the page.
If a user clicks the link for this item, these parameter values are passed to the designated Portal Template for items.
I want to edit a page parameter but it is inherited from a template.
When an Inherited from Template icon appears next to a page parameter, it means that the page parameter is inherited from the Portal Template on which the page is based. To edit, delete, or move a page parameter that is inherited from a Portal Template, you must edit, delete, or move the parameter in the template itself.
Similarly, if an event is associated with a portlet that is inherited from a Portal Template, you must edit the event in the template itself.
My Page portlet includes a parameter but I am not sure what syntax to use.
The Page portlet includes a parameter (named Page) that, if used, requires a value in the format PAGEGROUPID_PAGEID. To make use of this on a regular page, you must either:
Assign a constant value, such as 6_1, directly to the Page portlet's parameter.
Create a page parameter, map it to the Page portlet's parameter, then assign a value, such as 6_1, to the page parameter.
To obtain values for PAGEGROUPID and PAGEID, enter page Edit mode and display page properties by clicking the Page Properties icon in the toolbar at the top of the page.
When you use the Page parameter to define a page for your Page portlet, it overrides page selections on the Edit Defaults/Personalize pages. If the Page parameter is specified, any Edit Defaults/Personalize page selections are ignored.
