Related Topics: IBM Cloud

IBM Cloud: Article

Skin Deep

Skin Deep

The look and feel of a WebSphere Portal site is determined by the definition of themes and skins. This might give you the impression that themes and skins are mere window dressing and hence the domain of interaction designers and graphic designers. The WebSphere Portal page renderer, however, constructs its portal pages on the logic defined in the JavaServer Pages (JSPs) of the themes and skins. This means that themes and skins are capable of more function than just determining the look and feel of a portal page through cascading style sheets and images. WebSphere Portal developers can utilize the themes and (in particular the) skins to implement functionality that will influence the behavior of the portlet container (window and title bar) without modifying the portlets involved.

Themes and Skins
The visual appearance and the navigational structures of all the portal pages within a "Place" are determined by a theme. Themes determine the overall look and feel of the portal, including colors, images, and fonts, which will ensure consistency and provide company-specific branding. A theme supports multiple skins. A skin defines the look and feel of the window around the individual portlets (see Figure 1). Each portlet on a page can have its own skin, configured by the Portal administrator.


The themes and skins are the main parts of the Portal page construction process. They can be found in the directory WebSphere/PortalServer/app/wps.ear/wps.war and the more specific subdirectories. During the construction of the page, the portal server searches for theme and skin components, starting with the most specific subdirectory (country, locale, and client) and moving up to the more general, higher-level directories.

For example, when a user requests a page from a client using Internet Explorer version 5 with the locale set to en_US and the users' skins set to Shadow, WebSphere Portal will search for the skin resource file Control.jsp in the following order:
1.  /skins/html/Shadow/ie5/en_US/ Control.jsp
2.  /skins/html/Shadow/ie5/en/ Control.jsp
3.  /skins/html/Shadow/ie5/Control. jsp
4.  /skins/html/Shadow/en_US/ Control.jsp
5.  /skins/html/Shadow/en/Control. jsp
6.  /skins/html/Shadow/Control.jsp
7.  /skins/html/ie5/en_US/Control.jsp
8.  /skins/html/ie5/en/Control.jsp
9.  /skins/html/ie5/Control.jsp
10.  /skins/html/en_US/Control.jsp
11.  /skins/html/en/Control.jsp
12.  /skins/html/Control.jsp
13.  /skins/Control.jsp

Portal Page Construction
Figure 2 depicts the internal flow of the Portal page construction. Every page within WebSphere Portal is built according to this JSP scheme, except for some specific screens such as the registration, login, and error pages.


The starting point of the Portal page construction process is Default.jsp in the Themes directory. This page includes the other JSPs of the theme. Together these theme JSPs compose the header and navigation (places and pages) parts of nearly every WebSphere Portal page. Modifications to the Portal header, toolbar, place bar, or page bar are made within the corresponding JSP file. At the bottom the Default.jsp holds the <wps:screen Render> tag, which will include the Home.jsp of the Screen directory. The Home.jsp represents the content of a Portal page and triggers the composition render process of the skin-related JSPs.

The portlet render process is executed in the Control.jsp page of the skin. This means that every portlet is rendered according to the Control.jsp defined by the portlet skin for each page request. Interaction designers and graphic designers modify the images and cascading style sheets that are used by the Control.jsp to determine how a portlet (window) looks. The Control.jsp itself is less frequently altered, because it defines the title bar icon placement (title, minimize, maximize, etc.) of the portlet window (see Figure 3). The <wps:portletRender> tag will be replaced by the actual content of the corresponding portlet.


