Portlet parameter Options

The following text reproduced from: http://dev2dev.bea.com.cn/techdoc/200403134.html

The Portlet parameter options provide the preferred way to associate application data with Portlets. This feature is the key to personalizing a portlet based on its purpose. In this article, we'll cover the portlet parameter options in detail.

The Portlet parameter options provide the preferred way to associate application data with Portlets. This feature is the key to personalizing a portlet based on its purpose. In this article, we'll cover the portlet parameter options in detail.

· What is a portlet parameter option.

Specify parameter options

Modify parameter Options

JSP label for parameter options

Parameter options-Practical considerations

· definition portlets : Each portlet has a UI for displaying data/content, and a section of code to handle user interaction.

Using portlets: Once the portlet is created, the Portal administrator and/or end user can add the same portlet multiple times on the various portals and desktop pages. The Portal administrator and/or end user can then customize various properties of the portlet (for example, the title of the Portlet). In this case, the Portal administrator and/or end user will be dealing with the specific purpose of the portlet. That is, in this procedure, you create a portlet instance and customize each instance.

As you'll see, portlets are easier to reuse than other WEB components, such as servlet, JSP, or even Java Page flow. Once you have created a portlet, you can instantiate it multiple times.

Because multiple instances can be created for portlets, we naturally expect that each instance behaves differently, but uses the same code and UI. For example, consider a common portlet that displays a stock portfolio. Specifies a list of stock tickers that periodically retrieves quotations from the stock quotes Web site and displays them in the Portlet window. Each user can customize this portlet by having each user change the list of stock tickers and the time interval for reloading the quote data.

However, the portlet needs to be able to persist the list of stock tickers and the time interval for retrieval, and update them when the user customizes the values. In particular, the following data must be managed persistently:

Default value: The Portlet can specify the default list of stock symbols and a reasonable retrieval interval. These values are available to all uses of the portlet, regardless of who the user is. The user can even be anonymous.

Custom values: When a user updates a value for a particular portlet instance, the Portlet is required to store the values. Note that the portlet should also define this data within an instance so that the customization does not affect other instances of the portlet.

The Portlet parameter options provide a framework for associating these data with portlets. In addition to having the ability to build multiple Portlet instances, WebLogic Portal 8.1 allows users to specify parameter options for portlets.

In this article, we will analyze the following:

· How to associate Portlet parameter options and portlets.

· Note What is a Portlet parameter option.

The portlet parameter option is the specified string data. For example, a stock portfolio portlet might have the following portlet parameter options:

and the parameter option with the value "BEAS, MSFT"

and the parameter option with a value of "600" (in seconds).

You can associate multiple such parameter options with a portlet. The Portlet parameter options have the following properties:

Name: Each parameter option has a name. For a specific portlet, no two parameter options can have the same name.

Description: A brief description of the parameter options.

Value: Each parameter option can have one (single value parameter option) or multiple values (multivalued parameter options). Each value is of type java.lang.String.

Read Only: A Boolean value that indicates whether the value of a particular parameter option can be changed by a portlet.

WebLogic Portal 8.1 provides the following features to manage portlet parameter options:

Specify portlet parameter options at development time: when building a portlet, you can specify a name and default value for the parameter options for each portlet. By default, all Portlet instances derived from this portlet will use the values specified at development time.

To have the administrator modify portlet parameter options: WebLogic Portal 8.1 allows the portal administrator to modify parameter options for a particular instance.

Let the portlet Access and modify parameter options when requested: when requested, the Portlet can access and update parameter options through the Javax.portlet.PortletPreferences object using the program. You can create an edit page for a portlet to allow users to update parameter options, or to update parameter options that are part of a common portlet application process. specifying parameter options for Portlets

The associated steps of a parameter option with a portlet depend on the type of portlet being built. If you are using the Java Portlet APIs (see the Reference section at the end of this article), follow the steps specified in the Java portlet specification. For other types of portlets, such as those that use Java Page flow, Struts, or JSPs, Portlet,weblogic Workshop will help you add parameter options to the Portlet.

WebLogic Portal also allows you to create new parameter options through the Portal Administration tool. However, because portlet developers are more likely to notice how portlets use portlet parameter options, it is more appropriate to create portlet parameter options at development time.

for Java Portlet Specify parameter Options
For portlets that use the Java portlet API, you can specify parameter options in the Portlet deployment descriptor. For all portlets in the Web application, the deployment descriptor is Portlet.xml, which is located in the directory Web-inf of the Web application. The following is an example.

