Configuring JSR 168 portlets

Configuring JSR 168 portlets

To configure a JSR 168 portlet, open the Portlet Deployment Descriptor editor, select the portlet from the Portlets list box and specify the following values.

Table 1. Portlet class
Property Name Description
Portlet class The canonical name of the portlet selected in the Portlets list box. Select the Browse button to open the Select Portlet dialog and create a new mapping in the deployment descriptor. Used in the <portlet-class> node.

Table 2. Localization of deployment descriptor values
Property Name Description
Language The locale information used in the xml:lang attribute to localize the Display name and the Description. The default value for the xml:lang attribute is English (en). Used in the xml:lang attribute of <display-name> and <description> in <portlet>.
Display name An administrative name used to identify the portlet. It is only shown in GUI tools. Used in <display-name> in <portlet>.
Description A descriptive text about the portlet. This text is not displayed to end users. Used in <description> in <portlet>.

Table 3. Language specific portlet information
Property Name Description
Resource Bundle To provide language specific portlet information, like title and keywords, resource bundles are used. Set the fully qualified class name of the resource bundle. Used in <resource-bundle>.
Supported Locales Declare locales the portlet supports at run time. Used in <supported-locale>, and to locate the resource bundle file for each locale.
Portlet Info Specify the following portlet information for each supported locale. Select a supported locale above and specify the portlet information for the selected locale. The specified information will be saved in resource bundle files.

Title

The title that should be displayed in the title bar of this portlet. Only one title per locale is allowed. Note that this title may be overridden by the portal or programmatically by the portlet. Used in <title> in <portlet-info> for the default locale, and used in javax.portlet.title in the language specific resource bundle file for other locales.

Short title

A short version of the title that may be used for devices with limited display capabilities. Only one short title per locale is allowed. Used in <short-title> in <portlet-info> for the default locale and used in javax.portlet.short-title in the language specific resource bundle file for other locales.

Keywords

Keywords that describe the functionality of the portlet. Portals that allow users to search for portlets based on keywords may use these keywords. Multiple keywords per locale are allowed, but must be separated by a comma (,). Used in <keywords> in <portlet-info> for the default locale and used in javax.portlet.keywords in the language specific resource bundle file for other locales.

Table 4. Defining portlet modes support
Property Name Description
Supported Modes Portlet modes the portlet can handle for each markup type it supports. All portlets must support the VIEW portlet mode. The portlet must not be invoked in a portlet mode that has not been declared as supported for a given markup type. The portlet container will ignore all references to custom portlet modes that are not supported by the portal implementation, or that have no mapping to portlet modes supported by the portal.

MIME type

MIME type the portlet supports. Used in <mime-type> in <supports>.

Markup

Markup type the portlet supports. Used in <init-param> to define the property: wps.markup. This is an IBM extension markup property to enable the portlet access to the markup type, which is a more fine-grained definition for the markup to return than the MIME type. For example, HTML and cHTML both have MIME type text/html, but have markup html and chtml to enable the portlet to produce different output for the HTML and cHTML cases. For more information about this IBM extension, refer to Developing portlets using JSR 168 and WebSphere Portal V5.02

Portlet modes

Portlet modes the portlet can handle for the markup type specified by the MIME type. The standard portlet modes (VIEW, EDIT or HELP). Used in <portlet-mode> in <supports>.

Table 5. Initialization Parameters
Property Name Description
Initialization Specifies the initialization parameters of the portlet. Click the Add or Remove button to add or remove initialization parameters as name/value pairs. Select a parameter and click the Edit button to update the parameter and its value. Used in <init-param>.

Table 6. Programmatic Security
Property Name Description
Security Role References Specifies the security role references. Click the Add button, the Remove button or the Edit button to add, remove or update a security role reference. The following sub-elements are defined in the <security-role-ref> element.

Role name

A string specifying the name of the role which refers to an application security role. Portlets should use this role name to determine whether the authenticated user is included in an application security role. Used in <role-name>.

Role link

A string specifying the name of the application security role that the user may be mapped into. This security role must be defined in the Web deployment descriptor. If you specify a security role which has been already defined in the web deployment descriptor you can select it from the list. Used in <role-link>.

Language

A language in which the description is written. Used as xml:lang in <description>.

Description

A descriptive text about this security role. Used in <description>.

For example, to map the security role reference FOO to the security role with role-name manager, specify FOO in the Role name field and manager in the Role link field. In this case, if the portlet called by a user belonging to the manager security role made the API call isUserInRole("FOO"), then the result would be true.

Caching

Caching content helps improve the Portal response time for users. It also helps to reduce the load on servers. The Portlet Specification defines an expiration based caching mechanism. This caching mechanism is per-portlet, per-user client. Cached content must not be shared across different user clients displaying the same portlet.