WebSphere Portal provides a tag library (enige.tld) that is used in the JSPs of the themes and skins to provide the construction and decision logic. These tags can somehow determine which portlet is to be rendered. Consequently, the portlet is accessible from within the Control.jsp before it is rendered. This means that it is possible to create skin-based portlet window behavior without modifying portlet code. Since many portlets are provided by third parties (www.ibm.com/websphere/portal/portlet/catalog), no source code is available. Being able to change the behavior of portlets by selecting a custom skin (Control.jsp) offers a few interesting opportunities. The following example shows the type of solutions that can be built with skin-based portlet functionality, and how to create them with WebSphere Studio and the Portal Toolkit plug-in. The source code (included in the WAR files) can be downloaded from websphere/sourcec.cfm. The example code was tested on WebSphere Portal 4.1 and 4.2.

Personalization and Authorization
One of the core features of WebSphere Portal is the configuration (Configure mode) and personalization (Edit mode) of portlets. The portlet developer determines what is to be configured by the Portal administrators and what is to be personalized by a portlet user. Extending the configuration or personalization of portlets requires extra development per portlet and of course the source code must be available. The latter is often a problem for third-party portlets, not to mention decompilers.

Other related Portal features are access control (security/authorization) and custom pages. The Portal administrator determines which Places, Pages, and Portlets are accessible by which users and groups. When given the proper permissions, a user can edit his or her personal pages, determining which portlets should be on the page and their placement.

Now suppose that an extra feature is needed, functionality that provides conditional rendering (i.e., showing or hiding a portlet) based on a user profile setting. Personalization is not the solution because it controls the behavior of the portlets' content and not the window. Once the doView() method is invoked it is too late to hide a portlet, because parts of the portlet window (the title bar and border) are already created by the Control. jsp; however, skipping the doView() would render an empty portlet window. Neither is access control applicable. The authorization mechanism of WebSphere Portal is not advanced enough to handle conditional authorization based on user settings.

Conditional Rendering
If a Portal requires conditional portlet rendering, the best place to intervene is where the portlet window and content are (about to be) rendered. Hence, the Control.jsp of the selected skin is the best place to handle this kind of requirement because it contains the portlet window (title bar and border) and the <wps:portletRender> tag. This solution involves no modification of the portlet itself. The Portal administrator can just add an extra parameter to the portlet settings of all portlets that require custom rendering. The Control.jsp can access the parameters before portlet rendering and provide the required behavior. Because portlet parameters can be added, modified, and deleted at runtime by the Portal administrator, it is the ideal way to trigger specific skin functions.

Making rendering dependent on a user profile means that a personalized profile setting is exploited. In this example, the preferred language setting of the user is utilized. Of course, any other user profile setting - including a custom setting - is viable. The preferred language was chosen for reasons of simplicity (it is the default for WebSphere Portal installation). Now the modified Control.jsp compares the user profile setting with the portlet parameter and renders it when there is a match (see Figure 4).


The user information is available in the Control.jsp by invoking the getUser() method on the RunData object. RunData is an interface to run-time information that is passed within WebSphere Portal (actually it is JetSpeed, or more accurately, Turbine). The com.ibm.wps.engine. RunData can be retrieved from the request object. Acquiring portlet parameters in the Control.jsp is more complex. First, the PortletDescriptorID that identifies the portlet to be rendered is retrieved from the PortletHolder. The PortletHolder is available in the RunData through an attribute (name differs per WebSphere Portal version). Finally, with the PortletDescriptorID the ConcretePortletEntry, which holds the portlet parameters (as a map), can be found in the PortletRegistryAccess.

For technical details, refer to the Control.jsp of the source code zip file. Be careful to check the WebSphere Portal version, because there are differences between the Control.jsp (Portlet API) of WPS 4.1 and WPS 4.2. These differences are clearly marked by comments within the Control.jsp source files.

PortletSession vs HttpSession
In this example the conditional rendering can be activated or deactivated with an additional Control portlet that is available in the WAR file. This Control portlet also demonstrates how to communicate between a portlet and the Control.jsp using session variables. This might seem trivial, but there is a catch. A portlet can retrieve the session by calling getPortletSession() from the request object. However, this PortletSession is confined to a subset of the HttpSession used by this portlet. It is hard to retrieve (Portlet) session variables in a JSP page because the variable names are prefixed with a portlet ID. Here is a trick to circumvent this problem: cast the PortletSession to a PortletSessionImpl and use the getServletSession() method of this class to obtain the complete HttpSession. Be aware that this is outside the published Portlet API.

