Adapting portlets

You can adapt a portlet's output to the requesting device by passing the output to Transcoding Technology, which uses specialized programs called transcoding plugins to perform different conversions. For example, you can transcode a portlet's HTML output into WML (Wireless Markup Language) using the HTML to WML transcoding plugin that is part of Transcoding Technology. You can even write your own transcoding plugin, and use it in Transcoding Technology. Before a portlet can make use of Transcoding Technology, configure it by identifying the Transcoding Technology filter you want to use.

Configure a portlet to use Transcoding Technology

Before you can configure an individual portlet to use Transcoding Technology, transcoding must be turned on for all portlets. To determine if transcoding is turned on, look for an x in the Enable transcoding of content checkbox under the heading Transcoding options in Portal Administration > Portal Settings > Global Settings. This setting is a global over-ride setting. If it is not set in Global Settings (meaning transcoding is turned off for all portlets), your portlets will not utilize transcoding, even if you have configured your portlets to use Transcoding Technology.

Once transcoding is turned on for all portlets, you can configure individual portlets to use transcoding either through Portal Administration, or by adding a <config-param> element to the <concrete-portlet> element in the portlet's portlet.xml file.

All the <config-param> values in the portlet's portlet.xml can be modified post-deployment by using Manage Portlets; for example, an administrator can configure a portlet to use an Annotation or a Stylesheet via Manage Portlets.

To configure a portlet for transcoding using Portal Administration:

  1. Select Administration > Portlets > Manage Portlets to display the Manage Portlets page.

  2. Select the portlet you want to use with transcoding.

  3. Select Modify parameters.

  4. Enter the parameter name FilterChain with a value of Transcoding, then click Add. The parameter and value are added to the portlet.
    Note: Do not code FilterChain=Transcoding if the following parameters exist:

  5. Select the parameter for the portlet by clicking the checkbox next to it.

To delete a parameter, click the checkbox next to it and click Delete.

To configure a portlet for transcoding by adding a <config-param> element to the <concrete-portlet> element in the portlet's portlet.xml file, add the parameter FilterChain with a value of Transcoding.

For example:

         <!-- the following entry configures the portlet to be transcoded -->
         <config-param>
            <param-name>FilterChain</param-name>
            <param-value>Transcoding</param-value>
         </config-param>

 

Use stylesheets with a portlet

Prior to configuring the specific application portlet(s), configure the portal for processing XML documents. This is accomplished by updating the PortletFilterService.properties file and adding XML in the portal markup languages supported by the portal. To do this the following steps should be performed:

  1. Open the PortletFilterService.properties file with a text editor. The file is located within the application server directory at <portalserver>/shared/app/config/services/.

  2. After the existing entries within the filtername = Transcoding (there are currently three), add the following entries:

    Note: You can continue to configure any markup you choose, with any name you choose. All your markup has to have is a content-type (for example: text/html or text/vnd.wap.wml) and a default charset (for example: UTF-8). So the next entry in filtername=Transcoding would be:


    Refer to Designing your portal > Customizing your portal > Supporting new markup languages in the WebSphere Portal Information Center for more information about creating new markup.

  3. Click Save and close the file.

To include XML in the markup languages supported by the portal, access the Portal Administration and execute the following steps:

  1. Click Portal Administration -> Portal Settings -> Supported Markups. This gets you to the Manage Markups page.

  2. Click Add new markup.

  3. Enter these three values:

  4. Click OK.

Once you have configured the portlet to use Transcoding Technology, you can then use Transcoding Technology to perform transformations on XML data using Extensible Stylesheet Language (XSL) stylesheets. Examples of formats that can be produced by applying stylesheets include: HTML for display on a desktop browser, Wireless Markup Language (WML) for display on a smart phone, and VoiceXML for auditory rendering. XSL stylesheets can also be used to convert between different business-to-business XML formats to enable information exchange between companies.


Configure the portlet to use a stylesheet

Use an actual stylesheet file or a URL to a stylesheet file. To use a stylesheet file that has been added to the portlet WAR file, add a <config-param> element to the <concrete-portlet> element in in the portlet's portlet.xml file. The value-pair contains the name StylesheetFile with a value of =<path-to-file>, where <path-to-file> is relative to the WAR file root, such as WEB-INF/myfile.xsl; or is the URL where the stylesheet file is located, such as http://myserver/myfile.xsl.

