Introduction

A portal lets end users choose from a specific set of portal applications (portlets) and gives them a customizable, consistent view of their choices. The set of portlets can include a wide variety of applications, such as news, stock quotes,and search, and they can be requested from many different types of devices: from a conventional HTML browser, a phone using voice interactions, or a wireless handheld device with a limited display and keyboard. Page aggregation is the process that collects information about the user's preferences, the device being used, and the selected portlets, and combines it to create a display that is appropriate for the device.

This article explains how page aggregation works for devices that support markup languages for pervasive devices, such Wireless Markup Language (WML) and Compact HTML (cHTML). It describes how to add support for new pervasive devices, and, as an example, it demonstrates how to add support for Pocket PC devices.

The examples in this article use IBM® WebSphere® Portal Version 4.1; therefore it is helpful if you have some level of WebSphere Portal development experience. For basic information about pervasive portlet development, refer to Michael Wanderski's WebSphere Portal Programming: Pervasive Portlet Development.

Back to top

Page aggregation

Aggregation, which is repeated with each request that comes from the device, involves:

1. Collecting information concerning the user, the device used, and the language used.
2. Selecting the active applications (portlets) from the set of applications that the user has access to.
3. Aggregating the output of the active portlets.

This article describes how to add support for new pervasive devices to your portal. As an example, we will demonstrate how to add support for Pocket PC devices. You will learn how a portal performs aggregation for different devices, and how to update the look and feel of the portal for your new device.

Collecting information

During the first steps of aggregation, the following information is gathered:

Selecting the active applications

During this step, the portal determines the active applications (portlets). A defined set of applications, which should be presented in a common environment, are referred to as a page. The common environment changes depending on the device. For example, in an HTML browser, the page holds all rendered applications on a common HTML page. The pages themselves can also be grouped into page groups, which are application pages that belong to the same category of tasks. With WebSphere Portal, you have the following page groups:

Home
A default set of applications

Working with Pages
Pages that hold the applications to define the layout and content of a page

Portal Administration
Pages that hold the applications used for WebSphere Portal administration (such as ACL, portal tracing, etc.)

When the portal receives a request, it determines the active page group and page for the current user, and renders all applications on the active page.

Aggregating the output

After determining the active page, the portal uses the layout of the page to aggregate the content of the defined applications, to place the output, and to integrate everything into a complete page. A page contains components that contain other components or portlets. Examples of components are column containers, row containers, and controls.

WebSphere Portal provides fully dynamic aggregation of pages from page descriptors that describe the page. It uses JSP files to render all page components. Consequently, you can easily change the look and feel of the portal. To avoid using Java scriptlets in the JSP templates, WebSphere Portal has a custom tag library that provides all required functions such as, getting date and time, looking up portal URIs, and detecting available portlet modes.

Figure 2 shows a portal page with its components:

The single components include:

Controlling the portal layout

The layout of the portal output is defined by the following:

• The window layout
• The screen layout
• The screen components layout, if they exist

You can control the window and component layouts by changing the portal themes and skins. Themes refer to the window templates and skins refer to component templates.

Themes and skins

The portal page is displayed using themes and skins defined by the Web designer or the portal administrator. Themes represent the look and feel of the portal, including colors and fonts. The theme is also used to render the portal banner. Skins represent the rendering of the border around an individual portlet. Skins use the theme name to select the graphics that match the theme colors.

Templates

Aggregation uses the concept of templates for window, screen, and component layout to allow for more flexibility when customizing. When a corresponding part needs to be rendered, a template loader will load the requested template. If a requested template cannot be found, then a default template will be used. This guarantees that there is always a valid template. The loaded template consists of two parts:

• The template class Controls the rendering, and the localization and the launch of the JSP.
• The template JSP Performs the actual rendering. Since the portal administrator can manipulate the JSP files, this allows for easy customization.

During localization, the JSP file is searched for under different paths, depending on which markup, markup version, language, themes, and skins are being used. This gives you different options for handling various devices and device groups, as well as handling language-, theme-, and skin-dependent issues. The search starts with the most complex path first.

Window templates: The window template is responsible for the layout of the parts in the banner area and the placement of the screen. For example, a window template could also place the navigation tabs on the left side of the screen instead on the top. You can modify the search path for the window templates by how you set the Theme. The default template name is: Default. The following window templates are available:

• Default Used for all portal views, except for detached windows.
• Plain Used for detached browser windows, for example, the help window, which does not have a banner area.

The search path of the Theme template JSP is composed of these parts:

• Markup (HTML, WML, cHTML, etc.)
• Theme name (WebSphere, Corporate, Finance, etc.)
• Language (en_US, en, de_DE, etc.)
• Markup Version (ie5, Ns, ppcie, etc.)
• Template name (default or plain)

The following are examples of Theme template JSPs:

 \themes\html\WebSphere\ie5\en_US\Default.jsp
\themes\html\WebSphere\ie5\Default.jsp
\themes\html\WebSphere\Default.jsp

Screen templates: The screen template is responsible for the layout and the content of a screen, which provides an interaction area for the user. One special screen template, the Home screen template, contains information on how the current page is composed. Therefore, you can use only this screen to show the output of the portlets. The template name is taken from the screen name. The default template is: Home. The following screen templates are available:

• Home Displays the output of the portlets on a given page.
• Error Informs the user about general problems, for example, incorrect passwords, an expired session, etc. No portlet output will be displayed.
• Login Collects the login data for a user.
• NewUserForm Collects the data to enroll a new user during self-enrollment.

For other screen templates, go to the ..\screens\html directory.

The search path of the screen template JSP is composed of these parts:

• Markup (HTML, WML, cHTML, etc.)
• Language (en_US, en, de_DE, etc.)
• Markup Version (ie5, Ns, ppcie, etc.)
• Template name (Home, Error, Login, NewUserForm, etc.)

The following are examples of screen template JSPs:

 \screens\html\en_US\Home.jsp
\screens\html\ie5/Home.jsp
\screens\html\Home.jsp              

Component templates: The component template is responsible for rendering the component itself, and for starting the rendering of its children. The children of container components (row and column) may be other containers or controls. The child of a control will always be a single portlet. Modify the search path for the window templates by how you set the Skin. There is no default template defined. All components must have an existing template. The following component templates are available:

• RowContainer Renders a row container and starts the rendering of all its children, which are all the defined components that this container holds.
• ColumnContainer Renders a column container and starts the rendering of all its children, which are all the defined components that this container holds.
• Control Renders the title, frame, and control buttons of a portlet. The control template starts the rendering of the portlet with the portletRender tag.

The following diagram illustrates the imbedded nature of the component templates. The controls are children of the Column Containers, and the Column Containers are children of the Row Container.

For the RowContainer and ColumnContainer component templates, the componentRender tag starts the rendering of the children. Enclose the componentRender tag with the componentLoop tag, which repeats its content for each component.

The search path of the component template JSP is composed of these parts:

• Markup (HTML, WML, cHTML, etc.)
• Skin name (Album, Outline, Shadow, etc.)
• Language (en_US, en, de_DE, etc.)
• Markup Version (ie5, Ns, ppcie. etc.)
• Template name (RowContainer, ColumnContainer, or Control)

The following are examples of component template JSPs:

 \skins\html\Outline\ie5\en_US\Control.jsp
\skins\html\Outline\ie5\Control.jsp
\skins\html\Outline\Control.jsp

How page aggregation works

Rendering the Home screen triggers the aggregation of a page that holds several portlets; the pageRender tag in the Home screen starts the rendering process. If no portlet is maximized, then this tag calls the RootContainer, which holds all of the containers and controls for this page, and tells it to invoke the rendering of all of its children. Since the root container is used only as a starting point for the aggregation, it will not render itself and will not be visible on the screen. The child (most likely a container) invokes its template, which is responsible for rendering all of the content of this child. If this child contains further children components, then the componentLoop and the componentRender tags execute the rendering of all these components within this template one after the other. Each component invokes its own template which in turn invokes more components, and so forth. Therefore, control moves between the component classes and their respective JSPs.

Each component writes its own content to the servlet output stream. A control in the hierarchy invokes the rendering of the portlet, which also writes its content to the stream. After having completed the entire rendering process, the output stream will be closed, and the content will be sent back to the requesting client.

Figure 5 illustrates how the aggregation tree works:

Back to top

Supporting pervasive devices

How a portal renders page content, as well as the markup it uses, varies depending on the type of client device making the request. WebSphere Portal supports not only devices that use a desktop browser (with HTML), but it also supports mobile phones with WML and cHTML markups. However, because of the differences in the aggregation support for these devices, you need to take special considerations when working with WML and cHTML.

WML

Figure 6 shows portal output on a WML device. The critical factor of this device is in the limited size of the screen. Also, the aggregation of the page has been modified for WML:

• A large banner would cover the visible area; therefore, only the company name is provided in the portlet title.
• The links on the banner have been moved to the options section. To log in, the user would have to select options, and then click the link to display the login screen.
• The portlets displayed on the page is reduced to a list of links with the portlet title. These links take the user to the content of the portlets, as seen on the right side of Figure 6.