Closing Portlets
Although available in the (JetSpeed) Portlet API and a valid value according to the DTD, the portlet Close function is not supported by WebSphere Portal. Control.jsp, in conjunction with the Control portlet, can offer this close functionality. The Portal administrator again needs to add an extra parameter (enableClose) to all portlets that require closing. The Control.jsp can now display the Close icon in the title bar of the portlets with this parameter set to "yes". When a user clicks the Close icon, an action event is sent to the Control portlet, which sets a session variable to indicate that the corresponding portlet must be closed. Closed means that the Control.jsp does not render the portlet (and the window), which also implies that the portlet content is not aggregated (see Figure 5).


The Control portlet has an extra function that can restore all closed portlets to normal again (see Figure 6). For technical details, refer to the Control.jsp and SkinDeepControl. java of the source code WAR file.


Using the skin's Control.jsp to provide specific user interaction functionality with respect to portlet rendering is a solution that will work for all portlets, without any modification to the portlets involved. Although this is a big advantage, there are limits to the applicability of a pure Control.jsp solution. Sometimes a combination of special portlets (Control portlet) and a custom Control.jsp is necessary to solve specific problems.

There are also certain drawbacks attached to the advanced Control.jsp modifications described here, the most important one being the Portlet API differences between the versions of WebSphere Portal (4.1, 4.2, and future versions). Another shortcoming is that the Java code in the Control.jsp can be visible to graphic designers and may make them uncomfortable while modifying the look and feel of the portlet window. It is also error prone because of the imports in the page directive. Nine out of ten times when there is an internal translation/compilation problem with the Control.jsp the problem is a missing import. The solution to all these problems is to use custom tags that implement the Java part of the Control.jsp. With custom tags only the tag library needs to be modified in case of a Portlet API revision, the HTML tags are not cluttered by Java code, and there are no imports, except for the inclusion of the tag library.

