Converting portlet fragments to an HTML document

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.

About this task

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

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 Java™ archive (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>
```
Optional: 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, you must cache the complete portlet content.
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.
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 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.