Converting portlet fragments to an HTML document

A portlet only delivers fragment output whereas a servlet typically delivers document output. However, we 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 used to embed the portlet‘s content into a document is called the document servlet filter. We 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.

 

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. 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 we 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 verify 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 Hypertext Markup Language (HTML) document. For example, this allows another document servlet filter in front to convert the fragment into a valid Wireless Markup Language (WML) document instead.

 

Related concepts

Portlets
Portlet container

 

Related tasks

View deployment descriptors
Task overview: Managing portlets