Module dependencies in portlets

IBM WebSphere Portal offers a filtering feature for portlet capabilities based on the existing client side capabilities.

Portlets often expect the existence of a required client side capability, such as dojo being loaded on the page, and do not work when the required client side capability is missing. It is not always clear the portlet is not working as expected. For example, a JavaScript error displaying when a certain button is clicked might be the only indication the portlet is not working properly. IBM WebSphere Portal offers a filtering feature for Standards Portlets (168/286) that enhances the situation without adding additional logic to the portlet to check for that condition. This filtering feature is based on the existing client side capabilities.

A portlet can define a set of portlet preferences that declare the capabilities the portlet depends on. The portal can then be configured to check those capabilities against the ones provided by the page in two scenarios:

1. A runtime filter that displays a message at the place the portlet markup is displayed in case there is a capabilities mismatch.

2. A build-time filter that displays a message in the administration user interface in case a page is saved and to that page a portlet was added, and for that portlet there is a capabilities mismatch.

In scenarios, where portlets are not added to pages in the production environment, disable the feature in the production environment for maximum performance.

The runtime filter can also be used in the remote rendering use case (WSRP), with the restriction that both the consumer and the producer must be of the type WebSphere Portal. If other consumers exist, disable this function for WSRP. However, this function is independent from the setting for the local rendering use case.

How a page author can use the feature

Depending on the filter settings the page author is notified when saving the page after a modification (Error Codes: EJPNK0022E, EJPNK0023E, EJPNK0024E) or when the page is rendered (Error Codes: EJPNK0026E, EJPNK0027E, EJPNK0028E). The messages contain detailed information for each portlet about which capabilities are missing or which of them have the wrong version.

When the page author receives such a message, she needs to change the theme profile assigned to the page and assign one that meets all the requirements of the portlets on that page. Often the person in the page author role will not be the one that has the Theme Profile Manager role. Therefore, the Profile Manager needs to provide documentation for each profile that explains its purpose and also lists for each capability provided by the profile the ID and the version. The page author then needs to be educated where the information can be obtained and how to read it.

With this information, the page author can map the information shown in the message to the correct profile and select it.

To create the documentation, the profile manager can use the module documentation for the ready-to-use modules. For custom developed modules, the module owner is responsible to provide the documentation as part of this development task and needs to make it available for profile managers.

How a portlet programmer can use the feature

Define two preferences for each capability the portlet depends upon. One preference describing the ID of the capability and one that defines the minimal value/version in the following format, major.minor.revision:

• ID:
  Preference Name: capability.<sequence-number>.id
  Preference Value : <the capability name>

• Value:
  Preference Name: capability.<sequence-number>.minValue
  Preference Value: <the capability value>

In addition to the definition of the capabilities, the portlet must define a preference that describes whether the portlet handles the lack of the capabilities itself or not. To delegate the handling of the error case to portal, set preference...

capabilities.selfManaged = false

Portlet can either handle all capability dependencies or none. If this preference is not set, the framework expects the portlet manages the capability dependencies itself.

Sample:

<portlet-preferences>
    <preference>
        <name>capability.1.id</name>
        <value>dojo</value>
        <read-only>true</read-only>
    </preference>
    <preference>
        <name>capability.1.minValue</name>
        <value>1.6</value>
        <read-only>true</read-only>
    </preference>
             <preference>
        <name>capability.2.id</name>
        <value>oneUI</value>
        <read-only>true</read-only>
    </preference>
    <preference>
        <name>capability.2.minValue</name>
        <value>3.0.1</value>
        <read-only>true</read-only>
    </preference>
     <preference>
        <name>capabilities.selfManaged</name>
        <value>false</value>
        <read-only>true</read-only>
    </preference>
             </portlet-preferences>

For the list of available capabilities, see Modules provided with the WebSphere Portal theme.

Parent The module framework

Related concepts:

Ready to use modules

Related reference:

Configuration settings for capability filters