For example, to configure the portlet to use myfile.xsl, add the following:


         <!-- the following entry points to the stylesheet file, relative to the WAR file's root directory -->
         <config-param>
            <param-name>StylesheetFile</param-name>
            <param-value>WEB-INF/myfile.xsl</param-value>
         </config-param>

To configure the portlet to use myfile.xsl on the server myserver, add the following:


         <!-- the following entry points to the stylesheet file on a particular server -->
         <config-param>
            <param-name>StylesheetFile</param-name>
            <param-value>http://myserver/myfile.xsl</param-value>
         </config-param>

Transcoding Technology will retrieve the specified stylesheet when it processes the XML output generated by this portlet.


Specifying stylesheets within a document

As an alternative to configuring the portlet to use a stylesheet to be applied to an XML document, Transcoding Technology can select a stylesheet that is specified within the XML document. The stylesheet specification includes the conditions under which that stylesheet is to be applied. Several stylesheet specifications can be included in the same XML document.

The preferred method for specifying stylesheets within an XML document is to use the wtp-condition processing instruction. You can add several of these instructions to the prologue of an XML document to specify different stylesheets for different conditions. The wtp-condition instruction can use the values of any field in the HTTP header and any preferences in effect. It can also use two special variables device and user, which contain the respective profile names determined during preference aggregation.

If you want to combine conditions by "ANDing" them, use &amp; between the conditions as in these examples. XML uses & as the beginning of symbols, so if you use & by itself it will be interpreted as the beginning of a symbol rather than as AND. Transcoding Technology will change the &amp; into AND in order to evaluate the conditions.

<?xml version="1.0"?>
<?wtp-condition  stylesheet="file://mywml.xsl" condition="(targetContentType=text/vnd.wap.wml)
&amp; (textLinksPreferredToImages=1) &amp; (url=*orders/recent*) 
&amp; (device=WMLDevice)"?>

<?wtp-condition  stylesheet="file://myhdml.xsl" condition="(textLinksPreferredToImages=1) 
&amp; (url=*orders/recent*) &amp; (device=HDML-Device)"?>

<?wtp-condition  stylesheet="http://www.ibm.com/mypalm.xsl" condition="(textLinksPreferredToImages=1) 
&amp; (url=*orders/recent*) &amp; (device=Palm-Pilot3.HandWeb11)"?>

 

Use annotation with a portlet

Transcoding Technology also provides an annotation language that enables you to manipulate HTML documents. A special transcoding plugin, the annotation engine, is included to handle annotation processing. Annotations are composed of a special set of XML tags that, when combined with an HTML source file, dictate which parts of the HTML document should be modified. You can put all of your annotations for a particular document in a separate annotation file called an annotator (referred to as external annotation), or you can embed annotations directly in the HTML file itself as comments (referred to as internal annotation). Regardless of whether you use internal annotation or an annotator, Transcoding Technology's annotation engine processes the annotations with the HTML output and produces a clipped version of the document.

Configure a portlet for external annotation

To use an annotator file that has been added to the portlet WAR file for external annotation, add a <config-param> element to the <concrete-portlet> element in the portlet's portlet.xml file. The value-pair contains the name AnnotationFile with a value of =<path-to-file>, where <path-to-file> is relative to the WAR file root, such as WEB-INF/myfile.ann; or it is the URL where the annotator file is located, such as http://myserver/myfile.ann.

For example, to configure the portlet to use myfile.ann, add the following:


         <!-- the following entry points to the annotation file, relative to the WAR file's root directory -->
         <config-param>
            <param-name>AnnotationFile</param-name>
            <param-value>WEB-INF/myfile.ann</param-value>
         </config-param>

To configure the portlet to use myfile.ann on the server myserver, add the following:


         <!-- the following entry points to the annotation file on a particular server embedded      
		 <config-param>
            <param-name>AnnotationFile</param-name>
            <param-value>http://myserver/myfile.ann</param-value>
         </config-param>

Transcoding Technology will retrieve the annotator when it processes the portlet's HTML output. Note that annotation only works on HTML.


Use internal annotation with a portlet

Since internal annotations are embeded directly in the HTML file itself as comments, no special configuration of a portlet is required to use internal annotation. The annotations are dealt with automatically as Transcoding Technology processes the portlet's output.


 

See also