Defining the window template

Since WML does not have detachable windows, you do not need a JSP template for this support. The only available Window template is the default JSP. This JSP has to start with <?xml version="1.0"?>, since this statement must be the first statement in the resulting document. This statement will also generate the WML templates for the login button. The window JSP template has links to commonly used templates, code to render the screen, and then ends with the WML tag. WebSphere Portal does not include themes with its default window.

Defining screen templates

The markup generated by the screen starts and ends with a card tag, which lets the screen set a title for the output. The following screen templates are available for WML:

• Login
• Error
• Home
• Select Page
• Select Page Group

Note: Multiple card decks are not supported with this set of JSPs.

Defining component templates

Since the screen can only be extended in one direction, you can only arrange the portlets in a vertical list. Therefore, the only function of the Container JSP templates is to start the rendering of the children. The control JSP template renders the portlets in the following way:

• If one portlet is maximized, then the title and the content of this portlet is rendered. All other portlets are ignored.
• If no portlet is maximized, then a link is rendered to maximize each portlet.

The following table shows how WebSphere Portal 4.1 supports various methods in WML. Keep these in mind when creating portlets for pervasive devices.

cHTML

The portal generates output for cHTML devices with consideration for their limitations:

• The screen size: Typically, the screen size of a cHTML device is similar to the screen size of a WAP phone.
• Memory usage for cHTML output: The cHTML output should not exceed a 5 KByte limit.

The screen displayed for cHTML devices is composed of three parts:

• The title section at the top
• The navigation section at the bottom
• The content section in the middle

The title section contains the name of the screen, the portlet title, or the name of the selected portlet page. It is dependent on the mode that the portal session encounters:

• If the user has not yet logged into the portal, then the name of the portal is displayed (by default, this is IBM WebSphere Portal).
• When the user has logged into the portal and the home page is displayed, then the title section contains the title of the active portlet if one of the portlets is in the maximized state. If all portlets are in the minimized state, then the title section contains the text Page: followed by the title of the portlet page that is currently selected.
• When the portal displays the Login, Select Page, or an Error screen, the title section contains the name of this screen.

The navigation section contains the links for the following actions:

• Login (the link is visible if the user has not logged in)
• Logout (the link is visible if the user has logged in to the portal)
• Select Page
• Portal Help

To save space on the display, the links are displayed as icons.

Figure 7 shows the cHTML-generated output of an I-Mode phone. The home page of the portal (1) shows the portlets that are available when the user is not yet logged in the portal. The user clicks the login icon to get to the login screen (2), where the user can enter his or her user ID and password. After a successful login, the personalized portal home page (3) is displayed. The title of the selected portlet page is displayed in the title section. The portlet page can be changed by clicking the Page selection icon, which takes the user to the Page Selection screen (4). When a portlet is maximized (5), the title section shows the portlet title, plus the actions that are available for the portlet (minimize, help, edit, or configure).

Defining the Window template

Like WML, cHTML does not support detachable windows, so the only available window template is the default JSP. This template should at least contain the <html> and <body> tags. The <body> section should contain the <wps:screenRender/> tag.

Defining screen templates

Screen templates consist of cHTML fragments, excluding <html> and <body> tags. The following screens are available for cHTML:

• Home
• Select Page
• Login
• Error

Defining component templates

Like with WML, the screen can only extend in one direction, so you can only arrange the portlets in a vertical list. Therefore, the only function of the Container JSPs is to start the rendering of the children. The control JSP renders the portlets in the following way:

• If one portlet is maximized, then the title and the content of the portlet are rendered. All other portlets are ignored.
• If no portlet is maximized, then the portlet page title is rendered, and for each portlet a link is rendered to maximize the portlet.

Back to top

Adding a new device

When enhancing the capabilities of the portal for a new device, you must determine the existing support. There are several possibilities:

• The class of the device is already supported, and the portal already generates output appropriate for the device, but simply the device in question is not supported. In this case, you simply need to add a new device to the list of supported devices. Note that the portal provides a default "catch all" HTML device, which is used if the device is not in the list of supported devices. This may be a good solution for HTML devices, but will cause problems for WML or cHTML devices. Therefore, you will always need to add WML and cHTML devices that are not currently listed.
• Devices using the same markup language (HTML, WML, etc.) are already supported, but the device in question requires a different version of the markup language. In this case, you need to add the device and create a new markup version.
• The markup language of the device in question is not supported at all. In this case, you need to create a new markup and add the device.

