Convert portlet fragments to an HTML document

 

+

Search Tips   |   Advanced Search

 

Overview

A portlet only delivers fragment output whereas a servlet typically delivers document output. However, you can use the PortletServingServlet servlet, which is similar to the FileServingServlet servlet, to address portlets like servlets.

A default document servlet filter, the DefaultFilter filter, is applied to the PortletServingServlet servlet to return the portlet‘s content inside of a document. This filter only applies to requests, not to includes or forwards using the RequestDispatcher method. A servlet filter that is used to embed the portlet‘s content into a document is called the document servlet filter. You can define additional document servlet filters in a .xml file. The FilterRequestHelper attribute within...

com.ibm.wsspi.portletcontainer.util

...is provided to assist the document servlet filters in analyzing a request regarding filter chain and portlet information. It is used in supporting dynamic portlet titles, as a marker for redirection for document servlet filters and to ensure that document conversion is completed once.

 

Procedure

1. Add a new document servlet filter.

   The filter capability is a server feature, therefore all filters must be installed into the server to use the filter capability of the server. The filters need to be available in any classes or library directory on a server level.

   You must also register the filter in a plugin.xml file within the root of a JAR file.

   The following is an example of how to register the filter in a plugin.xml file.

   <?xml version="1.0" encoding="UTF-8"?>
   
   <?eclipse version="3.0"?>
   
   <plugin id="sample.plugin" 
           name="Customer_Plugin" 
           provider-name="Customer" 
           version="1.0.0">
   
     <extension point="com.ibm.ws.portletcontainer.portlet-document-filter-config">
   
       <portlet-document-filter class-name="sample.filter.CustomFilter" 
                                order="200" />
   
     </extension>   
   
   </plugin>
   
   

2. Optionally set dynamic portlet titles by providing the dynamic title as a request attribute.

   The PortletServingServlet servlet supports dynamic portlet titles by providing the dynamic title as a request attribute,...

   FilterRequestHelper.DYNAMIC_TITLE

   This attribute returns the dynamic portlet title if it has been set by the portlet, otherwise it returns the static portlet title of the portlet.xml file if defined.

   DYNAMIC_TITLE = ‘javax.portlet.title’

   The DefaultFilter uses this request attribute to set the document title while converting the fragment into a document. If you want the filter to support browser caching or dynamic portlet titles, cache the complete portlet content.

3. Specify cache handling for the portlet rendering call to support dynamic title.

   Redirection for document servlet filters

   A document servlet filter can set a marker as request attribute, FilterRequestHelper.REDIRECT. This marker ensures that the portlet container returns to the document servlet filter after the portlet action has been called prior to any render calls. You must define the following constants,

   REDIRECT = ‘com.ibm.websphere.portlet.action'

   ...and...

   REDIRECT_VALUE = 'redirect'

   The DefaultFilter uses this request attribute to provide special cache handling for the portlet rendering call to support dynamic title.

4. Convert the portlet's fragment into a valid document.

   Document conversion must be completed only once. Therefore each document servlet filter must ensure that the fragment has not yet been converted to a document previously. If the document servlet filter converts the fragment to a document, the request attribute...

   FilterRequestHelper.DOCUMENT

   ...must be set to...

   FilterRequestHelper.DOCUMENT_VALUE

   This request attribute marks whether the conversion still needs to be completed. The following constants are defined,

   DOCUMENT = ‘com.ibm.websphere.portlet.filter'

   ...and...

   DOCUMENT_VALUE = 'document'

   The DefaultFilter uses this request attribute to check whether it should convert the fragment to an HTML document. For example, this allows another document servlet filter in front to convert the fragment into a valid WML document instead.

---

 

Related concepts

Portlets
Portlet container

 

Related tasks

View deployment descriptors
Task overview: Managing portlets