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
    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.
    "Space Monkey by Vivent Smart Home is a product that is a distributed cloud-based edge storage network. Vivent Smart Home, our parent company, is a smart home provider that places a lot of hard drives across homes in North America," explained JT Olds, Director of Engineering, and Brandon Crowfeather, Product Manager, at Vivint Smart Home, in this SYS-CON.tv interview at @ThingsExpo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    DevOps is under attack because developers don’t want to mess with infrastructure. They will happily own their code into production, but want to use platforms instead of raw automation. That’s changing the landscape that we understand as DevOps with both architecture concepts (CloudNative) and process redefinition (SRE). Rob Hirschfeld’s recent work in Kubernetes operations has led to the conclusion that containers and related platforms have changed the way we should be thinking about DevOps and...
    SYS-CON Events announced today that Conference Guru has been named “Media Sponsor” of the 22nd International Cloud Expo, which will take place on June 5-7, 2018, at the Javits Center in New York, NY. A valuable conference experience generates new contacts, sales leads, potential strategic partners and potential investors; helps gather competitive intelligence and even provides inspiration for new products and services. Conference Guru works with conference organizers to pass great deals to gre...
    The Internet of Things will challenge the status quo of how IT and development organizations operate. Or will it? Certainly the fog layer of IoT requires special insights about data ontology, security and transactional integrity. But the developmental challenges are the same: People, Process and Platform. In his session at @ThingsExpo, Craig Sproule, CEO of Metavine, demonstrated how to move beyond today's coding paradigm and shared the must-have mindsets for removing complexity from the develop...
    In his Opening Keynote at 21st Cloud Expo, John Considine, General Manager of IBM Cloud Infrastructure, led attendees through the exciting evolution of the cloud. He looked at this major disruption from the perspective of technology, business models, and what this means for enterprises of all sizes. John Considine is General Manager of Cloud Infrastructure Services at IBM. In that role he is responsible for leading IBM’s public cloud infrastructure including strategy, development, and offering m...
    Companies are harnessing data in ways we once associated with science fiction. Analysts have access to a plethora of visualization and reporting tools, but considering the vast amount of data businesses collect and limitations of CPUs, end users are forced to design their structures and systems with limitations. Until now. As the cloud toolkit to analyze data has evolved, GPUs have stepped in to massively parallel SQL, visualization and machine learning.
    The next XaaS is CICDaaS. Why? Because CICD saves developers a huge amount of time. CD is an especially great option for projects that require multiple and frequent contributions to be integrated. But… securing CICD best practices is an emerging, essential, yet little understood practice for DevOps teams and their Cloud Service Providers. The only way to get CICD to work in a highly secure environment takes collaboration, patience and persistence. Building CICD in the cloud requires rigorous ar...
    "Evatronix provides design services to companies that need to integrate the IoT technology in their products but they don't necessarily have the expertise, knowledge and design team to do so," explained Adam Morawiec, VP of Business Development at Evatronix, in this SYS-CON.tv interview at @ThingsExpo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    To get the most out of their data, successful companies are not focusing on queries and data lakes, they are actively integrating analytics into their operations with a data-first application development approach. Real-time adjustments to improve revenues, reduce costs, or mitigate risk rely on applications that minimize latency on a variety of data sources. In his session at @BigDataExpo, Jack Norris, Senior Vice President, Data and Applications at MapR Technologies, reviewed best practices to ...
    Widespread fragmentation is stalling the growth of the IIoT and making it difficult for partners to work together. The number of software platforms, apps, hardware and connectivity standards is creating paralysis among businesses that are afraid of being locked into a solution. EdgeX Foundry is unifying the community around a common IoT edge framework and an ecosystem of interoperable components.
    "ZeroStack is a startup in Silicon Valley. We're solving a very interesting problem around bringing public cloud convenience with private cloud control for enterprises and mid-size companies," explained Kamesh Pemmaraju, VP of Product Management at ZeroStack, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    Large industrial manufacturing organizations are adopting the agile principles of cloud software companies. The industrial manufacturing development process has not scaled over time. Now that design CAD teams are geographically distributed, centralizing their work is key. With large multi-gigabyte projects, outdated tools have stifled industrial team agility, time-to-market milestones, and impacted P&L stakeholders.
    "Akvelon is a software development company and we also provide consultancy services to folks who are looking to scale or accelerate their engineering roadmaps," explained Jeremiah Mothersell, Marketing Manager at Akvelon, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    Enterprises are adopting Kubernetes to accelerate the development and the delivery of cloud-native applications. However, sharing a Kubernetes cluster between members of the same team can be challenging. And, sharing clusters across multiple teams is even harder. Kubernetes offers several constructs to help implement segmentation and isolation. However, these primitives can be complex to understand and apply. As a result, it’s becoming common for enterprises to end up with several clusters. Thi...