. 80
( 87 .)


484 Chapter 24

Figure 24-6 High-level architecture view including a wireless gateway and WEA.

TT inspects user agent information that is part of the headers packaged
with the request and allows you to provide speci¬c instructions for trans-
forming the original content to a form that is suitable for the device that ini-
tiated the request. Elements of TT are available in WP but the full package
is only available in WEA and most of the methods detailed in this section
relate to the more advanced TT available in WEA.
In order to enable TT in WEA, log in to the portal as an administrator and
follow these steps:
1. Select the Portal Administration tab.
2. Select Global Settings.
3. Check the Enable trancoding of portlet content check
4. Save and exit.
TT offers three ways to transform content, which are as follows:
1. XML style sheets”this method uses style sheets expressed in XSL to
de¬ne mappings that should be applied before the content is
delivered to the user™s device.
2. Annotators”this method allows you to associate a set of annotation
instructions with generated content. This instruction set allows you
to specify (either within the generated content or using an external
set of annotators) how the original portlet content should be
modi¬ed before it is delivered to the user™s device.
3. Transcoding plug-ins”a set of generic content modi¬ers that address
common tasks such as conversion from normal HTML to WML.
In addition to the transcoding plug-ins TT has a built-in fragmentation
transcoder. Fragmentation is important because many mobile phones have
severe limits on storage capacity. As an example, some i-mode phones and
gateways have a limit of 2048 bytes per document and some WML phones
and gateways have a limit of 2880 bytes. Large documents must be broken
WY009-24 WY009-BenNatan-v1.cls May 11, 2004 14:54

Supporting Mobile Users 485

Figure 24-7 Request ¬‚ow using TT as handled by the portal.

down into multiple documents linked together before they can be deliv-
ered to the user device. This function is carried out by the fragmentation
Figure 24-7 shows the request handling ¬‚ow that makes use of TT to adapt
generated content. The ¬‚ow shown in Figure 24-7 includes the following

1. When a request comes in, the portal determines what the user agent
is. This value captures which device the user is using.
2. The portal matches the user agent with the preference pro¬les
installed. Preference pro¬les allow you to specify how to treat
documents that will be delivered to different end user devices. You
should place your preference ¬les as .prop property ¬les in the
<TT_ROOT>/etc/preferences/device directory and name the
¬les based on the user agent to which they correspond. Selection of
the appropriate preference pro¬le is based on the following sequence:
a. The HTTP header is inspected to see whether it includes a value
for X-IBM-PVC-Device-Type.
WY009-24 WY009-BenNatan-v1.cls May 11, 2004 14:54

486 Chapter 24

b. The User-agent ¬eld is checked in the HTTP header.
c. If neither exists, TT uses the default device pro¬le.
d. In addition, you can specify a custom ¬eld in the HTTP header
that will be used for selecting a user-speci¬c pro¬le (rather than a
pro¬le that is based on the device only). To do this, set the
httpUserIdField value in <TT_ROOT>/etc/localConfig
Commonly used parameters that you can control through the
preference pro¬le ¬les include the following:
a. deviceRule”de¬nes which user agent this pro¬le will be
matched up with. You should include wild cards to cover multiple
browsers and microbrowsers rather than have a speci¬c preference
pro¬le for every different browser since many browsers and
microbrowsers behave similarly.
b. javaAppletsSupported”a boolean value specifying whether
applets should be stripped out of the content for devices that
cannot render Java applets.
c. javaScriptSupported”a boolean value specifying whether
Javascript code should be stripped out of the content for devices
that cannot interpret and run Javascript.
d. framesSupported”a boolean values specifying whether the
device can support HTML frames.
e. desiredContentTypes”a MIME type specifying the content
type sent back to the user device.
f. A value for the maximal deck size as used by the fragmentation
transcoder. This value de¬nes the maximal size per fragment. As
an example, the parameter for WML fragmentation is called
3. The portal calls the aggregator that in turn calls the appropriate
portlets. Each such portlet has a portlet ¬lter that is invoked by the
aggregator. An appropriate portlet is one that is con¬gured to use TT.
In order to con¬gure a TT-enabled portlet you need to set two
con¬guration parameters within your portlet.xml ¬le as follows:

<concrete-portlet-app ... >
<concrete-portlet ... >
WY009-24 WY009-BenNatan-v1.cls May 11, 2004 14:54

Supporting Mobile Users 487