The example presented here shows a few possible functions that can be implemented with a custom skin (Control.jsp). Of course there are many more applications in which the use of a custom skin, possibly in combination with special portlets, can be a (partial) solution. Customizing the skin might be a good answer, especially when specific portlet window user interaction or particular portlet rendering is required.


  • IBM WebSphere Portal V4.1 Handbook Volume 2, IBM Redbook, SG24-6920-00: http://publib-b.boulder.ibm.com/ Redbooks.nsf/CDAbstracts/sk3t8282.html
  • Developing and Debugging Portlets Using the IBM Portal Toolkit Plug-in for WebSphere Studio Application Developer: www7b.software.ibm.com/wsdd/library/techarticles/0210_phillips/phillips.html
  • Creating a Distinctive Look and Feel for Your Portal: www7b.software.ibm.com/wsdd/library/techarticles/0307_bartek/bartek.html
  • More Stories By Marcel Heijmans

    Marcel Heijmans is a senior software engineer and founder of Mnemonics. He created the J2EE Development Coaching concept, which trains and supports novice developers and architects within their projects while minimizing the project risks.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.

    Latest Stories
    Internet of @ThingsExpo, taking place October 31 - November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 21st Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The Internet of Things (IoT) is the most profound change in personal and enterprise IT since the creation of the Worldwide Web more than 20 years ago. All major researchers estimate there will be tens of billions devic...
    "The Striim platform is a full end-to-end streaming integration and analytics platform that is middleware that covers a lot of different use cases," explained Steve Wilkes, Founder and CTO at Striim, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
    Everything run by electricity will eventually be connected to the Internet. Get ahead of the Internet of Things revolution and join Akvelon expert and IoT industry leader, Sergey Grebnov, in his session at @ThingsExpo, for an educational dive into the world of managing your home, workplace and all the devices they contain with the power of machine-based AI and intelligent Bot services for a completely streamlined experience.
    SYS-CON Events announced today that Calligo, an innovative cloud service provider offering mid-sized companies the highest levels of data privacy and security, has been named "Bronze Sponsor" of SYS-CON's 21st International Cloud Expo ®, which will take place on Oct 31 - Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Calligo offers unparalleled application performance guarantees, commercial flexibility and a personalised support service from its globally located cloud plat...
    "At the keynote this morning we spoke about the value proposition of Nutanix, of having a DevOps culture and a mindset, and the business outcomes of achieving agility and scale, which everybody here is trying to accomplish," noted Mark Lavi, DevOps Solution Architect at Nutanix, in this SYS-CON.tv interview at @DevOpsSummit at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
    DX World EXPO, LLC., a Lighthouse Point, Florida-based startup trade show producer and the creator of "DXWorldEXPO® - Digital Transformation Conference & Expo" has announced its executive management team. The team is headed by Levent Selamoglu, who has been named CEO. "Now is the time for a truly global DX event, to bring together the leading minds from the technology world in a conversation about Digital Transformation," he said in making the announcement.
    21st International Cloud Expo, taking place October 31 - November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA, will feature technical sessions from a rock star conference faculty and the leading industry players in the world. Cloud computing is now being embraced by a majority of enterprises of all sizes. Yesterday's debate about public vs. private has transformed into the reality of hybrid cloud: a recent survey shows that 74% of enterprises have a hybrid cloud strategy. Me...
    "With Digital Experience Monitoring what used to be a simple visit to a web page has exploded into app on phones, data from social media feeds, competitive benchmarking - these are all components that are only available because of some type of digital asset," explained Leo Vasiliou, Director of Web Performance Engineering at Catchpoint Systems, in this SYS-CON.tv interview at DevOps Summit at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
    SYS-CON Events announced today that DXWorldExpo has been named “Global Sponsor” of SYS-CON's 21st International Cloud Expo, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Digital Transformation is the key issue driving the global enterprise IT business. Digital Transformation is most prominent among Global 2000 enterprises and government institutions.
    SYS-CON Events announced today that Datera, that offers a radically new data management architecture, has been named "Exhibitor" of SYS-CON's 21st International Cloud Expo ®, which will take place on Oct 31 - Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Datera is transforming the traditional datacenter model through modern cloud simplicity. The technology industry is at another major inflection point. The rise of mobile, the Internet of Things, data storage and Big...
    "Outscale was founded in 2010, is based in France, is a strategic partner to Dassault Systémes and has done quite a bit of work with divisions of Dassault," explained Jackie Funk, Digital Marketing exec at Outscale, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
    "We were founded in 2003 and the way we were founded was about good backup and good disaster recovery for our clients, and for the last 20 years we've been pretty consistent with that," noted Marc Malafronte, Territory Manager at StorageCraft, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
    Kubernetes is an open source system for automating deployment, scaling, and management of containerized applications. Kubernetes was originally built by Google, leveraging years of experience with managing container workloads, and is now a Cloud Native Compute Foundation (CNCF) project. Kubernetes has been widely adopted by the community, supported on all major public and private cloud providers, and is gaining rapid adoption in enterprises. However, Kubernetes may seem intimidating and complex ...
    While the focus and objectives of IoT initiatives are many and diverse, they all share a few common attributes, and one of those is the network. Commonly, that network includes the Internet, over which there isn't any real control for performance and availability. Or is there? The current state of the art for Big Data analytics, as applied to network telemetry, offers new opportunities for improving and assuring operational integrity. In his session at @ThingsExpo, Jim Frey, Vice President of S...
    "DivvyCloud as a company set out to help customers automate solutions to the most common cloud problems," noted Jeremy Snyder, VP of Business Development at DivvyCloud, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.