Defining the device

To support a new device in WebSphere Portal, use the Client Manager portlet available on the Portal Administration Page Group and add your device to the device list. Make sure to use the correct user agent string, since this is the value the portal uses to match an incoming request to your device.

Creating a new markup version

To create a new markup version, you need to modify the JSPs for the markup. Check all of the template JSPs (Window, Screen, and Component) to see if they are generating markup that is not supported by your client. If so, you need to copy all of the files into the new version-specific subdirectory for this client, and then modify these JSPs to generate only markup supported by your client. Take this same approach if you want to support a higher level of the current markup on the device when the current version of the markup does not satisfy your requirements. In this case, you can enhance the copied files with new markup tags.

The name of the markup version must match the name of the subdirectory created to hold the markup version's modified JSPs. You specify the markup version when you define your device with the Client Manager portlet. An example of creating a new markup version is provided in Creating the pocket client and a new markup version.

Creating a new markup

You define a markup in WebSphere Portal portal using the Manage Markup portlet on the Portal Administration Page Group.

Currently the following markups are defined:

For any new markup, at minimum you need to generate the following templates, and place them in a new subdirectory named according to the markup:

• Default.jsp, as a Window template
• Home.jsp, as a Screen template
• Errorxxx.jsp, as a Screen template
• Login.jsp, as a Screen template
• UserProfileForm.jsp, as a Screen template
• UserProfileConf.jsp, as a Screen template
• ColumnContainer.jsp, as a Component template
• RowContainer.jsp, as a Component template
• Control.jsp, as a Component template

If the device does not support table-oriented placement to render multiple rows and columns, then you need to provide dummy implementations for the row and column JSPs, which simply start the rendering of their children. This is used for WML and cHTML. Therefore, the portlets will be rendered as if they where placed in a one-dimensional column. Also, if you need to support themes and skins, you must create additional subdirectories and templates under the markup subdirectory. See Themes and skins above for this process. Finally, you need to set portlets that support this new markup to generate output for the new markup and define support for this markup in their portlet.xml file. Likewise, you should also set page groups and pages that contain portlets that support the new markup to indicate that they should be rendered on devices using the new markup. You can modify page groups and page properties using the Manage Page Groups and Pages portlet under the Working with Pages page group.

The name of the markup must match the name of the subdirectory that holds the markup's modified JSPs. You need to set devices that use the new markup to specify the new markup using the Client Manager portlet.

Back to top

Adding support for Pocket PC

As more people use portable mobile devices, it becomes more important for Web sites to support these devices. As shown in the preceding sections, WebSphere Portal provides the flexibility to support these portable mobile devices. The following section describes how you can add device support for a Pocket PC device using the Pocket PC Internet Explorer browser.

First, determine the type of device support you need. Since WebSphere Portal supports the Microsoft Internet Explorer desktop browser, you need to find out what features the Pocket PC browser supports. Refer to Pocket PC 2002 and Handheld PC Browser Comparison. This document highlight a major problem with using the Microsoft Internet Explorer device definition for the Pocket PC browser. WebSphere Portal uses cascading stylesheets for formatting the output to a desktop browser. As you can see, the Pocket PC browser does not support cascading stylesheets. Consequently, the output from the Microsoft Internet Explorer device will not be formatted correctly on a Pocket PC device.

As explained in Adding a new device, you need to decide which situation fits your needs. Because cascading stylesheet is not supported, using an existing device definition will not be suitable. There, you can either create a new markup version or a new markup. There are pros and cons for doing both:

For this example, assume that you want to minimize the amount of changes to the portlets, and that the HTML and Pocket PC versions will be similar. Based on this assumption, you will implement a new markup version.

Creating the pocket client and a new markup version

To create a new markup version called ppcie, and support it, complete the following:

1. Create a new client for a Pocket PC device using the Manage Client portlet. In the WebSphere Portal Portal Settings view, complete the following:
   
   
   1. In the User Agent field, enter .*Windows CE.*.
   2. In the Markup field, select html.
   3. In the Markup Version field, enter ppcie.
   4. In the Manufacturer field, enter Microsoft.
   5. In the Model field, enter Pocket PC IE.
   6. In the Version field, enter 3.x.
   7. In the Position field, select First.
   8. Click OK.
      
      Figure 8 shows the fields that need to be defined for the new client:
      
   
   Figure 8. The Portal Settings tab view
   
   
   Note: The capabilities define certain attributes that the device supports. See the Capability class in the portal API for a list of capabilities that can be added to a client definition. These capabilities can be checked in a JSP by using a client object. Refer to Michael Wanderski's WebSphere Portal Programming: Pervasive Portlet Development for information on using the client object. It is important that you define the correct capabilities so that the correct output is generated for the device. For a Pocket PC, define only these capabilities: HTML_3_2, HTML_3_0, HTML_2_0, HTML_TABLE, HTML_FRAME.