Alternatively, log in to the portal as an administrator, select
Administration ➪ Portlets ➪ Manage Portlets, select your portlet, and
click Edit Parameters. Then add values for the two parameters as
shown in Figure 24-8.
4. The portlet ¬lter calls the portlet to retrieve the content (in the source
markup”for example, HTML).
5. The portlet ¬lter then calls the TT runtime sending it the portlet™s
content. TT uses the information in the pro¬les as well as style sheets
and annotator ¬les to create the new content.
6. The portlet ¬lter returns the content generated by TT as if this is the
content generated by the portlet.

Figure 24-8 Enabling TT for your portlet”adding appropriate parameters.
WY009-24 WY009-BenNatan-v1.cls May 11, 2004 14:54

488 Chapter 24

7. The aggregator returns the aggregated content post-fragmentation (if
relevant) and the portlet returns the content to the end user device.

Using XSL for Adapting Content
So long as all content generated by portlets is well-formed XML (and this is
a nontrivial assumption that you should pay special attention to), XSL style
sheets are a very natural and architecturally elegant solution to generating
multiple presentations from a single portlet. In addition, XSL is an industry
standard and the use of XSL for mapping one content to another is a common
practice, which means that many people will be familiar with this method.
There are numerous tools that can help you in doing this right”including
the various versions of WebSphere Studio that include an XML editor, an
XSL editor, and an XML-to-XML mapping editor.
To use style sheet transcoding you ¬rst need to con¬gure the portal for
XML processing, which can be done as follows:

1. Edit <WAS_ROOT>/lib/app/config/services/
PortletFilterService.properties and add entries to allow
for transcoding to the various markup types that your portal should
support. Look for the last entry in the ¬le starting with Transcoding
.transcodeMarkup and make sure you use the next available
sequence. As an example, for transcoding to WML and cHTML add
the following entries:

Transcoding.transcodeMarkup.4 = xml->wml
Transcoding.transcodeMarkup.5 = xml->chtml

2. Log in to the portal as an administrator and select Administration
➪ PortalSettings ➪ Supported Markups. Click Add New Markup and
enter the values as shown in Figure 24-9. Click OK.
3. The new markup type will be added as inactive. Select the xml
markup and click Activate/Deactivate Selected Markup.
4. Validate your markup types by clicking Show Info; your display
should include an active XML markup as shown in Figure 24-10.

Once the portal has been set up for XML transcoding, you need to tell it
which style sheet should be used for transcoding each portlet. Specifying a
style sheet per portlet can be done in one of the following three ways:

1. Add a config-param element within the concrete-portlet
element in portlet.xml and put the style sheet in the WAR ¬le.
WY009-24 WY009-BenNatan-v1.cls May 11, 2004 14:54

Supporting Mobile Users 489

Figure 24-9 Adding support for XML markup for XSL transcoding.

2. Select Administration ➪Portlets ➪Manage Portlets, select your portlet
and click Edit Parameters. Then add a parameter called
StylesheetFile with the ¬le name as the value.
3. If you need to transcode XML content into multiple other markup
languages and want to separate the XSL transformation instructions
into separate style sheets, your portlet can produce XML output
with speci¬c transcoding processing instructions. Each such directive
includes a condition that de¬nes the location of the style sheet and
a category of user agents for which the style sheet should be applied.
As an example, to apply one style sheet for all Nokia phones, which is
different from a style sheet used for conventional Web browsers, add
the following two directives to the code producing your XML content:
<xml version="1.0" encoding="ISO-8859-1"?>
<wtp-condition stylesheet=”/browsers.xsl” condition=”(user-
<?wtp-condition stylesheet=”/nokiaPhones.xsl” condition=”(user-
... The rest of your XML content ...
WY009-24 WY009-BenNatan-v1.cls May 11, 2004 14:54

490 Chapter 24

Figure 24-10 Validating active XML markup.

Using Annotators for Adapting Content
The second method to adapt content involves annotators that are TT-speci¬c
constructs that can help you transform HTML generated by a portlet.
Annotators are important even though they are not a standard technology
because XSL sheets are often hard to write while annotators follow a very
simple instruction-based mapping metaphor. It is therefore often easier to
build an annotator than an XSL sheet. In addition, annotators transform
HTML content, which is probably what most of your portlets produce”
making them easy to incorporate with your portlet JSPs or classes. You
should therefore have both options in your arsenal of techniques.
Annotation instructions come in two ¬‚avors: external annotations and
internal annotations. External annotations are instructions that are placed


. 80
( 87 .)