Configuring JSR 168 portlets

Configuring JSR 168 portlets

To configure a JSR 168 portlet, double click on the Portlet Deployment Descriptor in the Project Navigator. The Portlet Deployment Descriptor editor opens. Select the Portlets tab, and then select the portlet from the Portlets list box. Then click on the section that contains the values you want to edit.
The following is a brief description of the properties that are common to both JSR 168 and JSR 286 portlets.
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.

Note:
wps.markup is a not applicable to Websphere Application Server V6.1 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.
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.

Note: Remote cache is only applicable to Websphere Portal.

Remote cache dynamic

If the portlet window does not modify cache settings at runtime, this check box should be deselected. This setting optimizes performance, informing the portlet container that it does not need to wait for the portlet window to publish remote cache information. The default behavior of this setting (the check box is selected), indicates that the portlet window does publish remote cache information.

Remote cache scope

shared indicates that the remote cache is shared.

Portlet Preferences

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.

For information specific to JSR 286 portlets, see Configuring JSR 286 portlets.

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. Note: Remote cache is only applicable to Websphere Portal. Remote cache dynamic If the portlet window does not modify cache settings at runtime, this check box should be deselected. This setting optimizes performance, informing the portlet container that it does not need to wait for the portlet window to publish remote cache information. The default behavior of this setting (the check box is selected), indicates that the portlet window does publish remote cache information. Remote cache scope shared indicates that the remote cache is shared.