<portlet> <description> This portlet displays a-stock portfolio.</description> <portlet-name>portfolioPortlet</portlet-name> <portlet-class>portlets.stock.portfolioportlet </portlet-class> <supports> <mime-type>text/html</mime-type> <portlet-mode>edit</portlet-mode> </supports> <portlet-info> <title>my portfolio</title> </portlet-info> <portlet-preferences> <preference> <name>stockSymbols</name> <value>beas, msft</value> </preference> <preference> <name>refreshInterval</name> <value>600</value> </preference> </portlet-preferences> </portlet>

This snippet uses two parameter options to deploy the stock portfolio Portlet: One parameter option named BEAS, MSFT, and the other parameter option is refreshinterval with a value of 600. Do not need to be a value element in bold.

<portlet> <description> This portlet displays a-stock portfolio. </description> <portlet-name>portfolioPortlet</portlet-name> <portlet-class>portlets.stock.portfolioportlet </portlet-class> <supports> <mime-type>text/html</mime-type> <portlet-mode>edit</portlet-mode> </supports> <portlet-info> <title>my portfolio</title> </portlet-info> <portlet-preferences> <preference> <name>stockSymbols</name> <value>BEAS</value> <value>MSFT</value> </preference> <preference> <name>refreshInterval</name> <value>600</value> </preference> </portlet-preferences> </portlet>

If you do not allow portlets to use programs to update any given parameter options, you can mark the parameter options as read-only. For example, if you want to prevent portlets changes

<portlet> <description> This portlet displays a-stock portfolio. </description> <portlet-name>portfolioportlet <portlet-class>portlets.stock.portfolioportlet <supports> <mime-type>text/html</mime-type> <portlet-mode>edit</portlet-mode> </supports> <portlet-info> <title>my portfolio</title> </portlet-info> <portlet-preferences> <preference> <name>stockSymbols</name> <value>BEAS</value> <value>MSFT</value> </preference> <preference> <name>refreshInterval</name> <value>600</value> <read-only>true</read-only> </preference> </portlet-preferences> </portlet>

Note that by marking the parameter options as read-only, you can only prevent the portlet from changing the current value when requested. The portal administrator can always change the value of the parameter options.

for other types of Portlets Specify parameter Options
If you build other types of portlets, such as those using Java Page flow, or strut, or simple JSPs, WebLogic Workshop can help you add parameter options.

The following steps show how to add parameter options to the Portlet. These steps are marked with [1], [2], and [3].

Step 1: Drag the "New preference" control into the Portlet window.

Step 2: Select the parameter options by expanding the Portlet Preferences tab.

Step 3: Update the properties of the parameter options in Property editor.

To specify multiple values for the parameter options, you can create multiple parameter options with the same name. To mark the parameter options as read-only, you can mark the modifiable property as false. accessing or modifying parameter options using the parameter options API

Portlet parameter options can be represented as instances of the Javax.portlet.PortletPreferences interface for a specific portlet at the time of the request. This interface is part of the Java Portlet API. This interface specifies methods for accessing and modifying portlet parameter options.

get parameter options: The portlet can access its parameter options using the following methods.

String GetValue (string name, string default)	Use this method to get the first value of the parameter option.
String[] GetValues (String name, string[] defaults)	Use this method to get all the values of the parameter options.
Boolean isreadonly (String name)	Use this method to confirm whether a particular parameter option is read-only.
Enumeration GetNames ()	Use this method to get a directory of all parameter option names.
Map Getmap ()	Use this method to get a mirror of the parameter options. The keys in this mirror are the names of all parameter options, and their values are the same as those returned by GetValues (String name, string[] defaults).

Set parameter options: The portlet can change the value of the parameter option using the following methods.

void SetValue (string name, String value)	Use this method to set the value of the parameter option.
void Setvalues (String name, string[] values)	Use this method to set multiple values for the parameter options.
void Store ()	Use this method to commit changes to the Portlet parameter options.
void Reset (String name)	Use this method to reset the value of the parameter option to the default value, or to remove the parameter options when there is no default value.

After you change the parameter options by calling the SetValue (), Setvalues (), and Reset () methods, you must call the store () to explicitly save the changes as permanent. Otherwise, the changes will not be permanent.

for Java Portlet Gets or sets portlets parameter Options
For portlets written using the Java Portlet API, the Java in the Javax.portlet.RenderRequest or render () method within the request--processaction () method of the incoming Portlet can be X.portlet.actionrequest gets the Doedit () method.

<%@ taglib uri= "Http://java.sun.com/portlet" prefix= "Portlet"%> <%@ page import= "Javax.portlet.PortletPreferences"%>