Transcoding Technology Adapting portlets

 

+
Search Tips   |   Advanced Search

 

We 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, we 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. We 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 we want to use.

 

Configure a portlet to use Transcoding Technology

Before we can configure an individual portlet to use Transcoding Technology, transcoding must be turned on for all portlets. This is no longer enabled by default. For information on how to enable transcoding, see What is Transcoding Technology. Once transcoding is turned on for all portlets, we 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 > Portlet Management > Portlets to display the Manage Portlets page.

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

  3. Select the Configure Portlet icon.

  4. Enter the parameter name FilterChain with a value of Transcoding, then click Add. The parameter and value are added to the portlet.

    Do not code FilterChain=Transcoding if the following parameters exist:

    • FilterChain=strutsTranscoding
    • FilterChain=wmlOnlyTranscoding
    • FilterChain=ChtmlOnlyTranscoding

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

To delete a parameter, click the check box 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...

    portal_server_root/shared/app/config/services/

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

    • Transcoding.transcodeMarkup.4 = xml->html

    • Transcoding.transcodeMarkup.5 = xml->wml

    We can continue to configure any markup you choose, with any name you choose. All the 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:

    • Transcoding.transcodeMarkup.6=xml->[yourmarkup]

  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 us 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, we 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. Configuring the portlet to use a stylesheet

We can 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 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. We 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.

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 us to manipulate HTML documents. A special transcoding plugin, the Transcoding plugins, 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. We can put all of the annotations for a particular document in a separate annotation file called an annotator (referred to as external annotation), or we 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 embedded 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.

 

Parent topic:

Transcoding