WebSphere Portal 6.1.5 Themes 101

Len Barker
Len Barker

by Len Barker, Managing Partner – Lotus Practice

Just when you thought you had WebSphere Portal themes figured out along came WebSphere Portal 6.1.5 and 7.0.  The addition of the PortalWeb2 theme in Portal 6.1.5 ushered in an era of client side aggregation into themes and hence new tools for designing themes.  Portal 7 introduces WebDav access to theme elements and yet another way to manipulate themes.  IBM’s documentation will tell you that these changes give the developer unprecedented control over themes.  This is true, but not until you understand what is going on.

Let’s start with a quick review of theme design in WebSphere Portal 6.0.x

In this version of Portal, the theme elements are all rendered by the server.  Since there is one location responsible for rendering all theme components it is reasonably easy to figure out what is going on.  IBM’s themes are located in [wp_profile root]\installedApps\wps.ear\wps.war\themes\.  Each theme contains Default.jsp which is where all of the action begins.  Becoming familiar with Default.jsp is critical to theme development in any Portal version.  The IBM White Paper entitled “Developing Themes and Skins in WebSphere Portal 6.0.x” is required reading if you are new to theme development.

Web 2.0 themes were introduced in Portal 6.1.5 as a way of giving the developer access to the dojo toolkit for rendering the dynamic portions of the theme. In other words, some parts of the theme are static (e.g. the banner graphics, background colors, etc) and others change often (e.g. the top and side navigation elements).  Rather than requiring the entire page to refresh when the dynamic elements change, the Web 2.0 theme uses dojo (javascript functions) on the client (client side aggregation) to refresh only the portion of the page that needs refreshing.  While that is a great experience for the end user it introduces more moving parts for the developer.  I found a good article on the Web 2.0 theme that illustrates which portions of the theme are now aggregated on the client side and which are still rendered by the server. 

For the pieces that are rendered by the client this is a quick summary of how it works:

  1. Default.jsp loads
  2. There are several placeholders in Default.jsp that will replaced by the client side code (e.g. <c:if test=”${!renderPlaceholdersOnly}”>)
  3. Default.jsp calls head_extras.jspf which initializes the client side dojo libraries through its’ bootstrap function
  4. The dojo libraries (located in the dojo_resources.ear) do all of the necessary logic and create an xml ouput of what needs to be displayed.  For more on the two version of dojo included in Portal 6.1.5 and 7 read the info center chapter on the subject.
  5. The xml is rendered as html using xsl stylesheets (located in the xsl directory under your themes root directory)

If you ever find some need to change the javascript functions (located under Dojo_Resources.ear\dojo.war\com\ibm) that do the client side rendering be aware that the individual javascript files that are listed in the directory structure are there for documentation only.  Your code changes would have to be made to ibmCSA.js.uncompressed (located under Dojo_Resources.ear\dojo.war\com) and then use a javascript compression tool to compress that file into ibmCSA.js.  After you do that you will have to stop and start the Dojo_Resources.ear from Portal’s application server console.

Hopefully this overview will jumpstart your understanding of how themes work in Portal 6.1.5.  I will save the Portal 7 discussion for another day.

8 comments on “WebSphere Portal 6.1.5 Themes 101

  1. hi, how would you deploy a new theme war file for websphere portal 7. currently i am able to create a new theme using webdav. but the theme_en.html is referencing to the pagebuilder2 war file in “C:\IBM\WebSphere7\PortalServer\theme\wp.mashup.cc.theme\installedApps\wp.mashup.cc.theme.ear\PageBuilder2.war”
    i would like to create my own theme war file and i do not wish to touch the existing jsp file.

    please advise.

  2. Hi Davalenllc,
    thank you for the reply. but after i deploy my war file, inside the theme_en.html, i am still unable to link to the new jsp in the WAR file that i have just deployed.
    the new WAR file context root is “/testtheme”
    i tried to link up using the dynamic content “
    i got the file not found error.

    • You need to make sure that you are putting your content in a location that is registered with the server or else you need to register a new location. At run time a server-side theme parser identifies and resolves dynamic content spots, and streams their output into the final response to the browser.
      A dynamic content spot has the following format:
      where: rel=”dynamic-content”
      The theme template parser recognizes the element rel=”dynamic-content”. It resolves the href attribute and inserts its output into the response. href is any URI that is resolved by the resource addressability framework.

      Dynamic Content Spot mappings are defined in WebSphere Application Server under Resource Environment providers →
      WP_DynamicContentSpotMappings → Custom Properties.

  3. I have created a new war with my jsp’s and I would like to not modify PageBuilder2 so in dojo_resources.ear there is a v1.4.3/com/ibm/themes/PageBuilder2 folder. Do I make a copy of this and rename it to my theme name? Also there are some references to PageBuilder2 in the theme.js.uncompressed.js, do I change this to my new theme folder name? Also are there any other files I need to change in Dojo_resources to reflect the new themes folder I created? Also can you explain in more detail the compressing of the js file. All I have done is imported the ear from WebSphere into RAD and am editing the files this way and then reimporting the changes back into WebSphere.

  4. Hello there I am so thrilled I found your website, I really found you by mistake, while I was looking on Google for something else, Anyways I am here now and would just like to say cheers for a tremendous post and a all round enjoyable blog (I also love the theme/design), I don’t have time to read it all at the minute but I have book-marked it and also added in your RSS feeds, so when I have time I will be back to read a lot more, Please do keep up the awesome job.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s