Red paper

2,104
-1

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
2,104
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
5
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Red paper

  1. 1. Front cover Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1 Access existing enterprise online Web applications from WAP and Pocket PCs Enable portlet-level transcoding with stylesheets and annotators Learn fragmentation in portal-level transcoding Juan R. Rodriguez LindaMay Patterson Gianfranco Rutigliano Luo Yuan Zhi, Anna ibm.com/redbooks Redpaper
  2. 2. International Technical Support Organization Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1 October 2002
  3. 3. Note: Before using this information and the product it supports, read the information in “Notices” on page v. First Edition (October 2002) This edition applies to Version 4, Release 1, Modification 1 of IBM WebSphere Everyplace Access for multiplatforms. © Copyright International Business Machines Corporation 2002. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  4. 4. Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ....... ...... . . vii The team that wrote this Redpaper . . . . . . . . . . . . . . . . . . ....... ...... . . vii Become a published author . . . . . . . . . . . . . . . . . . . . . . . . ....... ...... . . viii Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ....... ...... . . . ix Chapter 1. Transcoding Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Transcoding Technologies overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.2 Preference profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.3 XML stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.4 Annotators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.5 Transcoding plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2 XML Config tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3 Request Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3.1 How to start Request Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.4 Logging and tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1.4.1 Message files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.4.2 Tracing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.4.3 Gather troubleshooting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.5 A simple portlet using Transcoding Technologies . . . . . . . . . . . . . . . . . . . 15 1.5.1 Enable transcoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.5.2 Use Request Viewer to monitor the process . . . . . . . . . . . . . . . . . . . 23 Chapter 2. Using annotation for document clipping . . . . . . . . . . . . . . . . . 25 2.1 Annotation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 2.1.1 Annotation processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.2 Internal annotation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.2.1 Page Designer in WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . 28 2.2.2 Sample application: The Redbook News . . . . . . . . . . . . . . . . . . . . . 28 2.3 External annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 2.3.1 The external annotation language. . . . . . . . . . . . . . . . . . . . . . . . . . . 37 2.3.2 Sample scenario: RedbookNews02 . . . . . . . . . . . . . . . . . . . . . . . . . 38 Chapter 3. Using XSL stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 3.1.1 Configuring stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 © Copyright IBM Corp. 2002. All rights reserved. iii
  5. 5. 3.2 Configure portal for stylesheet processing . . . . . . . . . . . . . . . . . . . . . . . . 49 3.3 Sample one: XML Feed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 3.3.1 Configuring the XMLFeed portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.3.2 An alterative - Register the stylesheet . . . . . . . . . . . . . . . . . . . . . . . 53 3.4 Sample scenario 2 - ITSO News XML Feed . . . . . . . . . . . . . . . . . . . . . . . 54 3.4.1 Sample stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Chapter 4. Portal-level transcoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 4.1.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.1.2 Fragmentable elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.1.3 Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.1.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.2 WML fragmentation in Transcoding Technologies . . . . . . . . . . . . . . . . . . 68 4.2.1 Scenario 1: Using a WAP reverse proxy . . . . . . . . . . . . . . . . . . . . . . 69 4.2.2 Scenario 2: Using a forward proxy . . . . . . . . . . . . . . . . . . . . . . . . . . 74 4.2.3 Scenario 3: Using a forward proxy and reverse proxy . . . . . . . . . . . 75 iv Transcoding Technologies in IBM WebSphere Everyplace Access V4.1.1
  6. 6. Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces. © Copyright IBM Corp. 2002. All rights reserved. v
  7. 7. Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: AIX® IBM eServer™ SP™ DB2® iSeries™ WebSphere® Everyplace™ Redbooks™ IBM® Redbooks (logo)™ The following terms are trademarks of International Business Machines Corporation and Lotus Development Corporation in the United States, other countries, or both: Lotus® Word Pro® The following terms are trademarks of other companies: ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others. vi Transcoding Technologies in IBM WebSphere Everyplace Access V4.1.1
  8. 8. Preface This Redpaper will help you plan and enable the function provided by Transcoding Technologies in the IBM WebSphere Everyplace Access V4.1.1 so that existing enterprise online portlet applications can be accessed from wireless devices such as WAP phones and Pocket PCs. You will find step-by-step examples showing ways to implement text clipping, a process to manipulate existing HTML portlet pages to meet the characteristics of requesting devices. You will also find scenarios using stylesheets to transform XML portlet content into other markup languages suitable for handling by client devices. WML fragmentation, a function of Portal level transcoding, is also described in different configurations. A basic knowledge of WebSphere Portal; portlets; Java technologies such as servlets, JavaBeans, and Java Server Pages (JSPs); as well as HTML and XML markup languages; and the terminology used in Web publishing, is assumed. The team that wrote this Redpaper This Redpaper was produced by a team of specialists from around the world working at the International Technical Support Organization, Raleigh Center. Juan R. Rodriguez is a Consulting IT professional at the IBM ITSO Center, Raleigh. He received his Master of Science degree in Computer Science from Iowa State University. He writes extensively and teaches IBM classes worldwide on such topics as networking, Web technologies, and information security. Before joining the IBM ITSO, he worked at the IBM laboratory in the Research Triangle Park (North Carolina, USA) as a designer and developer of networking products. LindaMay Patterson is an Advisory Software Engineer from the eServer Custom Technology Center (eCTC) in IBM Rochester, Minnesota. She has 28 years of experience within IBM working with various software products to create business application solutions. She is currently working with the Enterprise Segment Strategy Team in the Pervasive Computing Division. Her current focus is on Pervasive Computing, XML, and related technologies. Prior to joining the eCTC, she worked in Partner World for Developers - iSeries © Copyright IBM Corp. 2002. All rights reserved. vii
  9. 9. creating educational material on various topics and helping ISVs incorporate new technology in their solutions. Gianfranco Rutigliano holds a degree in Systems Engineering from the University of Lima (Peru) and is a member of the Application Management Services (AMS) group in IBM Global Services working with e-business projects and related Internet technologies. He has worked with e-marketplace and home-banking implementation systems using Java technologies. Currently he is involved in wireless application solution projects using PDAs. Luo Yuan Zhi, Anna is an Advisory IT Specialist from the Emerging Technology Center in IBM Singapore. She has eight years of experience in the telecommunications and IT fields. Her current area of expertise is centered around Web technologies and Pervasive Computing. She holds a Bachelor’s degree (with honors) in Control and Communication Engineering from University of Manchester Institute of Science and Technology (UMIST), United Kingdom, and a Master of Science degree in Computer Engineering from the University Of Singapore. Thanks to the following people for their contributions to this project: International Technical Support Organization, Austin Center Julie Czubik IBM Research Triangle Park, North Carolina, USA James Thrasher, Alan Booth Become a published author Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. viii Transcoding Technologies in IBM WebSphere Everyplace Access V4.1.1
  10. 10. Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html Comments welcome Your comments are important to us! We want our papers to be as helpful as possible. Send us your comments about this Redpaper or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at: ibm.com/redbooks Send your comments in an Internet note to: redbook@us.ibm.com Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 662 P.O. Box 12195 Research Triangle Park, NC 27709-2195 Preface ix
  11. 11. x Transcoding Technologies in IBM WebSphere Everyplace Access V4.1.1
  12. 12. 1 Chapter 1. Transcoding Technologies This chapter provides an introduction to the Transcoding Technologies in WebSphere Everyplace Access. It covers the relevant tools and options available with Transcoding Technologies for portlet-level transcoding. Note: For more information about portal-level transcoding see Chapter 4, “Portal-level transcoding” on page 61. © Copyright IBM Corp. 2002. All rights reserved. 1
  13. 13. 1.1 Transcoding Technologies overview Transcoding Technologies included in WebSphere Everyplace Access enable the ability to tailor Web-based information to the different needs of different users. For example, Web pages can be made available on handheld and other pervasive devices economically and efficiently. With Transcoding Technologies, users receive information tailored to the capabilities of the devices they are using. For example, users with small-screen devices access a scaled version of the information, while users of a specialized markup language access the same information in a format suitable for their devices. By providing a single dissemination point for multiple renderings of information, Transcoding Technologies eliminates the expense of re-authoring or porting data or applications for multiple networks and devices. Transcoding Technologies extend the reach of information to a new class of users. Transcoding Technologies transform content based on the information associated with the request, such as device constraints and organizational policies. Web content can be transformed differently for different devices. Transcoding Technologies can support all common types of Web data, including HTML pages and Extensible Markup Language (XML). Transcoding Technologies also tailor images to adjust screen size, file size, and numbers of colors. Transcoding Technologies offer three ways to transform contents: XML stylesheets Annotators Transcoding plug-ins They are also referred to as resources in Transcoding Technologies. There is another type of resource called preference profiles, which is used to represent the characteristics of devices and users and determine which stylesheet, annotator, or plug-in to use. These four types of resources are discussed in more details in the following sections in this chapter. Note: In the following sections, the root directory at which Transcoding Technology is installed is referred to as TT_Root. You should replace this with your actual directory name, for example, C:Program FilesIBMTrans. 2 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  14. 14. 1.1.1 Architecture Transcoding Technologies in WebSphere Everyplace Access are invoked at two different levels: Portlet-level transcoding. This is used for content transformations. For example, markup language conversions, stylesheets, and annotators are applied at this level. Portal page level transcoding. This is used for whole page modifications. For example, content fragmentation. Figure 1-1 illustrates the transcoding technologies as implemented in IBM WebSphere Everyplace Access Version 4.1. Transcoding Technologies 11 10 7 6 12 9 8 Portlet Filter 1 Portal 2 3 Filter 4 Portlet 5 Aggregator Portal Figure 1-1 Transcoding technologies in WebSphere Everyplace Access The request flow can be explained as follows: 1. The user agent (WAP browser, Pocket PC browser, desktop browser) makes a request to the portal. In this environment the request is previously received by the portal filter. 2. The portal filter calls the portal to receive its contents, which calls the aggregator to aggregate the page. Chapter 1. Transcoding Technologies 3
  15. 15. 3. The aggregator selects portlets based on a combination of values, like user credentials and whether the portlet supports the current aggregator. If a portlet is configured to be transcoded and it provides a markup that Transcoding Technologies can use, it will be selected as well. For example, if the portlet provides HTML and the client needs WML content, the aggregator will select the portlet because the portlet content must be transcoded. Therefore, for a portlet that is configured to use Transcoding Technologies, the aggregator calls the portlet filter as if it were a proper portlet. 4. The portlet filter calls the portlet to receive its contents. 5. The portlet returns its contents. 6. The portlet filter sends the portlet’s contents to Transcoding Technologies for processing, associating the portlet’s contents with a default URI, unless otherwise specified. This step is known as portlet-level transcoding. Note that the portlet thinks it is communicating directly to the aggregator, so no special programming style is needed to write a portlet that is filtered. 7. Transcoding Technologies returns the processed contents to the portlet filter. 8. The portlet filter returns the processed contents as if it were a proper portlet returning contents normally. 9. The aggregator, having finished aggregating the page, returns the page. 10.The portal filter sends the portal’s aggregated contents to Transcoding Technologies for processing. This step in known as portal-level transcoding. 11.Transcoding Technologies returns the processed contents. 12.The portal filter returns the processed contents. 1.1.2 Preference profiles A preference profile can represent a particular type of device, or a particular user or group of users. Transcoding Technologies use preference profiles to decide how to treat documents that will be delivered to different devices and different users. For example, on a device with a small screen, it may be desirable to convert tables to lists to reduce horizontal scrolling. For a particular user, images should be eliminated altogether. When Transcoding Technologies processes a document, it selects a device profile and a user profile to apply to the document. Device preference profiles are represented by .prop files located in: <TT_Root>etcpreferencesdevice 4 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  16. 16. User preference profiles are represented by .prop files located in: <TT_Root>etcpreferencesuser If the X-IBM-PVC-Device-Type field is present in the HTTP header, Transcoding Technologies uses the device profile whose file name matches the value specified for that field. The value of the X-IBM-PVC-Device-Type field is set by WebSphere Portal’s preference aggregation. For example, if the value of X-IBM-PVC-Device-Type is Microsoft!Internet+Explorer!6.0, the following device preference profile will be used: TT_RootetcpreferencesdeviceMicrosoft!Internet+Explorer!6.0.prop Figure 1-2 illustrates the properties file for Microsoft Internet Explorer Version 6. #version = 1.0 #Wed Jul 10 12:55:23 CDT 2002 framesSupported=true deviceRule=(User_Agent%e*MSIE 6.0*) javaAppletsSupported=true portalOrdinal=360 portalMarkupVersion=ie createCHTML=false portalClient=true desiredContentTypes=[text/html] parent=NT.InternetExplorer javaScriptSupported=true Figure 1-2 Microsoft!Internet+Explorer!6.0.prop If the X-IBM-PVC-Device-Type field is not present in the HTTP header, Transcoding Technologies uses the device profile whose user-agent value matches the value of the user-agent field in the HTTP header. If no matching profile is found, Transcoding Technologies uses the default device profile. User resources are not maintained through Transcoding Technologies. However, other programs can pass information to Transcoding Technologies specifying the use of a user profile. A user profile is selected for a request following these steps: If a value is specified for userAndSessionExtractor in etc/localConfig.prop, Transcoding Technologies tries to execute the referenced implementation of the UserAndSessionExtractor interface to obtain user and session names and select the user profile that matches the user name. You can specify a field in the HTTP header to be used to select a user profile by setting the httpUserIdField value in etc/localConfig.prop. For example, if you Chapter 1. Transcoding Technologies 5
  17. 17. specify httpUserIdField=X-UserField, then Transcoding Technologies would find the value of the X-UserField keyword in the HTTP header and select the user profile that matches that value. If the X-IBM-PVC-User field is present in the HTTP header, Transcoding Technologies uses the user profile that matches the value specified for that field. If none of these checks identifies a user profile, then Transcoding Technologies does not use a specific user profile. If one of these methods is used to specify a user profile and the specified file is not found, Transcoding Technologies does not try the other methods; it does not use a specific user profile. For example, if you specify httpUserIdField=myUserField but myUserField is not specified in the HTTP header, Transcoding Technologies would not look for the X-IBM-PVC-User field. If more than one device preference profile matches the incoming request, it is impossible to predict which of the matching profiles would be selected. For example, if you create two device profiles with expressions that could match the same user-agent value, either one could be selected for a request that specifies that user-agent value. Be sure to specify unique values for any new profiles you create. Each profile contains values for the preferences that are important to the device that the profile represents. If a preference is not important to the device, it can be omitted so that a value can be chosen from a different profile. For most preferences, Transcoding Technologies will check profiles for a value in this order: 1. Specific user 2. Specific device 3. Default user 4. Default device If a value is not specified for a preference in one profile, Transcoding Technologies will work down the list until it finds a value. The transcoding plug-ins that will be applied to the document are selected based on the combined profiles. Transcoding Technologies provides profiles for several common pervasive devices. There are default profiles to be used if none of the existing profiles matches the device being used. In addition to determining which transcoding plug-ins will be used, a profile can be used to select a stylesheet or annotator. You can also specify parameters to be used by stylesheets that accept parameters. 6 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  18. 18. 1.1.3 XML stylesheets When Transcoding Technologies processes documents composed in Extensible Markup Language (XML), it uses XSL stylesheets to convert these documents to any markup language, such as HTML, WML, or other forms of XML. Stylesheets can be registered using the XML Config tool and be visible to all portlets. Alternatively, stylesheets can be set for specific portlets using Portal Administration. For details see Chapter 3, “Using XSL stylesheets” on page 47. After being registered, each stylesheet is represented by a stylesheet selector, which is mapped to a .prop file containing conditions for the selection of the stylesheet for use by Transcoding Technologies. A stylesheet is selected to process a document based on the values of one or more fields in the HTTP header, including the URL, and on the name or URL of the input DTD. A stylesheet can also be selected based on criteria that match a preference profile. Some stylesheets accept parameters that affect how they operate on documents. A stylesheet that accepts parameters can retrieve values for the parameters from: The HTTP header of the request Values specified for the Parameters field in the XML config file Values specified in a preference profile 1.1.4 Annotators For pervasive devices with limited screen size, it is often desirable to show only the key information from a Web page, and get rid of the less critical stuff such as graphics and other gimmicks. Annotators can be used to specify which portions of a Web page to include or discard when the page is transcoded. There are two types of annotators and they are: Internal annotators. They can be created using the tools available in WebSphere Studio Application Developer and WebSphere Studio Site Developer. Internal annotators are special tags embedded in the original Web page. When the page passes through Transcoding Technologies, these tags are examined and acted upon. For details about and samples of internal annotators see 2.2, “Internal annotation” on page 27. Chapter 1. Transcoding Technologies 7
  19. 19. External annotators come as separate and independent annotation files that the Transcoding Technology uses to operate on the original Web page. External annotators can be created with simple text editors, or with tools supplied in the Pervasive Toolkit. External annotators can be registered using the XML Config tool and be visible to all portlets. Alternatively, external annotators can be set for specific portlets using Portal Administration. For details see Chapter 2, “Using annotation for document clipping” on page 25. After being registered, each annotator is represented by an annotator selector, which contains conditions for the selection of the annotator for use by Transcoding Technologies. An annotator is selected based on the values of one or more fields in the HTTP header, including the URL. An annotator can also be selected based on criteria that match a preference profile. For details about and samples of external annotators see 2.3, “External annotation” on page 36. 1.1.5 Transcoding plug-ins A transcoding plug-in is a program written with programming languages that modifies the content of a document. Transcoding plug-ins are selected to process a document based on conditions specified by the program when the transcoding plug-in is created. Several transcoding plug-ins are provided with Transcoding Technologies in WebSphere Everyplace Access, and you can obtain or develop others. The image transcoding plug-in modifies images to better support the display capability of a device. The text transcoding plug-in converts textual data, such as HTML or XML, from one format to another and can perform a number of transformations to simplify the output. The fragmentation transcoding plug-in fragments XML documents into pieces small enough to be managed by the target device. The HTML DOM generator creates a Document Object Model (DOM) version of incoming HTML documents. The annotation transcoding plug-in, also called annotation engine, interprets the contents of files written with Transcoding Technologies' annotation language to perform document clipping. The HTML to WML transcoding plug-in converts HTML documents to WML for devices with WAP browsers. 8 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  20. 20. The HTML to compact HTML transcoding plug-in converts HTML documents to Compact HTML documents for devices with CHTML browsers. These transcoding plug-ins are installed with the product and enabled by default (with the exception of the HTML DOM generator). To verify whether the transcoding plug-ins are enabled or to change their status, use the XML Config tool. 1.2 XML Config tools The Transcoding Administration Console cannot be used in this release. Therefore, a set of command line tools are provided to effectively perform the following tasks: Export resources Import resources Disable resources Enable resources Note: Resources such as device profiles, stylesheet registrations, and external annotator registrations can be configured using this tool. For an example on how to use these commands see 3.3.2, “An alterative - Register the stylesheet” on page 53. 1.3 Request Viewer Request Viewer is a very useful visual tool for monitoring the traffic going through Transcoding Technologies. You can view the configuration and status information of the registered transcoding plug-ins within Transcoding Technologies. Request Viewer is particularly handy as a debugging tool, because it enables you to examine the flow of requests and responses through the server and observe which plug-ins are triggered and when they are triggered. For each transaction, Request Viewer also displays the header and content information as they are manipulated by the transcoding plug-ins. Note: Request Viewer can also be used to monitor traffic on a remote machine running Transcoding Technologies. Chapter 1. Transcoding Technologies 9
  21. 21. Figure 1-3 shows the Request Viewer’s Server Configuration window. In this window, all the registered transcoding plug-ins are displayed in the upper left panel, the upper right Details panel shows the configuration and status information for the transcoding plug-ins. Figure 1-3 Request Viewer - Server Configuration window The Request Viewer’s Request Processing window shows the flow of the requests and responses captured. The Transaction Header panel displays all the HTTP headers in the requests and responses, while the Transaction Content panel shows the body of the requests and responses. For a sample Request Processing window see Figure 1-16 on page 24. 1.3.1 How to start Request Viewer The following procedure can be used to extract and start the Request Viewer tool: 1. Locate the file wtpscripts.jar in the Transcoding Technology root directory; for example, c:Program FilesIBMTrans. 2. Expand this jar file using an unzip tool such as WinZip. 10 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  22. 22. 3. Locate RequestViewer.bat in the expanded jar file. 4. Extract this file to the Transcoding Technology root directory; for example, c:Program FilesIBMTrans. 5. From a command line run RequestViewer.bat. 6. A dialog pops up asking information about the machine where Transcoding Technologies is running. If it is running on the same machine, click Local, if it is on a remote machine, you will need to supply the necessary information. Click OK. Figure 1-4 Starting Request Viewer Note: The Request Viewer tool uses the RMI protocol when monitoring remote Transcoding Technologies in WebSphere Everyplace Access. For local monitoring, RMI is not required. 7. Request Viewer will be started. Chapter 1. Transcoding Technologies 11
  23. 23. Figure 1-5 Request Viewer started Note: Request Viewer is a monitoring tool; therefore, you cannot change the configuration or status of the transcoding plug-ins with it. 1.4 Logging and tracing To turn on tracing for Transcoding Technologies: 1. Log in to WebSphere Portal as an administrator, choose Portal Administration page group, choose Portal Settings page, and Enable Tracing portlet. 12 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  24. 24. Figure 1-6 Enable tracing portlet 2. Scroll down the page, find TranscodingTraceLogger, and check the box beside it. See Figure 1-7 on page 14. Chapter 1. Transcoding Technologies 13
  25. 25. Figure 1-7 Enable tracing for Transcoding Technologies 3. Click Save after you have selected the desired trace options. 1.4.1 Message files Message files are created in the TT_Rootlog directory. The first message file created is named TranscoderMessages1.log. When the maximum size is reached, this file will be renamed to TranscoderMessages2.log and a new TranscoderMessages1.log file created for new messages. TranscoderMessages1.log is always the newest file. The default message file size is 512 kilobytes. When the maximum number of message files have been filled, the oldest file will be deleted, the suffix number of each remaining file will be increased by one, and a new TranscoderMessages1.log will be created for new messages. A new file is begun when Transcoding Technologies is restarted. The default number of message files is three. Message file size and maximum number of message files are defined in the properties file: TT_RootetcrasTranscoderRASMessageFileHandler.properties 14 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  26. 26. 1.4.2 Tracing files Tracing records the specific behavior of Transcoding Technologies, recording information useful in the diagnosis of problems. Trace files are created in the TT_Rootlog directory. The first trace file created is named WebSphere Portal Server 4.1_TranscoderTrace1.log. When the maximum size is reached, this file will be renamed to WebSphere Portal Server 4.1_TranscoderTrace2.log and a new WebSphere Portal Server 4.1_TranscoderTrace1.log file created for new messages. The default trace file size is 512 kilobytes. WebSphere Portal Server 4.1_TranscoderTrace1.log is always the newest file. When the maximum number of trace files has been filled, the oldest file will be deleted, the suffix number of each remaining file will be increased by one, and a new WebSphere Portal Server 4.1_TranscoderTrace1.log will be created for new messages. A new file is begun when Transcoding Technologies is restarted. The default number of trace files is three. Tracing file size and maximum number of tracing files are defined in the properties file: TT_RootetcrasTranscoderRASTraceFileHandler.properties 1.4.3 Gather troubleshooting data When running into problems using Transcoding Technologies, there is a certain set of information that will be useful in troubleshooting. There is a program named RASCollect in Transcoding Technologies’s root directory. Executing RASCollect.bat on Windows or RASCollect.sh on AIX, Solaris, or Linux will package the necessary files and settings to make it easy to gather diagnostic information. When it finishes execution, a zip or tar file will be created in directory TT_Rootlog that you can send to the relevant people for diagnosis. It will be named RASCollect.zip on Windows NT, Windows 2000, or Linux, and RASCollect.tar on AIX or Solaris. 1.5 A simple portlet using Transcoding Technologies In this section we include a sample scenario to show how to enable transcoding in WebSphere Everyplace Access. The sample scenario is illustrated in Figure 1-8 on page 16. Chapter 1. Transcoding Technologies 15
  27. 27. Everyplace Wireless Gateway WTE forward proxy WebSphere HTTP HTTP Everyplace Access WAP WAP Proxy and Gateway Transcoding Technologies WAP/IP WAP Simulator Figure 1-8 Transcoding sample scenario 1.5.1 Enable transcoding To give an example of how to enable Transcoding Technologies for a portlet, a very simple HelloWorld portlet is used, which does nothing but display a Hello World message. The portlet descriptor (portlet.xml) for this portlet is shown in Example 1-1. Example 1-1 portlet.xml for HelloWorld portlet <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" "portlet_1.1.dtd"> <portlet-app-def> <portlet-app uid="DCE:25400630-8a18-1201-0000-005d15e0e1ac:1" major-version="1" minor-version="0"> <portlet-app-name>HelloWord application</portlet-app-name> <portlet id="Portlet_1" href="WEB-INF/web.xml#Servlet_1" major-version="1" minor-version="0"> <portlet-name>HelloWord portlet</portlet-name> <cache> <expires>0</expires> <shared>NO</shared> </cache> <allows> <maximized/> <minimized/> </allows> 16 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  28. 28. <supports> <markup name="html"> <view/> </markup> </supports> </portlet> </portlet-app> <concrete-portlet-app uid="DCE:25400630-8a18-1201-0000-005d15e0e1ac:1.1"> <portlet-app-name>HelloWord application</portlet-app-name> <concrete-portlet href="#Portlet_1"> <portlet-name>HelloWord portlet</portlet-name> <default-locale>en</default-locale> <language locale="en"> <title>HelloWord portlet</title> <title-short></title-short> <description></description> <keywords></keywords> </language> </concrete-portlet> </concrete-portlet-app> </portlet-app-def> Install this portlet into WebSphere Portal. To enable this portlet to use Transcoding Technologies, do the following: 1. Log in to WebSphere Portal as an administrator, for example, wpsadmin. 2. In Portal Administration page group, Portal Settings page, Global Settings portlet, check the box for Enable transcoding of portlet content. Chapter 1. Transcoding Technologies 17
  29. 29. Figure 1-9 Enable global setting for Transcoding Technologies 3. In Portal Administration page group, Portlets page, Manage Portlets portlet, choose the HelloWorld portlet, and click Modify parameters. 18 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  30. 30. Figure 1-10 Choose HelloWorld portlet to modify its parameters 4. Add a parameter named FilterChain, with the value Transcoding. Click Save. Chapter 1. Transcoding Technologies 19
  31. 31. Figure 1-11 Add the parameter to enable transcoding 5. Add this portlet to a desired page group and page, for example, the Welcome page of WebSphere Everyplace Access home page group. View this portlet in a normal desktop browser. 20 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  32. 32. Figure 1-12 HelloWorld portlet displayed in a desktop browser 6. Use Nokia Mobile Internet Toolkit to view the portlet with a WAP browser. Start Nokia Mobile Internet Toolkit by clicking Start -> Programs -> Nokia Mobile Internet Toolkit -> Mobile Internet Toolkit. 7. Next, you will configure the WAP Simulator to access the portlet. In the Nokia WAP Simulator, a connection profile is required and this profile can be for a direct HTTP connection to your Application Server or a WAP/IP connection if you plan to connect using a WAP Gateway. Figure 1-13 on page 22 shows a sample HTTP connection profile and a sample WAP/IP profile. Click Settings -> Toolkit Preferences to get to this window. Chapter 1. Transcoding Technologies 21
  33. 33. Figure 1-13 Nokia Mobile Internet Toolkit preferences 8. In the Go field, type the portal page URL and press Enter. Figure 1-14 Type portal page URL 22 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  34. 34. 9. The Welcome page is shown on the simulator. Scroll down to HelloWorld portlet and select it. The transcoded portlet is shown in the WAP browser. Figure 1-15 Welcome page and HelloWorld portlet displayed in WAP browser 1.5.2 Use Request Viewer to monitor the process Request Viewer can be used to observe and monitor when the portlet and portal page are transcoded. Open Request Viewer and use the WAP browser to access HelloWorld portlet. When HelloWorld portlet is opened on the WAP browser, Request Viewer has captured some activities in its Request Processing window. In this sample scenario, there are three entries. The first one is for building the Welcome portal page, the second one transcodes the HelloWorld portlet into WML, while the third one is for building the portal page with HelloWorld portlet opened. As illustrated in Figure 1-16 on page 24, you can expand each transcoder the request goes through and examine the content changes in MEG Input and MEG Output. Chapter 1. Transcoding Technologies 23
  35. 35. Figure 1-16 Request Viewer 24 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  36. 36. 2 Chapter 2. Using annotation for document clipping In this chapter document clipping using the Transcoding Technology within WebSphere Everyplace Access (Everyplace Access) is introduced. Clipping is an approach used to manipulate an HTML document to meet the characteristics of the requesting device. By using the annotation language, the developer can instruct the Transcoding Technology on how to modify and clip an incoming HTML document and generate the customized output. The developer has the ability to specify when particular annotation files or individual annotation instructions are executed against an HTML document. This is based on information contained in the HTTP header or the device profile. This chapter contains the following: An overview of annotations for Transcoding Technology An example of internal annotation using WebSphere Studio An example of using external annotation for different devices © Copyright IBM Corp. 2002. All rights reserved. 25
  37. 37. 2.1 Annotation overview Document clipping allows an enterprise to deploy existing Web content to mobile devices without having to create new versions of the existing content. This ability allows the enterprise to expand the reach of their existing Web applications and allows their mobile workers greater access to information and data. Annotation, a clipping technique, allows you to specify the document content to be affected and the action to be performed on that content. Annotation, an XML dialect, consists of various instructions that are used by the Transcoding Technology to perform the customization. Annotation instructions can be associated with the HTML document in two ways: 1. External annotations: The annotation instructions are located in a separate file (.ann file). These instructions consist of two parts, which are: – The location: The XPath of the element within the HTML document where the action is to be applied. – The action: The particular activity that is to occur against a particular portion of the HTML document (as specified by the XPath). The action may be applied to a particular HTML tag, a group of HTML tags, or to specific content. 2. Internal annotations: The annotations reside within the HTML document. They are represented as comments within the HTML file. Internal annotations consist of the actions and are located immediately before the associated HTML tag, group of associated HTML tags, or content. Both external annotations and internal annotations are processed by the Transcoding Technology within Everyplace Access. Transcoding Technology contains an annotation editor that processes the annotation instructions and creates a clipped version of the document as output. The overall set of annotation instructions available are: remove Removes associated HTML tag(s) and content keep Keeps associated HTML tag(s) and content table Effects overall table (in particular, the heading) column Removes a complete table column row Removes a complete table row field Modifies fields within a form option Used to specify a selectable option insertattribute Allows insertion of an attribute into an HTML tag inserthtml Allows insertion of HTML 26 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  38. 38. replace Replaces the specified content within the HTML document with the content specified replacewithhtml Replaces the associated HTML tag with the new HTML tag specified within the instruction setpreference Sets a preference that the Transcoding Technology will use with transcoding the HTML document splitpoint Identifies your preferred fragmentation point to the Transcoding Technology 2.1.1 Annotation processing The input to annotation is a Document Object Model (DOM) containing the source HTML document. You can think of the DOM as a tree representation of the source document. If you are using external annotations, the annotation instructions are inserted into the DOM according to the XPath and before/after attribute of the annotation instruction. Next the DOM is processed by traversing the tree. The annotation instructions are processed as they are encountered within the DOM. The keep or remove state is maintained according to the annotation instructions that are encountered. The result of the annotation process is a DOM with the modified structure and content. This DOM is input to the rest of the transcoding process with the final result in the markup language needed for the target device. 2.2 Internal annotation As stated earlier, for internal annotation, the annotation instructions are embedded directly into the HTML document. The new WebSphere Studio products provide the capability to create HTML documents and JSPs. The WebSphere Studio products support annotation of HTML documents. The sample scenarios in this chapter have been developed using WebSphere Studio Site Developer Advanced, which is included with Everyplace Access. The Everyplace Toolkit (a WebSphere Studio plug-in provided by Everyplace Access) has also been installed. The Everyplace Toolkit provides the tools to create and manage portlets. Note: In all subsequent references to WebSphere Studio Site Developer Advanced in this chapter, the term WebSphere Studio is used. Chapter 2. Using annotation for document clipping 27
  39. 39. 2.2.1 Page Designer in WebSphere Studio The portlet perspective within WebSphere Studio is used to create a sample portlet, as well as the JSP and HTML content emitted by the JSP. The WebSphere Studio Page Designer is a visual tool that allows you to create JSP statements and HTML content. The Page Designer has three views, which are: 1. Design: A WYSIWYG editor that allows you to visually construct the page. This editor is also used to specify your internal annotations 2. Source: An editor that allows you to view and edit the JSP and HTML source 3. Preview: A viewer that allows you to see the HTML as it would appear within a browser The WebSphere Studio Page Designer is used to create the HTML content the JSP will generate. Next the Page Designer is used to annotate the HTML content. With Page Designer, you can identify the HTML content that is to be annotated and specify the type of annotation that is to occur. Page Designer provides the following annotation instructions: Remove or keep HTML tags or content: Either individual tags or groups of tags. Replace text: Replace tags and their content with text. Note that using replace text removes the HTML tags so any styling provided by the HTML tag(s) is lost. Remove table rows or columns: Selected rows or columns can be deleted from the associated table. Multiple rows or columns can be removed in any combination. Propagate tables headings: Allows column headings to be propagated as labels with the row content when rendering the tables as lists. For a good overview on Page Designer in relation to creating internal annotations, refer to Section 5.4 in IBM WebSphere Everyplace Server Service Provider and Enable Offerings: Enterprise Wireless Applications, SG24-6519. 2.2.2 Sample application: The Redbook News The Redbook News application is a simple application that consists of a basic portlet named TheRedbookNews.java and a JSP named TheRedbookNews.jsp that emits the HTML. This simple example is intended to show you various annotation capabilities within Page Designer. For example, in this scenario a table and various text areas are included to show various annotation instructions. Figure 2-1 on page 29 shows the HTML content in Page Designer’s Design view. 28 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  40. 40. Figure 2-1 TheRedbookNews.jsp in Page Designer - Design view Using the Design view within WebSphere Studios Page Designer, internal annotation instructions are created. The annotation default state is set to keep. However, if you are going to remove more content than you are going to keep you may want to change the annotation default state, which could minimize the number of instructions you would need to create. Text replacement Because many mobile devices have very small screens it is important be very selective about the content sent to that target device. The Text Replacement function provides the ability to replace the associated text with your text replacement. This may be a shorter version of the original text. One draw back to this function is that the associated HTML tags are removed and you are not allowed to enter HTML tags in the text. So any HTML tags used for positioning and improved presentation of the information are lost. The steps to do text replacement are as follows: 1. In Design view click the area that you want to replace; in this case it is The IBM Raleigh ITSO News for 07/20/2002. Chapter 2. Using annotation for document clipping 29
  41. 41. 2. Right-click and a drop-down list will appear. 3. Click Annotation -> Set Text Replacement, as shown in Figure 2-2, and a text box will appear, as shown in Figure 2-3. 4. Enter your new (replacement) text into the text entry box, as shown in Figure 2-3, and click OK. Figure 2-2 Selecting Text Replacement Figure 2-3 Enter replacement text 30 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  42. 42. Tip: If you prefer to work from the menu bar rather than using the right mouse button to get to the annotation option, you can click Edit (on the menu bar), and move your mouse to the Annotate entry in the drop-down list. While the mouse is on the Annotate entry, the available annotation options with appear in the another drop-down list. You can select the appropriate action. The rest of the steps are the same as when using the right mouse. Remove or keep elements To remove or keep an area with the Design view, perform the following steps: 1. Highlight the area you wish to remove or keep. For example, select multiple HTML tags and content to remove. You can select large regions with multiple HTML tags or select each HTML instance individually, whichever approach you prefer. 2. Right-click on the area and, as before, the options list will appear. 3. Click Annotation -> Set Remove Region. When this operation is complete the specified area will have hash marks through it, as shown in Figure 2-4. Figure 2-4 Results of remove annotation Removing columns or rows from a table Tables are a very nice way to represent information in a Web page; however, some mobile devices do not have the space to display a large table. Page Designer has annotation instructions that allow you to simplify a table. You can remove rows and columns from a table or remove the column headings. In this instance, columns from the table will be removed. For example, you can use the following steps to remove a column or row from a table: 1. Select an entry in the table (column or row) you want to clip. 2. Go to the menu bar and click Edit -> Attributes. The Attributes panel appears, as shown in Figure 2-5 on page 32. Switch to the Table tag, if not already displayed. Chapter 2. Using annotation for document clipping 31
  43. 43. 3. Click the Annotation tab. 4. Click either Remove this column or Remove this row, as shown in Figure 2-5. In this case, for example, you will click Remove this column and then click OK. When the operation is processed the column appears with hash marks through it (within the Design view). Figure 2-5 Remove column from table Instead of using the propagate table headings annotation instruction, the headings from the table will be removed by selecting the heading and using the remove rows option. All the annotations The complete set of annotations (represented in the Design view) is shown in Figure 2-6 on page 33. These are the unique annotations performed for this sample scenario. To get the desired results you will use similar actions on various parts of the document. Figure 2-6 on page 33 shows the hash marks in the different areas where content will be removed. 32 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  44. 44. Figure 2-6 Design view with all the annotations An example of an internal annotation for text replacement is shown in Example 2-1. Example 2-1 Internal annotations <tr><td><font face="arial,sans-serif,helvetica" size="3"> <!--METADATA type="Annotation" startspan <?xml version="1.0"?><annot version="1.0"> <replace><text>ITSO News</text></replace></annot>--> <B>The IBM Raleigh ITSO News for 07/20/2002</B> <!--METADATA type="Annotation" endspan--></font></td></tr> The internal annotation (in Example 2-1) shows replacing the text The IBM Raleigh ITSO News for 07/20/2002 with ITSO News. Please note that the complete annotation instruction appears before the HTML tag and content that it is to effect. Also note that the internal annotation instruction is represented as a comment. The results of internal annotation After the portlet is installed and configured on the WebSphere Everyplace Access home page, you must make sure the portlet is available to transcoding by adding the parameter FilterChain = Transcoding to the portlet. To set the parameter, execute the following steps within Portal Administration: 1. Click Manage Portlet to see the portlets. Chapter 2. Using annotation for document clipping 33
  45. 45. 2. Highlight the TheRedbookNews portlet and click Modify Parameters. 3. On the Configure parameters and titles panel, specify FilterChain as the parameter and Transcoding as the value. 4. Finally, click Add and then click Save. A new portal session is started using Internet Explorer to view the updated WebSphere Everyplace Access home page. You will notice that the new portlet (displayed within Internet Explorer) contains the annotations intended for the WML browser only. In this situation, you have two options: 1. Disable transcoding for Internet Explorer (IE). This is done by disabling transcoding within the device resource for the Internet Explorer device profile(s). To do this set the <Enable> element value to false in the device profile and execute the ImportResources command against the file with the device profile. 2. Modify the internal annotations to include a condition statement that blocked the annotations from being processed for IE. In this sample scenario, the internal annotations that affect each annotation instruction within the HTML document are modified. To do this you will edit the annotation instructions within the Page Designer Source view. For example, a modified annotation instruction with the condition (which is highlighted) is shown in Example 2-2. Example 2-2 Annotation instruction with condition <tr><td><font face="arial,sans-serif,helvetica" size="3"> <!--METADATA type="Annotation" startspan <?xml version="1.0"?> <annot version="1.0" condition=”!(user-agent=*IE*)”> <replace><text>ITSO News</text></replace></annot>--> <B>The IBM Raleigh ITSO News for 07/20/2002</B> <!--METADATA type="Annotation" endspan--></font></td></tr> Next, the portal with the modified version of TheRedbookNews portlet is updated and another Internet Explorer portal session is started. The results should show that no annotation takes place for Internet Explorer. The Internet Explorer view of the portlet is shown in Figure 2-7 on page 35. 34 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  46. 46. Figure 2-7 Internal annotation results in Web browser Next the Nokia Mobile Internet toolkit is started and the portal URL is entered. The Redbook News portlet is selected and the annotated WML document appears. The complete dialogue is shown in Figure 2-8. Figure 2-8 Internal annotation results in Nokia browser Internal annotations for Pocket PC The condition instructions within the internal annotation file will be changed before running with the Pocket PC. For example, the new condition is !device=*Internet+Explorer. An annotation statement with the new condition is shown in Example 2-3 on page 36. Chapter 2. Using annotation for document clipping 35
  47. 47. Example 2-3 New annotation condition <annot version="1.0" condition="!(device=*Internet+Explorer*)"> <replace><text>ITSO News</text></replace></annot>--> <B>The IBM Raleigh ITSO News for 07/20/2002</B> <!--METADATA type="Annotation" endspan--></font></td></tr> The results in the IE browser and the WML browser are the same. The results with the Pocket PC are shown Figure 2-9. Figure 2-9 Internal annotation in Pocket PC 2.3 External annotation External annotation allows you to store your annotation instructions in a separate file away from the target HTML source. This approach is appropriate when the developer does not have control over the source HTML or has different annotation instructions for different situations and does not want to use the internal annotation condition statements. 36 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  48. 48. There are two key parts to an annotation instruction, which are: 1. Annotation markup action: The particular action to be taken against the HTML element(s) 2. XPath location: The exact location of the element(s) within the HTML source to take the action against For internal annotations the XPath was not necessary because the annotation instruction was located in relationship to the HTML tag(s); they were intended to effect. However, the external annotations are in a separate file, so the XPath provides the location of the element(s) to be effected. XPath is a Worldwide Web Consortium (W3C) specification that provides the syntax used to identify the location of all the elements and content within an HTML or XML document. 2.3.1 The external annotation language Because the external annotation language is an XML dialect, the first entry within the file is the XML version statement, represented as <?xml version='1.0' ?>. Next is the root element for the annotation language represented as <annot version=2.0>. Each annotation instruction is represented in a <description> element, which can consist of: condition = text Defines the condition that must be true for the annotation action to be applied. This is an optional attribute. take-effect = before or after Identifies when the annotation is to occur, either before or after the target node. target = XPath Identifies the target node (as defined by the XPath to a given element). <action> element A child element that states the action to be taken. There are several actions (some of the most important ones are included), which are; <inserthtml>, <insertmarkup>, <keep>, <remove>, <replace>, <replacewithhtml>, <setpreferences>, <splitpoint>, <table>. Example 2-4 on page 38 shows an annotation instruction. This particular annotation shows replacing the text at location target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]" with the text ITSO Redbook News. Chapter 2. Using annotation for document clipping 37
  49. 49. Example 2-4 External annotation description element <description target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]"> <replace><text>ITSO Redbook News</text> </replace> </description> 2.3.2 Sample scenario: RedbookNews02 In this sample scenario, the RedbookNews02 application is used to show external annotations. This sample is a variation of the Redbook News application (used for internal annotations). The RedbookNews02 application consists of the RedbookNews02.java portlet and the RedbookNews02.jsp, which emits the HTML. The HTML consists of headings, text, and tables allowing us to show various annotation instructions. The RedbookNews02 application, without any annotations applied, is shown in Figure 2-10. Figure 2-10 RedbookNews02 without annotations The HTML document itself is seen in Example 2-5 on page 39. 38 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  50. 50. Example 2-5 Redbook02 HTML <html> <HEAD><META name="GENERATOR" content="IBM WebSphere Studio"></HEAD> <Title>The Redbook News</Title> <body bgcolor="#FFFFFF"> <!-- header & logo --> <center> <h3>The IBM Raleigh ITSO News for 07/23/2002</h3> <P> <FONT face="Arial" size="2" color="#0000cc"> <B>Thanks for stopping by.</B></FONT> </P> <P><FONT face="arial,sans-serif,helvetica" size="2"> <B><I>We have Four (4) New Books Available TODAY! </I></B></FONT> </P> <table border="2"> <TR align="left"> <TH width="28">No.</TH> <TH width="307"> <CENTER><FONT face="arial,sans-serif,helvetica" size="2"> <B>Book Title </B></FONT></CENTER> </TH> <TH width="83">IBM Form#</TH> <TH width="57">Published</TH> </TR> <tr align="left"> <td width="28">1</td> <td width="307"><font face="arial,sans-serif,helvetica" size="2"> <B>The Wireless Enterprise </B></font></td> <TD width="83">SG99-9907</TD> <TD width="57">07/20/02</TD> </tr> <tr align="left"> <td width="28">2</td> <td width="307"><font face="arial,sans-serif,helvetica" size="2"> <b>Building Portals </b></font></td> <TD width="83">SG99-9908</TD> <TD width="57">07/21/02</TD> </tr> <tr align="left"> <td width="28">3</td> <td width="307"><font face="arial,sans-serif,helvetica" size="2"> <b>Easy Application Development </b></font></td> <TD width="83">SG99-9909</TD> <TD width="57">07/21/02</TD> </tr> Chapter 2. Using annotation for document clipping 39
  51. 51. <tr align="left"> <td width="28">4</td> <td width="307"><font face="arial,sans-serif,helvetica" size="2"> <b>Annotations For Fun</b></font></td> <TD width="83">SG99-9910</TD> <TD width="57">07/22/02</TD> </tr> </table> <P><font face="arial,sans-serif,helvetica" size="2" ><B><I> For details on these books and our vast selection of books - visit our website!!!</I></B></font></P> <table border="0"> <tr align="center"><td><FONT face="arial,sans-serif,helvetica" size="2" color="#FF0000"><B>IBM International Technical Support Organization</B></FONT></td></tr> <tr align="center"><td><font face="arial,sans-serif,helvetica" size="2"><a href="http://www.redbooks.ibm.com">http://www.redbooks.ibm.com</a></font></td>< /tr> </table> </center> </body> </html> For this application there are three target devices, and they are: Internet Explorer Pocket PC - Compaq Ipaq Wap Browser - Represented by the Nokia Toolkit An external annotation file is created for each of these client devices. Portlet parameters After the portlet is installed and configured on the WebSphere Everyplace Access home page, you will need to modify the portlet parameters using the Manage Portlet’s Modify Parameters option. Listed in Table 2-1 are the parameters and their values. Table 2-1 tPortlet parameters Parameter Value FilterChain Transcoding URI http://m23x303x.itso.ral.ibm.com/RedbookNews02.jsp 40 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  52. 52. The new parameter is the URI. This parameter will be used by the Transcoding Technology to associate the annotation resources to this JSP. This will be discussed further later in this chapter. Registering annotation files Because in this sample scenario three different annotation files (one for each target device) are created, the annotation files will be registered with the transcoding server. In order to do this you will need to create <Annotator> element resources and use the ImportResources command to register them. Also, the transcoding server needs a way to determine, which annotation file to process for a particular target device. In addition, the <keys> element will be used within the annotation resources to identify each annotation file to the associated target device. Within the <Annotator> element for each annotation file, you will need to include a <key> element. Each key element has a Name attribute which you will need to assign a valid key name and value. By looking at the device profiles in the WTPConfig.xml file you should find the valid keys for each device. For example, the device profiles for the Internet Explorer and the Pocket PC do not contain <keys> elements; so before you register the <Annotator> elements you will need to create <keys> elements for these devices. For example, copy the two device profiles from the WTPConfig.xml file to a new file along with the <XML> element and <Resources> element. Then add a <keys> element to each device profile. The <keys> element created for the Pocket PC is shown in Example 2-6 and the <keys> element for the Internet Explorer is shown in Example 2-7. The rest of the device description is left unchanged. Example 2-6 Keys for Pocket PC <Keys> <Key Name="deviceType">PocketPC</Key> </Keys> Example 2-7 Keys for Internet Explorer <Keys> <Key Name="deviceType">Internet+Explorer</Key> </Keys> The ImportResources command is used to register the updated device profiles. After all the changes to the device profiles are performed, you will be ready to register the annotation files (using the ImportResources command). Example 2-8 on page 42 shows the annotation entry created for the WML device. Chapter 2. Using annotation for document clipping 41
  53. 53. Example 2-8 Annotator for WML browser <Annotator> <Folder>ibm/itsotest</Folder> <SelectorName>RedbookNews02WML02</SelectorName> <Name>RedbookNews02WML02</Name> <Description>This ann file is for the Redbook News 02 </Description> <URL>http://m23x303x.itso.ral.ibm.com/RedbookNews02.jsp</URL> <Location>C:/Stylesheets/Redbook02WML.ann</Location> <Keys><Key Name="deviceType">WML Device</Key> </Keys> <Enable>true</Enable> </Annotator> Please take note that the annotator’s <URL> element contains the same information as the portlet’s URI parameter. These must match in order for the transcoding server to match the JSP with the annotation file. Internet Explorer - External annotation Even though you do not need to annotate the HTML document for Internet Explorer, it is a good way to show a simple annotation file. Internet Explorer’s annotation file contains these annotations: Replace text. Remove the first paragraph. Keep the rest of the document. Notice that this entry is not necessary because the default state is keep but it was included anyway. The annotation file for Internet Explorer is shown in Example 2-9. Example 2-9 External annotation for Internet Explorer <?xml version='1.0' ?> <annot version="2.0"> <description target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]"> <replace> <text>ITSO Redbook News</text> </replace> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[2]"> <keep/> </description> </annot> 42 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  54. 54. The results of the external annotation processing are shown in Figure 2-11 on page 43. Figure 2-11 Results - Internet Explorer Pocket PC - External annotation More text and two columns from the table (column one and column four) will be removed for the Pocket PC. In Example 2-10, the following annotation instructions are shown: Replace text. Remove content. Modify the book table (table 1) by removing row 1 and row 4 (this includes removing the associated heading). Unlike with internal annotations, you can only create annotation statements for rows and not for columns, which caused us to create annotation instructions for each row in order to remove the first and last column of the table. Example 2-10 Pocket PC external annotation file Chapter 2. Using annotation for document clipping 43
  55. 55. <?xml version='1.0' ?> <annot version="2.0"> <description target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]"> <replace> <text>ITSO Redbook News</text> </replace> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[2]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[2]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[3]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[4]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[2]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[3]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[4]"> <remove/> </description> --------repeat these instructions for Table Row 3, 4 & 5 ------- <description target="/HTML[1]/BODY[1]/CENTER[1]/P[3]/FONT[1]/B[1]/I[1]/text()[1]"> <replace> <text>Details at our website:</text> </replace> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[2]"> <keep/> </description> 44 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  56. 56. <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[2]/TBODY[1]/TR[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[2]/TBODY[1]/TR[2]"> <keep/> </description> </annot> The results of the Pocket PC external annotations are shown Figure 2-12 Figure 2-12 Results - Pocket PC external annotation WML browser - External annotation The external annotations for the WML Browser (Nokia toolkit) are similar to the external annotation instructions for the Pocket PC, expecting that you keep columns 1 and 2 (the number and the book title) of the Book table. The results displayed on the Nokia toolkit are shown in Figure 2-13 on page 46. Chapter 2. Using annotation for document clipping 45
  57. 57. Figure 2-13 Results - WML browser external annotation Tip: To run each annotation file and verify that you agree with the way the results look, set the portlet AnnotationFile parameter with a value of the location of each annotation file and use Internet Explorer as the test device. The AnnotationFile parameter’s value would be in the following format file:c:/stylesheets/Redbook02IE.ann. Also, remember to delete the AnnotationFile parameter when you are done because this parameter overrides the annotator resources. 46 Transcoding Technologies in IBM WebSphere Everyplace Access Version 4.1.1
  58. 58. 3 Chapter 3. Using XSL stylesheets In this chapter Transcoding Technology within WebSphere Everyplace Access (Everyplace Access) is used to transform eXtensible Markup Language (XML) documents to various markup languages required by mobile devices or Web browsers. It is natural to extend existing applications that generate XML documents to the Web and to mobile devices. This approach provides the enterprise with the opportunity to share XML documents with their various users (mobile and on site) while retaining one original representation of that data as XML documents. The combination of eXtensible Stylesheet Language (XSL) stylesheets and Transcoding Technology allows the transformation of XML documents for display on various mobile devices and Web browsers. Stylesheets are frequently used to convert XML documents of a particular document type to other XML dialects, HTML, and device markup languages (like WML). Stylesheets consist of rules that specify the XML document content (elements, attributes, and element content) to be processed and how that content is to be processed in order to generate the expected markup language. In this chapter the following topics are discussed: How to configure the portal for stylesheet processing How to configure a portlet for stylesheet processing How to use stylesheets with sample applications How to use multiple stylesheets against a particular XML document type © Copyright IBM Corp. 2002. All rights reserved. 47

×