In an environment where a remote proxy server is used for caching, JSR 168 compliant portlets can indicate cache settings that are used by the server to determine how the page is cached on a remote proxy server.

Table 7. Caching
Property Name Description
Expiration Cache Defines an expiration based caching mechanism. The following selection is used to set the value of the expiration property, <expiration-cache>.

Always expires

Caching is disabled for the portlet. This will set the expiration property to 0.

Never expires

The cache does not expire. This will set the expiration property to -1.

Expires after specified seconds

The duration (in seconds) of the expiration cache.

Remote cache Additional settings must also be provided using a deployment descriptor extension (ibm-portlet-portal-ext.xmi). The portlet indicates whether the remote cache is shared or not-shared using the <remote-cache-scope> element in the extension file.

Remote cache dynamic

shared indicates that the remote cache is shared.

Remote cache scope

If the portlet window does not modify cache settings at runtime, this setting should be false. This setting optimizes performance, informing the portlet container that it does not need to wait for the portlet window to publish remote cache information.

Portlet Preferences

Portlets are commonly configured to provide a customized view or behavior for different users. This configuration is represented as a persistent set of name-value pairs and it is referred to as portlet preferences. Portlet preferences are intended to store basic configuration data for portlets. It is not the purpose of the portlet preferences to replace general purpose databases.

Property Name Description
Persistent Preference Store Specify portlet preferences. Specify elements in a preference. Included in a <preference> attribute.

Name

Name of the preference. Used in <name> in <preference>.

Values

Initial default values of the preference. Used in <value> in <preference>.

Read only

Select the Read only check box to fix this preference at deployment time. If it is not selected, this preference is modifiable when the portlet is processing an action request in any of the standard portlet modes (VIEW, EDIT or HELP). This selection will set the <read-only> element to true in <preference>.

Select a preference validator class

Validator class

Specify a class that implements the PreferencesValidator interface to validate the set of preference values in the PortletPreferences object. Edit the Validator class field or click the Browse button to select the preference validator. Used in <preference-validator> attribute in the <portlet-preferences> attribute.

Related concepts
Portlet APIs
Creating portlets and portlet projects
Working with portlet deployment descriptors

Related tasks
Creating, adding, removing, or editing portlets
Defining portlet security constraints
Defining custom portlet modes
Defining custom window states
Defining user attributes

Related reference
References

Property Name	Description
Language	The locale information used in the xml:lang attribute to localize the Display name and the Description. The default value for the xml:lang attribute is English (en). Used in the xml:lang attribute of <display-name> and <description> in <portlet>.
Display name	An administrative name used to identify the portlet. It is only shown in GUI tools. Used in <display-name> in <portlet>.
Description	A descriptive text about the portlet. This text is not displayed to end users. Used in <description> in <portlet>.

Property Name	Description
Resource Bundle	To provide language specific portlet information, like title and keywords, resource bundles are used. Set the fully qualified class name of the resource bundle. Used in <resource-bundle>.
Supported Locales	Declare locales the portlet supports at run time. Used in <supported-locale>, and to locate the resource bundle file for each locale.
Portlet Info	Specify the following portlet information for each supported locale. Select a supported locale above and specify the portlet information for the selected locale. The specified information will be saved in resource bundle files. Title The title that should be displayed in the title bar of this portlet. Only one title per locale is allowed. Note that this title may be overridden by the portal or programmatically by the portlet. Used in <title> in <portlet-info> for the default locale, and used in javax.portlet.title in the language specific resource bundle file for other locales. Short title A short version of the title that may be used for devices with limited display capabilities. Only one short title per locale is allowed. Used in <short-title> in <portlet-info> for the default locale and used in javax.portlet.short-title in the language specific resource bundle file for other locales. Keywords Keywords that describe the functionality of the portlet. Portals that allow users to search for portlets based on keywords may use these keywords. Multiple keywords per locale are allowed, but must be separated by a comma (,). Used in <keywords> in <portlet-info> for the default locale and used in javax.portlet.keywords in the language specific resource bundle file for other locales.

Property Name	Description
Expiration Cache	Defines an expiration based caching mechanism. The following selection is used to set the value of the expiration property, <expiration-cache>. Always expires Caching is disabled for the portlet. This will set the expiration property to 0. Never expires The cache does not expire. This will set the expiration property to -1. Expires after specified seconds The duration (in seconds) of the expiration cache.
Remote cache	Additional settings must also be provided using a deployment descriptor extension (ibm-portlet-portal-ext.xmi). The portlet indicates whether the remote cache is `shared` or `not-shared` using the <remote-cache-scope> element in the extension file. Remote cache dynamic `shared` indicates that the remote cache is shared. Remote cache scope If the portlet window does not modify cache settings at runtime, this setting should be `false`. This setting optimizes performance, informing the portlet container that it does not need to wait for the portlet window to publish remote cache information.