2. Create ppcie subdirectories under the html directory to hold the modified aggregator JSPs. The following directories will be created to hold the modified JSPs:
   
   • ..\screens\html\ppcie\
   • ..\skins\html\skin_name\ppcie\
   • ..\skins\html\theme_name\ppcie\

Handling cascading stylesheets

One main reason for creating a new markup version to support Pocket PC devices is that these devices do not support cascading stylesheets. Therefore, you must copy all JSPs in the html subdirectories that reference cascading stylesheet classes or that use the <style> tag into the corresponding ppcie subdirectory, and modify them. Then, convert the references to stylesheet classes to the equivalent HTML tags. For example, the Control.jsp in ..\skins\html contains references to stylesheet class that need to be changed:

<td class="wpsPortletTitle" width="100%"  
nowrap align="<%= bidiAlignLeft %>" valign="middle">
&nbsp;&nbsp;
<wps:portletTitle>
<wps:problem bundle="nls.problem"/>
</wps:portletTitle>
&nbsp;&nbsp; 
</td>

The stylesheet used for HTML is located in ..\html\Styles.css. In this file, you see that wpsPortletTitle is defined as:

.wpsPortletTitle { background-color: #EBEBEB; color: #666666; 
    font-weight: bold; font-family: sans-serif; font-size: 12pt; }

Therefore, change the same code snippet for the modified Control.jsp in the ppcie subdirectory to:

<td bgcolor="#EBEBEB" width="100%" nowrap align="<%= bidiAlignLeft %>" 
valign="middle">
<font face="sans-serif" size="1" color="#666666"><b>
&nbsp;&nbsp; 
<wps:portletTitle> 
<wps:problem bundle="nls.problem"/> 
</wps:portletTitle>
&nbsp;&nbsp; 
</td>

Repeat the above steps for all references to stylesheet classes in all aggregator JSPs. When you hardcode the HTML tags, you also need to update the Pocket PC colors and fonts each time the stylesheet is updated in order to keep the desktop and Pocket PC colors and fonts similar. This might become difficult if you do not remember where a particular class was used. Taking a dynamic approach, you could create a bean to read the class definition from the stylesheet and then convert it to the proper HTML tags. Consequently, when the stylesheet is updated, it will be automatically picked up by the ppcie JSPs that use the bean. You will need to do this for any output generated by the portlets for a Pocket PC device. For a more detailed description of this approach, read WebSphere Portal Programming: Pervasive Portlet Development.

Handling other formatting issues

One other issue emerges from the limited screen size of a Pocket PC device. For desktop HTML browsers, you can define multiple column containers on one page so that portlets are displayed in multiple columns. This can result in usability concerns on the Pocket PC device because multiple columns will require the user to scroll extensively horizontally. Because of the limited screen size, it makes more sense to display output vertically and avoid horizontal scrolling if at all possible. Therefore, for Pocket PC devices, always display portlets in a single column. This is similar to how portlets are handled for WML and cHTML devices. Since this behavior is controlled by ColumnContainer.jsp and RowContainer.jsp, copy these two JSP files from the ..\skins\wml subdirectory instead of the ..\skins\html subdirectory. These two JSPs will simply render all of its children without creating multi-column tables so that you can use them without any changes. You still want the portlet contents to be rendered on the page, so copy Control.jsp from the ..\skins\html directory before modifying it.

Back to top

Conclusion

WebSphere Portal can support a variety of different types of devices. This makes it well-suited to support the many different pervasive devices in the market today. Many of these devices, such as WML, I-Mode, HTML, are already supported by the standard portal installation, and others, such as, Voice and Pocket PC, can be supported through special extensions. As new pervasive devices are made available, you can use WebSphere Portal to develop new device support or customize existing ones to handle special needs for these devices.

Resources

• WebSphere Portal Information Center. Information on portal modifications and portal API, including aggregation tags.
  
  
• WebSphere Everyplace Access Information Center. Information on pervasive device viewing enhancements for WebSphere Portal.
  
  
• Microsoft Pocket PC Information
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Page aggregation
• Supporting pervasive devices
• Adding a new device
• Adding support for Pocket PC
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers