Introduction

This is the first article in a series that covers developing with IBM WebSphere Portal Server. First, the series will demonstrate how WebSphere Portal Server 2.1 can be extended to provide dynamic theme selection. Second, the series will demonstrate how IBM WebSphere Studio Application Developer can be used to jump start all WebSphere Portal Server development activities.

Part 1 of this series introduces how dynamic theme customization for Portal Server can be achieved. Part 2 will explore in greater detail Portal Server project development using Application Developer. Step-by-step instructions will be provided on how to create a Portal Server project in Application Developer. Part 3 will explore how Application Developer can be set up to debug and troubleshoot Portal Server applications.

This article assumes that you have WebSphere Portal Server 2.1 and WebSphere Application Server 3.5.4 installed. You should also be familiar with Portal Server and Application Server administration. To view the source code of the project that is provided with this article, you must have WebSphere Studio Application Developer 4.0 installed.

WebSphere Portal Server

WebSphere Portal Server 2.1 is a product that enables the hosting of aggregated information and collaborative applications on IBM WebSphere Application Server 3.5.4. Portal Server provides site users with a single point of access to multiple types of information and applications through the concept of portlets. Portlets are visual windows that organize content from different sources into a single interface for individual or group access. Most of the underlying technologies employed by Portal Server are standards based on the J2EE specifications. Portlets provide both visual and programmatic means of delivering information to the users. Hence, an enterprise portal site can be built quickly by integrating a collection of portlets, which integrates with the infrastructure services provided by the Portal Server framework. Most of the services provided can be customized further with some programming. As WebSphere Portal Server gains in popularity, there is a growing interest in the development community to learn more about the tools available to expedite development, and gain insights on how to perform customization.

WebSphere Studio Application Developer

WebSphere Studio Application Developer provides an extensible integrated development environment for Java^TM-based software development. Application Developer comes with a plethora of plugins that enhance the development cycle of projects - projects that span a wide magnitude of complexity. The features and functions built into Application Developer make it ideal for developing WebSphere Portal Server projects.

If VisualAge for Java is the developer's development platform of choice, then the supported development and debugging environment for WebSphere Portal Server is the WebSphere Portal Server Testing Environment. At the time of this writing, Application Developer comes with built-in development support for WebSphere Application Server 4.0 and Tomcat. Since Portal Server sits on WebSphere Application Server 3.5, there are no direct references to how Portal Server development can be performed using Application Developer. As a result, the "how-to" of creating and managing Portal Server projects using Application Developer became a popular question among Portal Server developers. For more information about the WebSphere Portal Server Testing Environment, go to the WebSphere Portal Server Support page.

Back to top

Themes and Skins

WebSphere Portal Server provides an easy way of customizing the look and feel of a portal site. The customization feature is made available through the concept of Themes and Skins. A Portal site administrator or developer can decide on the look and feel of the site by creating the necessary bitmaps and JSP^TM files for the Themes and Skins. WebSphere Portal Server ships five different Themes and four types of Skins. The Themes that are available for use are:

• DefaultTheme
• GreyTheme
• KhakiTheme
• LilacTheme
• TealTheme

The available Skins for use are:

• Album
• Hint
• Outline
• Shadow

Themes determine the banner image, tab images, icon, and color scheme (implemented using Cascade Style Sheets) of the Portal site, while Skins dictate the look and feel of each portlet on every page. A thorough description of the location of files related to the Themes and Skins is provided in the Portal Modification section of the WebSphere Portal Server InfoCenter. The InfoCenter also provides a good description of how different bitmaps schemes can be applied, along with the size and dimensions required for these bitmaps. Table 1 below is adapted from the InfoCenter for illustration purposes.

Table 1. Bitmaps related to the Default Theme profile

Resource type	Image sample	Remarks
Banner		Appears in the upper left background of the banner
Navigational Icons	nav_customize.gif	Links to the page to customize the portal
Navigational Icons	nav_create_account.gif	Links to page for self enrollment
Navigational Icons	nav_forgot_password.gif	Links to page to help users request credentials from the site administrator
Navigational Icons	nav_help.gif	Links to portal help page
Navigational Icons	nav_login.gif	Links to login page
Navigational Icons	nav_logoff.gif	Links to logoff page
Navigational Icons	nav_profile.gif	Links to page for updating account information
Tab Corners	tab_left.gif	Appears on the left edge of the tab
Tab Corners	tab_right.gif	Appears on the right edge of the tab
Portlet Title Bar	title_back.gif	Returns the portlet from help mode to view mode
Portlet Title Bar	title_help.gif	Opens the portlet help mode
Portlet Title Bar	title_edit.gif	Opens the portlet edit mode
Portlet Title Bar	title_maximize.gif	Opens the portlet to a maximized view
Portlet Title Bar	title_minimize.gif	Renders the portlet to a title bar
Portlet Title Bar	title_restore.gif	Restores the portlet from maximized or minimized state

The selection of different themes can be activated by modifying the theme.default field of the TurbineResources.Properties file. The location of this properties file can be found in the <WPS_Install_Root>\app\web\WEB-INF\conf folder.

When WebSphere Portal Server starts up, this file is read and parsed, and the specified value of the theme.default field remains in effect for as long as the Portal session is available.

In addition, the theme.default field does not permit any form of key-value mapping, which results in a single theme value being used by all Portal Server user sessions.

# ...Some code truncated above... 
#
# This is the default theme to apply to the L&F
#
# Default: DefaultTheme

theme.default=DefaultTheme

# ...Some code truncated below...

This default behavior -- that is, the single theme value being used by all Portal Server user sessions -- becomes a limitation when there is a need to provide finer granularity to customize the user interface of Portal Server. Often, the granularity that is required is a factor of the following environment parameters:

• User session (for example, login user id)
• Location (for example, where the user browsed from, or the user's IP address)
• Time (for example, is it a school holiday season)

Back to top

Dynamic theme selection

When a WebSphere Portal Server site needs to adapt the look and feel based on some environment parameter, then the parameter has to be retrievable during run time, possibly when a user request to the Portal Server is made. An example scenario could be when there is a need for different sets of color and bitmaps to be used for different users or different groups of users. It is very common for a portal site to provide UI personalization based on user preferences. Sometimes, the selection logic is programmed based on corporate policies, but more frequently, the preference is specified by the user. Depending on the operational requirements of the Theme selection, the logic required for implementing dynamic theme selection may vary slightly.

Currently, WebSphere Portal Server does not support dynamic theme selection because there is only a single theme.default field defined for all users in the TurbineResources.Properties file. Fortunately, with some simple programming, WebSphere Portal Server can be extended to handle dynamic theme selection. The steps required for implementing the changes are as follows:

1. Determine how and when the environment parameter can be retrieved. See the implementation of getEnvironParam() in MyThemeTag.java in the download file (more details provided below).
2. Derive the Theme value by using the environment parameter as a key to a hash. See the implementation of getTheme() in MyThemeTag.java in the download file (more details provided below).
3. Serve out the Theme value. See the implementation of doStartTag() in MyThemeTag.java in the download file (more details provided below).

I will expand on steps 1 and 3 above by providing functional skeletal code to illustrate the concepts. As for step 2, deriving the Theme value from the environment parameter is usually specific to an individual portal site. Often, this can be implemented by using a simple lookup table or reading values from a database table. For now, we will demonstrate by using a hash table that gets initialized into the memory whenever WebSphere Portal Server starts up.

The next section will describe how to extend Portal Server to provide UI customization, allowing the use of external environment parameters to influence the selection of themes.

Back to top

<wps:theme> demystified

As mentioned in the previous section, every Theme defined in WebSphere Portal Server consists of a set of user interface entities or resources. The Portal Server developer has the flexibility to customize resources such as images, banners, and various style sheets (.css files). These style sheets contain the color and font type scheme of the Theme. When the Portal Server kernel generates the HTML code from the JSP files, references to these .css files are inserted so that the user's browser will look up these style sheets for page customization from the browser side.

Portal Server employs the concept of JSP tags to perform the task of dynamic field substitution. Essentially, JSP tags have two components: a tag handler implemented using Java code and an XML tag element. Whenever the tag element is encountered in a JSP file, the relevant tag handler Java code will be executed. The Java execution code can also influence how the tag will be rendered on the actual markup generation.

WebSphere Portal Server allows developers to implement and provide a user-defined customized tag library. These user-defined tags can be used to further enhance the portlet page rendering process. Besides the developer's customized tag library, Portal Server implements a set of tag library functions for use by the Portal Server engine. This is referred to as the Engine Tag Library or Engine.tld. The location of the file can be found in the <WPS_Install_Root>\app\web\WEB-INF\tld folder. A detailed description of what each of the engine tags does can be found in the Changing the Portal layout section of the WebSphere Portal Server InfoCenter.

Taking a closer look at the Engine.tld file will reveal how the tag commands of the tag library are registered and declared.

...Some code truncated above...

<tag>
   <name>url</name>
   <tagclass>com.ibm.wps.engine.tags.UrlTag</tagclass>
   <bodycontent>empty</bodycontent>
   <attribute>
      <name>type</name>
      <required>true</required>
   </attribute>
</tag>

...Some code truncated below...

Declare an engine tag by enclosing it with the <tag> element. The <name> element defines the tag element name to be used from within the JSP file. The implementation portion of the tag element is identified by the <tagclass> element. The <attribute> tags can enclose further parameters required by the implementation class of the JSP tags.

...Some code truncated above...

<tag>
   <name>theme</name>
   <tagclass>com.ibm.wps.engine.tags.ThemeTag</tagclass>
   <bodycontent>empty</bodycontent>
</tag>

...Some code truncated below...

The Theme tag defined by WebSphere Portal Server does not take in any parameters and the implementation of the Theme tag handler returns the name of the Theme. The value returned will translate into the actual files exported by Portal Server into its Web folder. An example use of the <wps:theme> tag in the Banner.jsp is:

// ...Some code truncated above...

<TD class="wpsPortalBanner" valign="middle" align=left width="499" height=43
   background='<wps:url type="base"/>images/themes/<wps:theme/>/banner.jpg'>

// ...Some code truncated below...

When Banner.jsp gets compiled and served back to the user's browser, the following HTML code will be generated:

// ...Some code truncated above...

<TD class="wpsPortalBanner" valign="middle" align=left width="499" height=43
   background='http://babylon5.sg.ibm.com/wps/
   portal/images/themes/TealTheme/banner.jpg'>

// ...Some code truncated below...

Depending on where and how the WebSphere Portal Server server is installed, the JSP tag engine will substitute the <wps:url> tag command with the relevant URL path. The <wps:theme> tag is substituted with the value TealTheme as specified by the theme.default field of the TurbineResources.Properties file.

Back to top

Making the changes

To implement dynamic theme selection, two changes to the Portal Server system are required:

• Modify Engine.tld to reflect the new Java code to handle Theme selection.
• Implement a new ThemeTag class that performs dynamic theme selection and loads it into the Portal Server instance.

We could actually implement a new tag (for example, <mywps:dyna_theme>) and avoid modifying the Engine.tld file. The downside of this approach is that you would have to add this newly introduced tag in all JSP files that involve Theme rendering that are used by Portal Server.

Let's take the more practical approach of overriding the original behavior of the ThemeTag supplied by Portal Server.

Engine.tld

You need to make the following changes to the Engine.tld file.

<tag>
   <name>theme</name>
   <tagclass>com.ibm.etc.wps.tags.MyThemeTag</tagclass>
   <bodycontent>empty</bodycontent>
</tag>

Notice the substitution of the Java class in <tagclass> with our own com.ibm.etc.wps.tags.MyThemeTag. This has the effect of requesting the Portal Server's JSP processor to execute our version of the Theme tag handler.

MyThemeTag.java

The MyThemeTag.java class implements the dynamic selection logic and extends from the original ThemeTag class of the com.ibm.wps.engine.tags package. When a tag handler code is invoked by the JSP processor, the doStartTag() method will be called first. In return, the environment parameter is obtained via the getEnvironParam() method. If you have a different environment parameter to hook into, then this is where you should insert the changes. Otherwise, the code can stay and it retrieves the user's login ID derived from the RunData object. Using the environment parameter as a key, the getTheme() method is called to obtain a preferred Theme value. Our implementation is to match against a hash table of user ID with the Theme value. In your actual implementation, this field can be stored as part of the relational database table used by Portal Server for the user's preferences or it can be derived from some kind of logic. A more elaborate implementation could be to retrieve the Theme value from a hash table that takes in the user ID, IP address, and Date/Time group. This form of customization provides finer granularity in UI customization to the Portal users.

See the download file below for the implementation of MyThemeTag.java.

Back to top

Running the changes

In the download ZIP file below, you will find a pre-built version of the project mytheme.jar, a modified engine.tld file, and all of source code shown in this article. This project is created with all of the necessary JAR files embedded in. So you should not experience any problems with missing JAR files when trying to recompile using Application Developer. I will cover Portal Server project development in greater detail in Part 2 of this series.

If you are familiar with using Application Developer, then go ahead and import the project into the workspace environment and start building the code. Otherwise, simply copy the mytheme.jar file into the <WPS_Install_Root>\app\web\WEB-INF\lib directory and copy the engine.tld file into the <WPS_Install_Root>\app\web\WEB-INF\tld directory. Backup the original engine.tld file if you wish to.

Next, start your WebSphere Application Server administrative console and add the mytheme.jar path to the classpath of the Portal Server Web Application. This will ensure that the JSP processor of Portal Server is able to locate the new Theme tag handler. Finally, remove any copies of cached portal pages that are stored in the <WAS_Install_Root>\temp\default_host directory. You can safely remove all files that are found under this folder because they are usually generated and cached for performance reasons.

Once all of these changes are done, restart the WebSphere Portal Server Application Server from the WebSphere Application Server administrative console and check out the changes!

Both Figures 1 and 6 above show the default WebSphere Portal Server home page when no user has yet logged in to Portal Server. Notice the difference in their color schemes. In Figure 6, the dynamic theme selection kicked in and chose the GreyTheme for "guest" or pages with no user ID. Similarly, in Figure 7, the logged in user "wpsadmin" receives a different Theme, TealTheme (compare this to the default implementation shown in Figure 2). This switching between different sets of Themes happened dynamically based on the implementation of the MyThemeTag::doStartTag() method. Remember that no changes are made to the TurbineResources.Properties file and that the WebSphere Portal Server Application Server was not restarted.

Back to top

Summary

The article and code demonstrate the possibilities of extending WebSphere Portal Server by overriding the default behavior of the Portal Server classes. Using the same principle of overriding the default implementation of the Tag handler, there are many different customizations that can be added to Portal Server for a highly personalized portal site. An example would be overriding the <wps:page> Tag handler and providing value-add services (such as internationalization) to the names of each page.

You can also further extend the example code shown in this article to provide a Customizer page for soliciting Theme selection (or other kinds of UI preferences) from the user and persisting the value to some storage, such as databases.

The original implementation of this technique was developed on the Portal Server 1.2 code base and has been ported to Portal Server 2.1 for the purpose of writing this article. There are some small differences in the way Tag engine classes work between Portal Server 1.2 and 2.1. For the code designed for use in Portal Server 1.2, contact the author.

Back to top

Download

Name	Size	Download method
part1_source.zip	796 KB	FTP|HTTP

Information about download methods

Resources

• Portlets Definition
  
  
• WebSphere Portal Server InfoCenter
  
  
• WebSphere Portal Server Portlets Catalog
  
  
• Introduction to Portlets API
  
  
• Advanced Introduction to Portlets API
  
  
• WebSphere Portal Server Development Using WebSphere Studio Application Developer -- Part 2: Developing a Portal Server project
  
  
• WebSphere Portal Server Development Using WebSphere Studio Application Developer -- Part 3: Applying the Portal Server Project Template
  
  

About the author

Alvin Khor is a Staff Software Engineer at the IBM Emerging Technology Center in Singapore, where he serves as a technical team lead for application development in the Pervasive Computing field. Before joining IBM, he worked in various areas of technology, including data warehouse, speech processing, and multimedia. With IBM, Alvin has worked in areas including transcoding, WAP, portal and personalization, and broadband networking, and is starting to explore voice-enabled applications. Besides development activities, Alvin also participates in conducting training on PVC topics in various parts of Asia. Alvin received his Honors degree in Computer Science in 1993 from Essex University in the United Kingdom. You can contact Alvin at khorewa@sg.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Themes and Skins
• Dynamic theme selection
• <wps:theme> demystified
• Making the changes
• Running the changes
• Summary
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers