Developing Themes and Skins in IBM® WebSphere® Portal 6.0.X

Developing themes and skins in IBM® WebSphere®
Portal 6.0.X
Ryan Wilson
WebSphere Portal Level 2 Support,
WPLC.J2EE/Portal/WebSphere-based technology
Durham, NC
Jim Barnes
WebSphere Portal Level 2 API Team Lead,
WPLC.J2EE/Portal/WebSphere-based technology
Durham, NC
March 2008
© Copyright International Business Machines Corporation 2008. All rights reserved.
This document provides IBM® WebSphere® Portal developers an understanding of the new
features and layouts available with the version 6.0.X themes and skins, addressing new
functionality such as theme extensions and theme policies. It also covers how the various files
that make up the complete theme are pulled together and how they are used to control the
various aspects of the look and feel.
To get the most from this white paper, you should be familiar with Java™ Server Page (JSP)
and servlet development practices, WebSphere Portal concepts such as xmlaccess, and
WebSphere Application Server administration. Moreover, you should be well versed in HTML
and cascading stylesheet (CSS) files since the WebSphere Portal themes and skins are
returned to the browser in HTML.
Table of contents
1 Introduction..................................................................................................................................3
2 Themes and skins basics ..............................................................................................................3
2.1 JSP files for themes........................................................................................................................... 4
2.2 JSP files for portlet layout and rendering ...................................................................................... 5
2.3 JSP files used for stylesheets............................................................................................................ 6
2.4 JSP files used for JavaScript ........................................................................................................... 6
2.5 Additional JSP files used by the portal theme ............................................................................... 7
2.6 Tags used by WebSphere Portal JSPs ............................................................................................ 8
3 Theme policy ..............................................................................................................................11
3.1 Exporting and updating a theme policy........................................................................................ 13
3.2 Adding custom policy attributes.................................................................................................... 15
3.3 Accessing standard theme policy attributes ................................................................................. 17
4 Color palette ...............................................................................................................................18
4.1 Creating the palette ........................................................................................................................ 18
4.2 Assigning the palette to a page ...................................................................................................... 19
5 Theme extensions.......................................................................................................................20
6 Flyouts and context menus .......................................................................................................32
6.1 Flyouts ............................................................................................................................................. 32
6.2 Context menus................................................................................................................................ 34
7 Development tools .....................................................................................................................37
8 Migrating to version 6.0 from version 5.1................................................................................39
8.1 Adding drag and drop.................................................................................................................... 39
8.2 Considerations when migrating.................................................................................................... 43
9 Conclusion.................................................................................................................................44
Appendix A: Drop-down navigation example ..........................................................................45
Appendix C: Removing unwanted space......................................................................................48
Appendix D: Changing properties of the flyout...........................................................................49
Resources.......................................................................................................................................52
About the authors..........................................................................................................................52
Acknowledgements........................................................................................................................52
1 Introduction
This document is a comprehensive treatment of all aspects of developing themes and skins for
WebSphere Portal 6.0, including theme policy, color palette, theme extensions, and flyouts and
context menus. We also explain how to migrate themes and skins from version 6.0 from 5.1.
2 Themes and skins basics

Before you start coding your new custom theme and skin, you need to understand how all the
parts of the version 6.0 themes fit together. If this is the first time you will be customizing themes
for WebSphere Portal, you may get confused by what each JSP and JSPF will do for the overall
portal and what is appropriate to add to a JSP.
NOTE: Avoid customizing the theme provided out-of-the-box. It is best practice to copy the
IBM directory, give it your own name, and then use that for your sample. Also, it is best to
assign it to a page only, and not the whole portal, while developing it.
In this white paper we include a theme and a skin that give you the same theme and skin as
shown above in your own portal environment. This process is best done on a stand-alone test
environment and is not intended for a clustered configuration. To install, simply extract the .zip
files, using a .zip utility or the .jar command, into the following locations:
For themes:
profiles/wp_profile/installedApps/nodename/wps.ear/wps.war/themes/html/
For skins:
profiles/wp_profile/installedApps/nodename/wps.ear/wps.war/skins/html/
Use the supplied XML file (install_whitepaper.xml) to install the themes and skins and sample
pages into your portal. This installation creates a tab labeled White Paper, with pages under it
with several example themes and skins to go along with the white paper (see figure 1).
Figure 1. White Paper tab
After the installation is complete, open the page in your browser to display the screen in figure 1
above. (Note that this sample is best viewed with the Firefox browser.) This page lets you see
what part of the overall markup is coming from which JSPs. You are also able to see how they
all fit together on the page to make one finished HTML document.
Consider that the theme controls the look and feel of your portal and the navigation throughout
the site. The rest of the layout of the portal page, which includes how the portlets exist relative
to each other, is controlled by the default skin for that theme.
The look and feel of the portlet itself is controlled by the skin you have configured for that portlet.
If no skin is configured, the portlet renders the default skin. If you select a skin for a portlet, not
all of its JSPs are called; only the control.jsp file is called for that skin to render that portlet. This
limitation allows these files to change their rendering based on any theme extensions.
2.1 JSP files for themes

Default.jsp. This file is the JSP that renders the portal page after the portal servlet has
completed its initial preprocessing. This JSP includes numerous other JSPs, JSPFs, and tag lib
definitions. The file also calls the js.jsp and the styles.jsp files, so that they are compiled, and so
the styles and JavaScripts can include JSP logic to change the behavior of the portal
dynamically.
Head.jspf. This fragment is called to set up the header area of the page. Theme extensions
implementing the MetaTagDataItems are included at this time. Several JNDI lookup operations
are performed in this JSPF file. The file also sets up links to the JavaScript and styles JSP files.
Additionally it sets up some of the resources needed for the flyouts and gets other variables
ready for the main menu (Launch button).
Banner.jspf. This fragment is the first visible JSP fragment to be included in the portal. It
represents the top layer of the page and it holds the launch button, the breadcrumb trail, the
search control, and the toolbar JSPF files.
TopNav.jspf. This fragment controls the look and feel of the top navigational bar. This bar can
be one or two layers, depending on the theme policy selected. Edit this JSP file if you want to
create a drop-down navigational structure. The file also holds logic to render the context menus
for the page. Appendixes A and B show additional variations on the navigation of the
WebSphere Portal site.
SideNav.jspf. This fragment controls the side navigation and only has visible content if needed.
This page also has logic to expand and contract the child pages and build the context menus for
the pages.
Footer.jspf. The final fragment is the footer, which holds the normal footer information for page
navigation and quick links to other pages for the users.
2.2 JSP files for portlet layout and rendering

The container JSP files are called from the default skin so they can lay the portlets in columns
and rows. The skin selected for the portlet does not affect the stacking of the portlets into
columns or rows. It is always the default skin for the theme that holds the container JSP files,
which in turn control the layout of rows and columns.
If the default skin does not contain the JSP unlayered containers as listed below, then the
aggregation engine pulls them from the base skin/html directory:
UnlayeredContainer-V.jsp. This file controls the vertical columns for the portlets and how
they are arranged within that column. The tags in the JSP file help control the drag-and-drop
feature.
UnlayeredContainer-H.jsp. This file controls the horizontal appearance of the portlets and
can contain the UnlayeredContainer-V.jsp.
Control.jsp. This file controls the look and feel of the portlet itself. It renders the menu
items, the title bar, and the table that holds the portlet content. It also provides drag-and-
drop handles for moving the portlet around on the portlet page.
These files contain references back to the theme to maintain the same look and feel, which
include images and colors. The files that are containers (UnlayeredContainer-V.jsp and
UnlayeredContainer-H.jsp) are used to render the rows and columns.
In figure 1 above, for example, you can see that there is one row, rendered by
UnlayeredContainer-H.jsp with two columns, with both being rendered by UnlayeredContainer-
V.jsp. These rows and columns correspond to the layout from the edit layout page of the
administration portlet. So, for each column or row, you have separate rendering of the above
files.
2.3 JSP files used for stylesheets
In WebSphere Portal version 6.0, there is one JSP file that is called, and it’s compiled based on
various items from the request, theme policy, and color palette:
Styles.jsp – This is the main JSP file that is called when included in the theme. It is empty of
any real content and includes the following JSPF files: styles_cacheSettings.jspf,
styles_rules.jspf, styles_theme.jspf, styles_portlet.jspf, styles_help.jspf, styles_oob.jspf,
styles_ibm.jspf, styles_palette.jspf, and styles_extensions.jspf. Appendix C shows just one way
that the styles can be adjusted to affect the layout of the theme.
The JSPF files control the style declarations for the following pieces:
styles_cacheSettings.jspf – declares how long the CSS files should be cached. This file is
used to improve performance on the browser side so that it doesn’t need to constantly
request this resource.
styles_extensions.jspf – loops through and pulls any theme extension pieces styles.
styles_help.jspf – styles for help related text and controls.
styles_ibm.jspf – styles used for admin portlets, which generally should not be changed.
styles_oob.jspf – styles for portlets and controls that are ready to use, as is.
styles_palette.jspf – styles used for the palettes and drop-down controls.
styles_portlet.jspf – styles used for portlets that follow the Web Services for Remote
Portlets (WSRP) portlet standard.
styles_rules.jspf – styles used for browser and locale-specific CSS files. All CSS JSP files
should include this one file.
styles_theme.jspf – styles used in the base theme and in the drag-and-drop tags.
2.4 JSP files used for JavaScript

The themes and skins in WebSphere Portal 6.0 make extensive use of JavaScript. When
adding your own JavaScript, ensure there are no collisions with the already-existing JavaScript
in the theme. Like the other parts of WebSphere Portal, there is one main JavaScript file that
includes several other JavaScript files:
js.jsp. This JSP file includes the files js_cacheSettings.jspf, AsynchronousContextMenu.js,
browserDimensions.js, ElementJavascriptEventController.js, flyout.js, and js_extensions.jspf,
which are defined as follows:
js_cacheSettings.jspf – similar to the cache settings file for stylesheets, this file allows the
JavaScript files to be cached by the browser instead of requiring it to be reloaded on every
request.
AsynchronousContextMenu.js – used for the context menus that WebSphere Portal
renders (such as from the portlet drop-down and the theme drop-down controls.) This file
should not be modified.
browserDimensions.js – determines the browser window size for such elements as flyouts.
ElementJavascriptEventController.js – contains helper methods for the other JavaScript
files that should not be modified.
flyout.js – contains methods that control the speed and look of the flyouts used in
WebSphere Portal. Use care when modifying these controls. Appendix D shows additional
changes that can be made to this.
js_extensions.jspf – searches for and loads any theme extensions that are present. Any
custom extensions that you have created that implement the JavascriptItems interface are
pulled in.
2.4.1 Adding items to the onload

In the course of your theme or portlet development you might want to add items to the
onLoad() event of the page. The default themes make extensive use of this event. A better
approach is to use an addEvent method and add items to the onLoad() event. For example:
if (window.addEventListener) //DOM method for binding an event

window.addEventListener("load", methodName(), false)
else if (window.attachEvent) //IE exclusive method for binding an
event
window.attachEvent("onload", methodName())
2.5 Additional JSP files used by the portal theme

The following are additional files used by the portal theme:
flyout.jspf renders the flyouts for the dynamic menus used by the portal. Use care when
modifying this file. Appendix A shows additional changes that can be made to this.
mainMenu.jsp renders the launch menu and should not be modified. To add pages to the Main
Menu, create pages at the first level underneath Content Root. All pages are picked up by
default there. To prevent pages created at this level from being visible, set the hidden flag for
the page parameter for the content-node tag in XML.
Note: You can still view and work with pages that are marked as hidden in Administration
portlets. You can also create a direct URL to the hidden page so that the page can be
accessed from other areas of the site, such as the page menu.
You can use the following XML snippet:
<content-node action="update" ...>

....
<parameter name="com.ibm.portal.Hidden" type="string"
update="set"><![CDATA[true]]></parameter>
...
</content-node>
Or you can use personalization rules to hide pages. For more details on this, refer to the
WebSphere Portal Version 6 information center’s topic, Step 6: Hiding pages on the site .
pageContextMenu.jsp, portletContextMenu.jsp render the page and portlet context menus

that you see as drop-down controls. They should not be modified.
2.6 Tags used by WebSphere Portal JSPs
When creating your own theme, the most commonly used JSP tags used are the <portal-
navigation/> tags. These tags should not be used in portlets and are reserved for use only
inside the themes and skins.
2.6.1 Navigational tags

<portal-navigation:navigation> This tag is used to set up parameters for the navigation tags.
Basically you pass in the start and stop level for the navigation loop. If you want it to start at
navigation level 2 and stop at navigation level 3, it will render the first level of navigation under
portal home, such that you will see all the pages, labels, and URLs from that level.
<portal-navigation:navigationLoop> This tag always occurs inside the <portal-

navigation:navigation> tag. It loops through the navigation levels specified in the navigation tag
above and displays the markup contained in the loop for each node that is pulled out. This
would be the markup that exists between the begin and end tags.
The body of this tag should contain your markup for creating the links to the page and for calling
the context menus for the page if it is within the selection path. Refer to the existing sidenav.jspf
file for more information on what the body of this tag should include.
<portal-navigation:navigationShift by="number" maxPages="number"> This tag is
available for shifting between visible pages, so that if you are currently showing the first five
pages, you can scroll over as many pages that you’ve specified. If the tag is not used, then all
pages are shown for that current level of navigation.
An example of this tag’s usage is:
<portal-navigation:navigationShift by="-5" maxPages="6">
<portal-logic:if pageAvailablePrevious="yes">
<td class="wpsUnSelectedPage">
<a href="<portal-skin:urlParent />"> - </a>
</portal-logic:if>
<portal-logic:if pageAvailablePrevious="no">
<td class="wpsUnSelectedPage">
</portal-logic:if>
</portal-navigation:navigationShift>
<portal-navigation:navigationShift by="+5" maxPages="6">
<portal-logic:if pageAvailableNext="yes">
<a href='<portal-skin:urlParent/>'> + </a>
</td>
</portal-logic:if>
<portal-logic:if pageAvailableNext="no">
</td>
</portal-logic:if>
</portal-navigation:navigationShift>
To use this example, you also need to add this tag lib to the default.jsp file:
<%@ taglib uri="http://www.ibm.com/xmlns/prod/websphere/portal/v6.0/portal-

skin" prefix="portal-skin" %>
<portal-navigation:navigationUrl type="link|expand|collapse|launch"
varname="node_name" var="variable_name"/> This tag is always used within the navigation
loop tags to render links to various navigation nodes. Link and Launch are very similar; the other
two are used when that page has a child node and you want to expand the list to see the child
nodes. To create the link, you add code such as <a href="<portal-navigation:navigationUrl
type='link' />"><portal-fmt:title/></a>
<portal-navigation:url> This tag lets you create links to the screens, commands, or home
attributes from within your theme.
<portal-navigation:urlGeneration> This tag lets you create links directly to various portal
resources, either pages or portlets, and is very similar to the URLs you can create via the URL
generation API. The WebSphere Portal information center and various technotes go into further
detail in creating these links.
<portal-navigation:urlParam name="parameter_name" value="parameter_value"> With

this tag, you can add various parameters to the URL. If you have targeted a portlet, the
parameters can then be retrieved by the getParameter method of the portlet request for a
standard portlet. If the URL tag that is the holder for this parameter tag targets just a page, the
parameters are available to all portlets written to the IBM Portlet API on the page, but they will
not be available to JSR 168-Compliant portlets.
2.6.2 Format tags

<portal-fmt:title varname="scripting_variable"/> When used inside a navigation loop tag,
this tag pulls the page’s title based on the locale, while allowing you to pull the title for any item
that supports the localized interface.
<portal-fmt:description varname="scripting_variable" /> This tag pulls the description for

the object that supports the localized interface.
<portal-fmt:text key="key" bundle="bundle"> This tag returns the given text in the specified
language. Java Standard Tag Library (JSTL) should be used instead of these tags, where
applicable.
<portal-fmt:textParam> This tag can be used only within the text tag. If the key in the bundle
file has a place holder in the format of {0}, then this tag can be used to substitute a value for the
place holders. For example, the file nls.engine contains
welcome = Welcome {0}!
Then, in the JSP file, you can put this snippet:
<portal-fmt:text key="welcome" bundle="nls.engine">

<portal-fmt:textParam>World</portal:textParam>
</portal-fmt:text>
The value for {0} will be replaced with World.
<portal-fmt:user attribute="value"/> This tag returns any attribute as defined in IBM

WebSphere Member Manager (WMM) for the current user.
2.6.3 Logic tags
<portal-logic:if attribute="value"> This tag checks a variety of conditions that might exist,
including loggedIn, nodeInSelectionPath, portletMaximized, and portletState. You can use this
tag to change various aspects of the theme to be conditional.
<portal-logic:pageMetaData/> This tag accesses the metadata for the page.
<portal-logic:unless> This tag is the opposite of the <portal-logic:if attribute="value"> tag

above but works on the same conditional states as that tag; that is, if the condition is true, the
content of the tag is not written to the HTML output and instead the content is rendered.
<portal-logic:urlFindInSkin file="file_name"> and <portal-logic:urlFindInTheme
file="file_name"> These tags let you build URLs that point to the files as they exist in either the
theme or skin without having to hard-code the URL. You can have the URL for all your images
use this tag and place the images in your theme directory, after which WebSphere Portal will
find them and generate the correct URL.
Using this tag lets the portal engine determine the correct URL path for the image and write that
to the HTML output. An example is
<portal-logic:urlFindInTheme file="images/toolBar/help.gif"/>
where the .gif file exists at the following location on the file system:
wps.ear\wps.war\themes\html\IBM\images\toolBar
2.6.4 Other items affecting theme rendering

When using the default theme as the basis for your new custom theme or when developing your
own theme, using the guidelines found in the information center, you must be mindful of the
theme policy. The theme policy affects how parts of the WebSphere Portal-provided tags
render. Theme policies can cause these tags to change and can leave you with a theme other
than the default theme. For example, some of the theme policies instruct the theme not to
render the theme extensions, so the theme extension tags do not render any output when
called.
Another item affecting rendering is the color palette. You can select various color palettes based
on several factors to change what color scheme the theme uses. For example, you can use the
same theme but a different palette to deploy across different business units.
Finally, you can extend your theme by using the theme extensions framework. These items are
examined in detail later in this document.
Special Notes:
• When you want to modify the look and feel of palettes, be aware that these are separate
portal pages, and they have their own assigned themes. If you want to modify properties
such as the colors and images, you must make sure to edit the correct theme. The
pages on which the palettes are use the IBM theme by default.
• To change the icon for the portlet, you must define the name of the .gif file in the
configuration parameters for the portlet. The parameter name is "portlet_Icon_name",
and the value can be just the name of the file, "my_weather.gif". Check the "My
Weather" portlet as a guide, if you still have it installed.
• The image file must be located in the <theme>/images/palette/portlets directory. After

making the change in the configuration of the portlet, you may need to log out and open
a new browser before you see the new image.
3 Theme policy
The theme policy is a new concept that was introduced with version 6.0 of WebSphere Portal.
This policy controls how various parts of the theme are displayed on the page. Using various
theme policies, you can have one theme but have several looks to your portal.
The only way to update a given theme policy is through the XML configuration interface. You
can apply this policy by using either the properties portlet or the XML configuration tool. As with
many other aspects of themes, you need only set a theme policy on a page if it needs to be
different than the parent policy. Once this setting is set on a page, it is handled through the
process of inheritance, cascading down through any children pages, until it gets to a page with
an explicit definition.
The theme policy contains several attributes, each one controlling a single aspect of the page.
For example, the Boolean renderBreadCrumb attribute controls whether the breadcrumb
displays, and the breadCrumbMaxLevels attribute controls the number of steps listed in the
breadcrumb trail when it displays.
The theme policy can control whether any theme extensions are run and rendered into your
theme. Be mindful of this control when setting the renderExtensions attribute to false, as it can
cause all the theme extensions to fail.
Table 1 lists all possible theme policy attributes and their type.
Table 1. Theme policy attributes

Attribute Type Function
renderMainMenu Boolean If true, the main menu is rendered.
renderTopNavigation Boolean If true, top navigation is rendered.
renderMainMenuActions Boolean If true, the main menu actions are rendered.
renderSelfCare Boolean If true, Selfcare is rendered.
renderBreadCrumbTrail Boolean If true, the breadcrumb trail is rendered.
render renderSearch Boolean If true, search is rendered.
renderToolBar Boolean If true, the toolbar is rendered.
renderContentPalette Boolean If true, the portlet palette is rendered.
renderPeoplePalette Boolean If true, the people palette is rendered.
renderContextMenus Boolean If true, context menus are render.
renderSideNavigation Boolean If true, side navigation is rendered.
renderTaskBar Boolean If true, the task bar is rendered.
Attribute Type Function
renderFavorites Boolean If true, favorites is rendered.
renderExtensions Boolean If true, extensions are rendered.
renderBannerTitleGraphic Boolean If true, the banner title graphic is rendered, as
long as one exists.
renderPortletFragmentIDAnchor Boolean Determines if the user is on a palette page.
renderBannerTitle Boolean If true, the banner title is rendered, as long as
one exists.
breadCrumbMaxLevels Integer Indicates the number of steps listed in the
breadcrumb trail.
breadCrumbStartLevel Integer Indicates which level to start the breadcrumb
trail.
rootNavigationStartLevel Integer Indicates the start level for root navigation.
rootNavigationStopLevel Integer Indicates the stop level for root navigation.
topNavigationNumRows Integer Indicates the number of rows to render for top
navigation.
topNavigationStartLevel Integer Indicates the start level for top navigation.
topNavigationStopLevel Integer Indicates the stop level for top navigation.
sideNavigationStartLevel Integer Indicates the start level for side navigation.
The default WebSphere Portal installation comes with ready-to-use policies, including
SingleTopNav, SingleTopNavMinimal, DoubleTopNav, DoubleTopNavMinimal, SideNavOnly,
SideNavOnlyMinimal, NoTheme, Federation, SingleTopNavLevel2, and Palette.
The last three policies should not be modified because they are used on various parts of the
default theme for flyouts and other pieces of the interactive theme. Additionally, the Federation
policy cannot be applied to any page using the XML configuration tool or the properties portlet.
Here are descriptions of the theme policies:
SingleTopNav – used when you want only one level of top navigation. It renders only five levels
in the breadcrumb trail and only three levels of side-level navigation.
SingleTopNavMinimal – is similar to the one above and is used when you want a minimal
amount of navigation options and links on the page. The self care, breadcrumb trail, search
control, toolbar, palettes, context menus, favorites, extensions, title, and graphics in the title bar
are not rendered. Top and side navigation and the main menu are rendered, but all the actions
in the main menu are not rendered.
DoubleTopNav – quite similar to the SingleTopNav except that two levels of navigation are
rendered along with the top level. All other navigation is picked up by the side navigation.
DoubleTopNavMinimal – quite similar to the SingleTopNavMinimal, but with the navigation, it

changes as in DoubleTopNav.
SideNavOnly – causes all levels of navigation to be rendered in the side navigation area.
SideNavMinimal – similar to the other minimal policies, but all side navigation is rendered on
the side navigation area.
NoTheme – has all elements of the theme not to be rendered. This policy is similar to a plain
theme template that could be used for a print preview, if you wanted just to print the content of
the portlet.
For more information on these policies and their specific attributes, refer to the information
center’s Theme policies topic.
When working with the theme policy in your JSP files, use the <portal-theme-
ext:initthemepolicy/> tag to set up the theme policy. This tag is in the IBM theme in the
default.jsp file and makes two variables available to the JSP files:
portalThemePolicyMap and portalThemePolicyPath.
The theme policy path is the theme policy name, like SideNavMinimal. This attribute is the same
one you use when exporting the theme policies. This tag checks whether a theme policy has
been set via the URL state and, if not, it checks on the page to determine whether a theme
policy has been set. If it cannot find the theme policy, it uses the default value of SingleTopNav.
Add the following code snippet to your default jsp file in your theme to load the map into a
bean for easy access elsewhere in your JSP:
<jsp:useBean id="themePolicy"
class="com.ibm.portal.theme.policy.ThemePolicyBean" scope="page"/>
<% themePolicy.setValuesMap(portalThemePolicyMap);%>
3.1 Exporting and updating a theme policy

To update the theme policy, first export it using the XML configuration utility indirectly. The URL
location specified points to an XML file that you want it to create. The xmlaccess files are
indirectly used to access the theme policy utility. Use this example as your input file:
<?xml version="1.0" encoding="UTF-8"?>

<request xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
create-oids="true" type="export"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<portal action="locate">
<policy-node action="export" label="WebPage"
type="theme" path="">
<url>file:///c:/temp/exportThemePolicies.xml</url>
</policy-node>
</portal>
</request>
If you want to export only one policy, replace the path attribute with the name of the theme
policy. For example, if you had a policy named TestThemePolicy, replace path="" with
path="TestThemePolicy".
After you have generated the export XML file, update any attributes (such as changing the
renderExtensions attribute from true to false), and then use that as your import file into the XML
configuration tool in the next step. This operation is necessary when we get to the next step of
creating your own theme policy pieces.
The XML file that is generated cannot be used as an import file to the XML configuration utility.
You must always pass the utility an XML file that points to the actual policy XML file. This file will
either be the file used to update the existing policy or to create the file when doing an export
operation:

create-oids="true" type="update"
<policy-node action="update" label="WebPage" type="" path="">
<url>file:///c:/ibm/PortalServer/bin/exportThemePolicies.xml</url>
</policy-node>
</portal>
</request>
If you wanted to delete your theme policy, the XML would look like this:
create-oids="true" type="update"
<policy-node action="delete" label="WebPage"
type="theme" path="TestThemePolicy">
</policy-node>
</portal>
</request>
After you have created your new theme, assign it to a page by specifying the metadata attribute
com.ibm.portal.ThemePolicy.
This example sets the theme policy SingleTopNavMinimal to the page

ThemePolicyPageTest:
<request type="update" create-oids="true"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd">
<content-node action="update" ordinal="last"
uniquename="ibm.portal.ThemePolicyPageTest" content-parentref="Content.Root"
active="true" allportletsallowed="false" create-type="explicit"
objectid="wp.theme.policytestpage" type="page">
<supported-markup markup="html" update="set"/>

<parameter name="com.ibm.portal.ThemePolicy" type="string"
update="set">theme/SingleTopNavMinimal</parameter>
</content-node>
</portal>
</request>
Here are some tips to follow when updating a theme policy:
If you are only updating a theme policy, you must perform these steps:
z Export the theme policy.

z Edit the values of the attributes to be updated.
z Use the XML configuration interface to import your file, which is referenced from the
actual input file to xmlaccess.
When updating, if you are also extending a theme policy by adding attributes to it, the attributes
must also be added to the root theme policy:
z Export the entire theme policy structure.

z Edit the root theme policy.
z Edit the theme policy to be updated by adding the attribute, if the value is different than
the root theme policy.
z Import the file that references the file that has the updated definitions.
If you are modifying only the value of an attribute that already exists in a theme policy, use the
following guidelines:
z Export the theme policy you want to modify.

z Make the appropriate changes to the attribute.
z Import the file that references the file which has the updated definitions.
3.2 Adding custom policy attributes

When creating your own theme policy, you can also add your own custom attributes, which can
be of type integer, Boolean, or string. These attributes can then be used in your JSP file to
control the rendering of certain parts of your theme.
To create your own custom theme policy attribute, export the root theme policy by simply
exporting everything as described above.
After you have the output, add the following to the root policy definition that exists at the top of
the XML file that was created from the export operation:
<policyValue
Name="renderTestAttribute"
Factory="com.ibm.wps.policy.parse.BooleanFactory">
<value>false</value>
</policyValue>
<policyValue
Name="renderTestAttributeLock"
<value>false</value>
</policyValue>
Then import the file back into WebSphere Portal using the configuration interface, which adds
them to all theme policies. In one of your theme JSP files, put the following code snippet:
<% boolean isTestAttribute =

themePolicy.getValueAsBoolean("renderTestAttribute", false);
if(isTestAttribute){%>
<p> Display this paragrah if renderTestAttribute is true. </p>
<%}%>
Because this value is a Boolean type, we used the getValueAsBoolean method, but the theme
policy object actually has three accessor methods:
• getValueAsBoolean(String key, boolean defaultValue);

• getValueAsInt(String key, int defaultValue);
• getValueAsString(String key, String defaultValue);
where key is the name of the attribute as defined in the theme policy and defaultValue is the
value that is used if the attribute value cannot be retrieved from the theme policy.
Next, create your own policy called test policy. Included in the Downloads that accompany this
white paper is a file to be used to import this theme policy (newtesttheme.xml). The theme
policy contained in the newtesttheme.xml is a copy of the DoubleTopNav, but with the added
item of the renderTestAttribute.
This file has the renderTestAttribute set to true and once we apply it to a page, we will be
able to see the HTML text rendered in the page that was contained in the if tag that we added
above. After creating our own test policy and importing it, we assign the test policy to a page
that has the theme that we modified to have the scriptlet above.
<policyValue
Name="renderTestAttribute"
<value>true</value>
</policyValue>
In figure 2, we see that based on the theme policy, the paragraph is visible.
Figure 2. Visible paragraph

3.3 Accessing standard theme policy attributes
Another way to access the theme policy attributes in a JSP file is to load the themepolicy for the
page directly into the page for reference inside the expression language for the JSP. To do this,
add the following snippet in the default.jsp file for the standard IBM Theme:
<portal-theme-ext:initthemepolicy/>
class="com.ibm.portal.theme.policy.ThemePolicyBean" scope="page"/>
Then in your JSP code, retrieve the value:

<c:if test="${themePolicy.renderTopNavigation}">
<p> Display this paragrah if renderTopNavigation is true and we are loading
from the page map. </p>
</c:if>
The one limitation is that only the standard theme policy attributes are available in this way. You
must use the standard getter methods to get any values that you add to extend the theme
policy.
If you want to extend this access so that you can call the bean as above for your own attributes,
you can do the following:
First, in Rational® Application Developer create a Java project, pointing to the WebSphere
Portal 6.0 runtime and JDK.
Next, add the following JAR file from /shared/app to the buildpath:
wp.theme.themepolicy.jar file. Finally create a class like the following:
package com.ibm.wps.l2.themepolicy;
import com.ibm.portal.theme.policy.ThemePolicyBean;
public class MyThemePolicyBean extends ThemePolicyBean {
private static final String RENDER_TEST_ATTRIBUTE =

"renderTestAttribute";
/**
* Controls whether the theme should render the title in the banner.
* @return Returns the renderBannerTitle.
*/
public boolean isRenderTestAttribute() {
return
this.getValueAsBoolean(MyThemePolicyBean.RENDER_TEST_ATTRIBUTE, true);
}
}
Add as many getter methods to the class for all of your custom attributes. Export this file as a
JAR file, place it in the shared/app directory, and then restart the server. A sample is included in
the Downloads theme_policy_test.jar.
Change the policy bean loading to the following:

class="com.ibm.wps.l2.themepolicy.MyThemePolicyBean" scope="page"/>
Then, you can retrieve your values like this:
<c:if test="${themePolicy.renderTestAttribute}">
<p> Display this paragrah if renderTestAttribute is true and we are
loading from the page map. </p>
</c:if>
4 Color palette
The color palette lets you keep colors and certain icons separated from your stylesheets. This
separation lets you change the color used on the page without needing to change any theme
code. For example, public pages could be one color, and authenticated pages could be another
color.
The palette is defined by a properties file that is loaded by the stylesheet JSP files and then
used to dynamically pull the properties to configure settings within the stylesheet files. The
default palette can be overridden on a per-page basis.
4.1 Creating the palette

The IBM-provided palettes are stored in the following location:
/profiles/profilename/installedApps/nodename/wps.ear/wps.war/themes/ht
ml/IBM/colors.
In this directory is a file called default.properties and a directory called default,

where the default color §palette is included.
A color §palette is defined by an identifier, which is the name of the directory and the name of
the properties file. To create a new color §palette, for example, called testthis, create a
properties file labeled testthis.properties and a folder labeled testthis.
This property file stores parameters as key value pairs. In the default theme, all keys are
prefaced with a setX, where X is a number. This preface is used to group the properties into
sets of like properties. These are just a convenience and are not needed when creating your
own §palette, but all color definitions must contain the same keys. Figure 3 contains a sample of
some of these properties.
Figure 3. Sample properties
In the above samples, set1Text1 defines the text color in the selectedPage style class, but
set1Text2 and set1Text3 do not have corresponding elements in the CSS box model.
These values are included to provide multiple text colors for emphasis. The values could be
used, for example, to specify the text color for <h1> and <h3> elements, or for <strong> text. If
you need more values, add them. If you don’t need them at all, they can be deleted. There is no
requirement for the contents of the property file, only that the keys used here correspond to their
use in the stylesheet JSP files, and that all properties files contain the same keys.
4.2 Assigning the palette to a page

After you have defined all your colors, you can then assign the palette to a page. The theme
determines what color palette is in use by the metadata in the head.jspf file of the theme:
<portal-logic:pageMetaData varname="pageMetaData">

<c:set var="colorPalette" scope="request">
<c:out value="${pageMetaData.colorPalette}" default="default"/>
</c:set>
</portal-logic:pageMetaData>
It gets a value from the page metadata and, if none is found, it uses a default color palette. It is
important that all your themes have a default color palette and not just custom ones so that, if
the metadata is missing, the page still renders. By default, pages do not have a colorPalette
metadata value.
For example, to assign the testthis color palette as a default to the pages, do the following:
1. Click the Page properties of the page on which you want to use a specific color palette.
2. Expand “Advanced options.”
3. Click “I want to set parameter.”
4. Enter color§Palette as New parameter.
5. Enter the name of the color-palette property file as the New value. For example, enter
testthis to assign testthis.properties.
4.2.1 Referencing a color palette in CSS

The Styles_rules.jspf file loads the [color§Palette].properties file and stores it in
a map request attribute, colors, for use by the CSS style definitions. The most efficient way to
reference the values is with Expression Language (EL) expressions. EL expressions let you
reference a map's values by a simplified dot notation. For example,
${colors.set1Background} retrieves the set1Background color.
If you are only creating a new color palette for the existing theme, you need not modify the
styles_*.jspf files. This modification is required only if you have added or removed keys
from the properties files.
For example, suppose you have added a new key that has a font color and a key for font size.
You have two properties files, blue and red, and you have added this to the default.properties
file. Next, add a style to the stylesheet JSP files so that this new key is pulled. Then, assign that
style to the parts of the markup that you want.
5 Theme extensions
Extensions aid in the building of a modular product with loosely coupled components. Extension
points define how the component is to be extended, and the extensions comprise the additional
functionality. WebSphere Portal uses the Eclipse plug-in framework to define the theme
extensions. Visit eclipse.org for complete details on the plug-in framework and API.
Like the Eclipse framework, theme extensions provide extension points to create and extend
plug-ins. This extension allows for a highly customizable theme with little or no coding changes.
Theme extensions let you add content to the rendered page without updating JSP files.
WebSphere Portal provides several extensions that are ready to use, as is. Some of the default
extensions include functionality to add flyouts or context menu items.
5.1 Theme extension APIs

The APIs for theme extensions consist of several interfaces and a set of classes that provide a
default implementation to the core interfaces. We now briefly discuss the interfaces and then
discuss the default implementations in more detail. Please see the imaged included in the zip
labeled themeextension_class_diagram.jpg for more information.
5.1.2 Interfaces
ThemeContent:
All theme extensions indirectly extend the ThemeContent interface. Any element that
contributes content to the theme using a defined extension point is of type ThemeContent.
Two methods are defined in this interface:

• getOrdinal - determines the priority, in which the lower the value, the higher the priority.
If no value is specified using the plugin.xml file, then a value of -1 should be returned.
• init(ThemeContext context) - initializes the ThemeContext.
Inherited methods:
• isActive method is inherited from com.ibm.portal.ActiveFlag. Returns true if
the include should be rendered; otherwise, it returns false.
• SetInitializationData is inherited from

org.eclipse.core.runtime.IexecutableExtension. Sets the initialization
data that is used to get attributes from the plugin.xml file. This method is passed an
IconfigurationData object. This object represents the plugin.xml file of the
extension and contains methods for extracting the attributes defined in the item element
of the plugin.xml file.
The following three methods are inherited from com.ibm.portal.Localized:

• getDescription - returns the description.
• getLocales - <lookup>
• getTitle - returns the title.
There are two types of ThemeContent, ThemeItems and ThemeIncludes:
ThemeItems
Theme items are responsible for contributing content directly to the page. Two methods are
defined in this interface:
• getTooltip(java.util.Locale)
Returns the tooltip text for the current locale. If no value is specified or if there is an
exception then null should be returned.
• newIconURL(com.ibm.portal.state.access.url.portalresource.State
state)
Returns the URL of type com.ibm.portal.state.DisposableURL for the
specified icon. If the URL cannot be created or does not exist, a null value is returned.
This method can throw a StateException.
There are two types of ThemeItem, ThemetextItem and ThemeLinkItem:

ThemetextItem
Contributes simple text. This interface adds one method:
• getText(java.util.Locale)
Returns the text to be contributed to the markup.
ThemeLinkItem
Creates a URL to contribute to the theme. This interface adds two methods:
• newURL
Returns the generated URL of type com.ibm.portal.state.EngineURL or null if
the user is not allowed to access the resource.
• RequiresPOST
If the URL is the target of an action, this method should return true.
ThemeIncludes
ThemeIncludes are responsible for rendering their own content. RequestDispatcher should
be used to include a JSP. The content is included using the render method. One method is
• render()
The render method is responsible for including the JSP.
ThemeJspInclude
A ThemeJspInclude is responsible for rendering itself by invoking a JSP using a
RequestDispatcher. The invoked JSP is responsible for maintaining the look and feel of
the overall theme. One method is included in this interface:
• getJspPath()
Returns the JSP path to be included.
ThemeContext
Describes the current theme context. This interface formalizes the current context for a specific
ThemeContent. An extension can declare a custom context in the plugin.xml file by
including the context attribute in the markup describing the extension. Three methods are
• getRequest()
Returns the request associated with this context.
• getResponse()
Returns the response associated with this context.
• initContext(javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
Initializes the context.
Constants:
There are three interfaces for defining constants to be used in theme extension. The constants
represent the attribute names used in the default implementation of the theme extensions and
match the attribute names as defined in the plugin.xml file. For example, the
ThemeItemDescriptorConstants contains a constant named TOOLTIP_ATTRIBUTE.
This constant maps to the tooltip attribute in the plugin.xml file:
<item id="jsmith"
class="com.ibm.wps.themeext.sample.ContactNames"
firstName="John"
lastName="Smith"
email="jsmith@us.ibm.com"
tooltip="John Smith"/>
ThemeContentDescritporConstants: Constants describing the XML attributes for a

DefaultThemeContent.
ThemeItemDescriptorConstants: Constants describing the XML attributes for a ThemeItem.

ThemeJspIncludeDescriptorConstants: Constants describing the XML attributes for a
DefaultThemeJspInclude.
See the API for detailed information about all the interfaces discussed, which you can find in the
developerWorks WebSphere document, Javadoc for WebSphere Portal V6.0 and V6.01.
5.1.3 Default implementations

The theme extension APIs provide default implementations for the interfaces listed above. They
provide a convenient extension point to the APIs without having to implement all the required
methods. You can use these implementations rather than writing your own classes.
In this section we discuss the attributes for each of the implementation classes. Most of the
attributes are optional; however, those that are required are identified here.
Some attributes do not fit to a particular type and are global:
• id (optional) -- Specifies identification for this element. Although it is not required to make
this value unique, it is a best practice to do so.
• class (required) -- Identifies which class should be used for this element.
• tooltip (only used in theme items; optional) -- This text is rendered using the
ThemeExtensionItemToolTip tag.
• context (optional) -- Identifies a custom ThemeContext to be used. If a context is not
specified, then a default one will be provided.
DefaultThemeContent
This class is the default implementation of ThemeContent and provides access to the following
attributes defined in the plugin.xml file:
• description (optional) -- Provides a description about the extension.

• ordinal (optional) -- This method determines the priority, in which the lower the value, the
higher the priority. The extension will be ordered based on their ordinal value, if
specified.
• title (optional but should be included) -- Defines the title for the extension.
All default implementations of ThemeItems (DefaultThemeLinkItem and DefaultThemeTextItem)

extend this class, which means that they are inherently able to access these attributes when
defined in the plugin.xml file.
DefaultThemeItem
This call provides a default implementation for ThemeItems and handles all the icon processing
for the newIconURL method. This class works in conjunction with the
ThemeExtensionItemIconUrl tag.
Only the following attribute is defined for this default class.
z iconName
Defined the path and name of the icon to be used for this extension.
DefaultThemetextItem
Provides an implementation for a ThemetextItem. The text defined is rendered to the theme
using the ThemeExtensionItemText tag. The following attribute is the only one added by this
class:
z text (required)
Text to be contributed to the markup.
DefaultThemeLinkItem
This implementation creates a portal link to the specified content node. For this implementation
the following methods return false or null:
RequiresPOST (returns null)

getTooltip (returns null)
getOrdinal (returns 0)
isActive (returns false)
getLocales (returns false)
isAllowed (always returns true)
The following additional attributes are added:
z contentNode
This attribute should be the uniqueName of the page you are targeting.
z useNewWindow
Used when targeting new windows like flyouts. The value would be true.
DefaultThemeJSPInclude
This class provides the implementation to include a JSP in the theme. The render method is
invoked to call the RequestDispather to include the desired JSP file. The following attributes are
added with this class:
z Jsp (required)
The relative path to the JSP to be included.
The previous section discussed the default implementations and the attributes required in the
plugin.xml file. If you decide not to use the default implementation and create your own, it is
important to understand how these attributes are resolved. It would be a best practice to use the
attribute names described above, but it is not required.
There may also be cases in which you need to extend the default implementation to add more
attributes.
The following is a snippet of a plugin.xml file that uses a ThemeTextItem. For this example,
we only use a few of the possible predefined attributes, while adding a custom attribute:
<extension point="com.myco.theme.plugin.Sample" id="Sample_01"

name="Test_01" >
<item id="Page1"
class="com.myco.sample.TextSample"
description="This is sample text"
text="some value for page 1"
text2=”some other text”/>
</extension>
This extension uses a class named TextSample as defined in the class attribute. TextSample
extends DefaultThemeTextItem and overrides the setInitializationData method to process that
new attribute, text2. When the setInitializationData method is called on TextSample, the
IConfigurationElement is used to retrieve the text2 attribute. The IconfigurationElement object
contains a method to retrieve all attributes defined in the item element of the plugin.xml file.
Example:
public void setInitializationData(IConfigurationElement element,

String arg1,
Object arg2) throws CoreException {
super.setInitializationData(element, arg1, arg2);

String value = element.getAttribute(“text2”);
if(value != null){
myCustomValue = value;
}
}
The attribute is retrieved from the IconfigurationElement by use of the getAttribute method. This
is how the plugin.xml attributes are realized in the theme extension code.
5.1.4 Default extension points

The default themes provide a set of extension points. The Suggested Interface field describes
the interface that provides the information required by the default extension point. Type
enforcement is not performed at runtime. However, if an implementation does not provide at
least the information required by the Suggested Interface, the extension might not display
correctly in the theme.
The following list describes the extension points provided:
com.ibm.portal.theme.plugin.MetaTagDataItems
• Description: Provides components the ability to add data to the meta tags of a page.
• content type: ThemeItem
• Interface: ThemeTextItem
com.ibm.portal.theme.plugin.Styles
• Description: Provides components the ability to contribute CSS to the page.
com.ibm.portal.theme.plugin.Javascript
• Description: Provides components the ability to add JavaScript to the page.
com.ibm.portal.theme.plugin.HorizontalPageBarItems
• Description: Provides components the ability to add JSP content to the horizontal page bar.
• content type: ThemeInclude
• Interface: ThemeJspInclude
com.ibm.portal.theme.plugin.VerticalPageBarItems
• Description: Provides components the ability to add JSP content to the vertical page bar.
com.ibm.portal.theme.plugin.MainContextMenuItems
• Description: Provides components the ability to add an item to the main context menu.
• Interface: ThemeLinkItem
com.ibm.portal.theme.plugin.PageContextMenuItems
• Description: Provides components the ability to add an item to the page context menu.
com.ibm.portal.theme.plugin.PortletContextMenuItems
• Description: Provides components the ability to add an item to the portlet context menu.
com.ibm.portal.theme.plugin.Flyouts
• Description: Provides components the ability to add flyouts to the page.
5.1.5 Plugin.xml
The plugin.xml file is used to define extensions and extension points. The following
elements should be used within the plugin.xml file:
plug-in
This element is the root of the XML file and the following attributes should be defined:
• id
This attribute is the root identification for the plug-in. This ID combined with the ID in the
extension-point element are used to determine the entire extension point. For example,
if the ID defined in the plug-in element is com.ibm.portal.theme.plugin and the ID
attribute in the extension-point element is “Styles”, then they would combine to give
the fully qualified extension point the name of
com.ibm.portal.theme.plugin.Styles.
• name
Name used to identify the plug-in.
• version
The version number of the plug-in.
• provider-name
This name should identify the vendor writing the plug-in.
extension-point
Used when defining a new extension point. This element is a child element of the plug-in
element and has the following attribute:
• id
Unique identifier of this extension point that’s used in conjunction with the id attribute in
the plug-in element to determine the fully qualified extension-point.
extension
This element is also a child element of the plug-in element and is used to extend an extension
point. When participating in theme extensions, this element will be used the most. The following
attribute are defined:
• point
Fully qualified name of the extension point you want to extend.
• id
Unique identifier for the extension.
• name
Unique name for the extension.
item
This element is a child of the extension element and is used to define the ThemeContent. The
attributes for this element vary depending on the extension-point being targeted. As outlined
above we have defined the attributes required for the default implementation and also outlined
how to define custom attributes.
The following is an example of a plugin.xml file using a custom extension point:

<plugin id="com.myco.theme.plugin" name="Theme Extensions Plug-in Page Value
Samples"
version="1.0.1" provider-name="IBM">


<extension-point id="Sample" />
<extension point="com.myco.theme.plugin.Sample" id="Sample_01"

name="Test_01" >
<item id="Page1"
class="com.myco.sample.TextSample"
description="This is sample text"
text="some value for page 1"
text2=”some other text”/>
</extension>
</plugin>
5.1.6 Theme extensions in a JSP

WebSphere Portal defines a set of JSP tags to initialize and process theme extensions, listed
below. These tags should be used only within themes and skins and are not supported for use
in portlets. For a complete listing of attributes, see the information center.
themeExtension
Starts the processing of the theme extension. The id attribute is used to identify the fully
qualified extension point.
themeExtensionLoop
Iterates through all extensions defined in the plugin.xml file. This tag makes the ThemeItem
object available with a variable named themeExtension.
themeExtensionItemTooltip
Prints the tooltip specified. If a tooltip is not identified, then nothing is rendered.
themeExtensionItemText
Prints the text associated with the extension. The class defined in the plugin.xml for the
extension must be of type TextItem.
themeExtensionItemUrl
Prints the URL associated with a ThemeLinkItem.
themeExtensionItemIconUrl
Creates a URL for the extension icon.
themeExtensionRenderInclude
Renders the content associated with ThemeIncludes, which are responsible for rendering their
own content.
Extensions are instantiated each time they are used via the
IConfigurationElement#createExecutableExtension method. This instantiation for
each access can have a performance impact, so the placement of an extension should be
carefully considered. Avoid placing the extension inside nested loops.
Custom extension point

We now create a simple custom theme extension for displaying user contact information. To do
this, you’ll need to perform the following steps:
1. Create a plugin.xml file defining your extension point and extensions.

2. If needed, create classes and interfaces for your extension.
3. Bundle your classes and plugin.xml file into a JAR file.
4. Place this JAR file under the portal/shared/app directory.
5. Update the theme to read the plug-in and properly render the extension.
6. Restart the server to force your new classes to be loaded.
Let’s start with creating the plugin.xml file. First, define the XML document:
Next, define the root of the XML file; for the plugin.xml, it will be plug-in. The id attribute
used in this element is combined with the extension-point ID to form the full extension-point ID.
Also, define the name, version, and provider-name:
<plugin id="com.myco.theme.plugin" name="Theme Extensions Contact Samples"

version="1.0" provider-name="IBM">
Next, define the extension-point and give it an id of “ContactNames”.
<extension-point id="ContactNames" />

Next, define an extension for this extension-point:
<extension point="com.myco.theme.plugin.ContactNames" id="ContactNames_01"

name="names_01">
Use the combination of the ID of the plug-in and the ID of the extension-point. The id and name
are used during logging. While uniqueness is not enforced, try to create names unique to your
plug-in.
Next, we define items that correspond to the ThemeItem objects used in the theme. For a single
extension-point you can have multiple items defined. The item also needs to define the class to
be used and an ID.
This example lists contacts with a first name, last name, and email ID:
<item id="rywilson"
firstName="Ryan"
lastName="Wilson"
email="rywilson@us.ibm.com" />
Add a few more contacts, and the complete file will look like this:

<plugin id="com.myco.theme.plugin" name="Theme Extensions Contact Samples”
version="1.0" provider-name="IBM">
<extension-point id="ContactNames" />
<extension point="com.myco.theme.plugin.ContactNames" id="ContactNames_01"

name="names_01">
<item id="rywilson"
firstName="Ryan"
lastName="Wilson"
email="rywilson@us.ibm.com" />
<item id="jwbarnes"
firstName="James"
lastName="Barnes"
email="jwbarnes@us.ibm.com" />
</extension>
</plugin>
Because custom attributes were used, we must create a class that will read them. In this class,
define some constants that define the attribute names and override the setInitializationData
method to read these attributes from the IconfigurationElement object. For this example we will
extend the DefaultThemeTextItem class and take advantage of the default implementations.
First, create an interface named IcontactNamesItem.
Add the following constants to identify the attribute names from the item element:
public static final String FIRST_NAME = "firstName";
public static final String LAST_NAME = "lastName";
public static final String EMAIL_ID = "email";
Next, define a set of Strings used to store the values of these attributes:
private String firstName;
private String lastName;
private String email;
Our interface will define the following getters and our implementation will set and return the
values:
public String getEmail();
public String getFirstName();
public String getLastName();
Create a class that extends DefaultThemeTextItem and also implements

IContactNamesItem.
Next, override the setInitialization method to retrieve the data:
public void setInitializationData(IConfigurationElement element, String arg1,

Object arg2) throws CoreException {
String value = element.getAttribute(FIRST_NAME);

if(value != null){
firstName = value;
}
value = null;
value = element.getAttribute(LAST_NAME);
if(value != null){
lastName = value;
}
value = null;
value = element.getAttribute(EMAIL_ID);
if(value != null){
email = value;
}
}
This coding is needed to create the bean that represents the ThemeItem. We could have
optionally added another method to generate the markup, to email this customer.
While defining the getters in the interface works when using a small number of attributes, there
is a better solution if there are many more attributes defined.
You could use a Map to store all the data, and then have one method for retrieving the desired
attribute. We could rework the example so that the interface looked like this:
public interface IContactNamesItem {

public static final String FIRST_NAME = "firstName";
public static final String LAST_NAME = "lastName";
public static final String EMAIL_ID = "email";
public String getAttribute(String key);
Our implementation would then change to the following:
public class ContactNames extends DefaultThemeTextItem implements

IContactNamesItem{
private Map attributes = new HashMap();
public void setInitializationData(IConfigurationElement element, String

arg1, Object arg2) throws CoreException {
String value = element.getAttribute(FIRST_NAME);

if(value != null){
attributes.put(FIRST_NAME, value);
}
value = null;
value = element.getAttribute(LAST_NAME);
if(value != null){
attributes.put(LAST_NAME, value);
}
value = null;
value = element.getAttribute(EMAIL_ID);
if(value != null){
attributes.put(EMAIL_ID, value);
}
}
public String getAttribute(String key){

if(key !=null){
return (String)attributes.get(key);
}
return null;
}
}
This implementation provides a cleaner solution, especially when there are a large number of
attributes.
To display the list of contacts on the top of the page, add this code in the default.jsp. The taglib
for the theme extensions is already defined for the IBM-provided themes. If you are using a
custom theme, add the theme extensions taglib definition:
<%@ taglib uri="http://www.ibm.com/xmlns/prod/websphere/portal/v6.0/portal-

theme-ext"
prefix="portal-theme-ext"%>
The policies can determine whether or not theme extensions are enabled, so place your theme
extension code after the theme policy initialization tag:
<portal-theme-ext:initthemepolicy />
class="com.ibm.portal.theme.policy.ThemePolicyBean" scope="page" />
<%themePolicy.setValuesMap(portalThemePolicyMap);%>
Using the themeExtension tag, specify the extension point to include. We have defined the
extension-point to be com.myco.theme.plugin.ContactNames, so this is the value to use in the
id attribute:
<portal-theme-ext:themeExtension id="com.myco.theme.plugin.ContactNames" >
Next, we iterate through all extensions that have this point defined. This is the advantage of
using theme extensions: Other WebSphere Portal administrators can create their own plug-in
that extends this extension point and provide additions to the contact list, developers could also
create a custom class that implements IcontactNamesItem and defines some custom logic, and
all this can be done without needing to change the theme.
While looping through the extension we cast the implicit themeExtension object that is provided
in the themeExtensionLoop tag:
<portal-theme-ext:themeExtensionLoop>
<%
com.ibm.wps.themeext.sample.ContactNames contact =
(com.ibm.wps.themeext.sample.IContactNamesItem)themeExtension;
After we have this object, we can use it to create a mailto link to this contact.
out.println("<a href='mailto:" + contact.getAttribute(contact.EMAIL_ID) +
"'>" + contact.getAttribute(contact.FIRST_NAME) + " " +
contact.getAttribute(contact.LAST_NAME) + "</a><br>");
%>
</portal-theme-ext:themeExtensionLoop>
</portal-theme-ext:themeExtension>
6 Flyouts and context menus

Let’s now discuss flyouts and context menus.
6.1 Flyouts
Flyouts are customizations that take advantage of the theme extensions so that you don’t need
to modify any theme JSP files. You can drop these JAR files into your shared app directory,
restart the server, and the extensions are added to the theme as it renders.
In this example we create a link to the enable tracing page so that it renders as a flyout.
We need to create a Java project in Rational Application Developer (or your tool of choice), then
add the portal runtime to the build path, and finally add these three JAR files:
portal_root\shared\app\wp.theme.extensions.api.jar
portal_root\shared\app\wp.theme.extensions.impl.jar
portal_root\shared\ext\eclipse-runtime.jar
For our example, we created a class that extends the class ThemeLinkItem.
The methods outlined below in that class are doing most of the work.
The following method creates the URL using a URL- generation API, making use of a helper
class to do all the URL creation (for more information, refer to the developerWorks article,
“Leveraging WebSphere Portal V6 programming model: Part 2. Advanced URL
generation in themes and portlets.”):
public EngineURL newURL() throws StateException

{
EngineURL result = null;
try {
result =
ServletURLGenerator.generateUrlForFlyout("ibm.portal.Enable Tracing",
"wps.p.Enable Tracing", aContext.getRequest(), aContext.getResponse() );
} catch (Exception ex) {
System.out.println("There was a problem generating a flyout
url");
}
return result;
}
The following method specifies which graphic to display into the theme for expanding and
collapsing this new flyout. This example uses a graphic of a pencil writing. You can use any
graphic you want, but limit the size of the graphic to 21 pixels square. We use the helper class
to generate the URL for us, which makes use of the URL-generation API:
public DisposableURL newIconURL( State state ) throws StateException {

DisposableURL url = null;
try {
url =
ServletURLGenerator.getDisposableURL(aContext.getRequest(),
aContext.getResponse(), "images/toolBar/tracing.gif");
System.out.println("Unable to create the url");
}
return url;
}
This method returns the title to be shown when hovering over the icon. It will also be used if the
graphic URL cannot be retrieved:
public String getTitle( Locale arg0 ) {

return "Enable Tracing";
}
This method renders in a new window instead of the current one. In a flyout, this will let it
actually fly out over the current window instead of trying to be in the window:
public boolean isNewWindow()

{
return true;
}
Finally, in your Java project at the root level, you need a plugin.xml file:
<plugin id="com.ibm.wps.l2.whitepaper.samples" name="Theme Extensions Plug-in
Samples" version="1.0.1" provider-name="IBM">
<extension point="com.ibm.portal.theme.plugin.Flyouts"
id="WPSToolBaryFlyouts" name="ToolBarFlyouts">
<item id="DebuggingFlyout"
class="com.ibm.wps.l2.whitepaper.samples.TracingFlyout"
title="My Portal Extension" />
</extension>
</plugin>
This tells WebSphere Portal from where to load your extension, and where to add it in the
theme extension hierarchy. Because we have not defined any new extension points, we do not
have the tag for the extension-point. Instead, there is the extension we are adding to the already
existing extension points.
To deploy this implementation, put the graphic into the theme in use that will go under
app_server_root/profiles/profilename/installedApps/nodename/wps.ear/wp
s.war/themes/html/themename/images/toolBar/.
Next, export this Java project from your development environment. Note: Make sure you have
specified 1.4 as the compiler compliance level, as Rational Application Developer uses 5.0 by
default for Java projects.
Take the JAR file that was exported in the previous step, drop it into
portal_server_root/shared/app, and then restart the WebSphere Portal server. Using
our example, you should now see the image for tracing in the upper-right-hand corner of your
theme (see figure 4).
Figure 4. Tracing image
6.2 Context menus

Several context menus are included by default. At this time, do not use the theme extension
points to create your own context menu. Instead, use the extension points to add items to the
context menus, either for the page, the portlet, or the whole portal. You can selectively enable
these menu items at runtime, based on criteria.
To create a context menu item, create a class that extends ThemeLinkItem.

In this class, we have overridden the setInitializationData to pull in the properties from our
plugin.xml file, to parameterize this class (this is discussed in more detail in Section 5 Theme
extensions, above):
public void setInitializationData( IConfigurationElement arg0, String

arg1, Object arg2 ) throws CoreException
{
String titleValue = null;
titleValue = arg0.getAttribute( TITLE_ATTRIBUTE );
if ( titleValue != null ) {
this.title = titleValue;
}
String descriptionValue = null;

descriptionValue = arg0.getAttribute( DESCR_ATTRIBUTE );
if ( descriptionValue != null ) {
this.description = descriptionValue;
}
String urlValue = null;

urlValue = arg0.getAttribute( EXTERNAL_URL_ATTRIBUTE );
if ( urlValue != null) {
this.externalUrl = urlValue;
}
}
Based on the values that we pulled in, we create a URL to an external site:
public EngineURL newURL() throws StateException {

return new ExternalURL( this.externalUrl );
}
Finally, we tell it to open the page in the existing window:
public boolean isNewWindow() {

return false;
}
Then, in the plugin.xml file, add the following:
<extension point="com.ibm.portal.theme.plugin.PortletContextMenuItems"
id="WPSExternalPortletMenuLinks" name="ExternalPortletMenuLinks">
<item id="GoogleLink3"
class="com.ibm.wps.l2.whitepaper.samples.ExternalLinkItem"
title="Google"
description="Search for relevant items."
url="http://www.google.com" />
</extension>
This code loads these parameters into the class, using the setInitializationParameterData
method. In this way, you can reuse the code above to create several links to add to the context
menu of your choice (page, portal, or portlet).
Just by changing it to this example, it is added to the Main menu instead of the Portlet Context
menu:
<extension point="com.ibm.portal.theme.plugin.MainContextMenuItems"
id="WPSExternalMainMenuLinks" name="ExternalMainMenuLinks">
<item id="GoogleLink1"
class=" com.ibm.wps.l2.whitepaper.samples.ExternalLinkItem”
title="Google"
description="Search for relevant items."
url="http://www.google.com" />
</extension>
It would display in the drop-down control from the launch button instead of anywhere else in
WebSphere Portal.
Also included in the source code is an example of a Page Context menu item that points to a
portal page. The class is InternalLinkItem and extends the ThemeLinkItem. This link points to a
custom Create Page that could exist anywhere inside your portal, but will be accessible from the
Page Context menus of any page, as long as the theme policy to render theme extensions is set
to true.
The method to create the URL also used the helper class and looks like the following (this
helper class could let you target a portlet and pass parameters to it):
public EngineURL newURL() throws StateException {

EngineURL result = null;
try {
result = ServletURLGenerator.generateUrlStringServlet(page, null,
null, context.getRequest(), context.getResponse());
System.out.println("This exception in this code = " + ex);
}
return result;
}
In the plugin.xml file, we have the following to describe this new item:
<extension point="com.ibm.portal.theme.plugin.PageContextMenuItems"
id="WPSExternalPageMenuLinks" name="ExternalPageMenuLinks">
<item id="LinkToSearchResults"
class="com.ibm.wps.l2.whitepaper.samples.InternalLinkItem"
title="Create Page"
description="Create a New Page."
page="Create_Page" />
</extension>
For full source code listing, see the attached code in the Downloads file (in the jar
theme_ext_sample.jar in the following directory filesforwhitepaper\contextmenus). Several
methods that are needed are defined in the source, but we have not modified them in any
significant way.
More information on these methods is also in the Javadoc for theme extensions, which can be
found in the IBM WebSphere Portal Support technote #1247155, Theme APIs were not
included in version 6.0 of IBM WebSphere Portal.
7 Development tools
As the new version contains a significant level of complexity and improvement from previous
versions, debugging all the interactions can be quite tricky. Luckily there are tools that make
both HTML and JavaScript debugging easier.
The tools we’ve used the most are plug-ins for Firefox that let you make real-time changes to
the source code and see how it changes the look, without requiring you to refresh the browser.
Also, you’ll be able to pinpoint which area needs changing easier.
The first of these add-on tools is the Web developer plug-in for Firefox. The second is called
Firebug, which is helpful for debugging issues with JavaScript and CSS.
With both these plug-ins installed, you can inspect the rendered Web site in the following
manner. Right-click an element and then choose Inspect Element (see figure 5).
Figure 5. Inspect Element menu option
That action displays a window at the bottom of the browser that lets you see the HTML source
code for the current element (see figure 6).
Figure 6. HTML source code displayed
Additionally, you can view the stylesheets, the JavaScripts, the DOM, and Net, which shows you
the response time for various pieces to load.
Next, on the right side, are the stylesheet definitions in use for this element (see figure 7).
Figure 7. Stylesheet definitions
You can click to edit one of these or add a new setting to see how it would look in the rendered
output. This change affects only this page view and is not persisted.
With the Web developer toolbar you can also validate the HTML and CSS. You can outline all
table elements, which can be helpful when the page is failing to load correctly. Line guides are
also available to help with positioning of items when pixels measurements are used. A ruler is
available that you can stretch directly on the page to measure distances between visual objects.
There is a wealth of other options, and you’ll be sure to find both these tools very useful when
developing themes and skins.
8 Migrating to version 6.0 from version 5.1

When migrating to version 6.0, you won’t want to convert all your skins and themes to full 6.0
style.
8.1 Adding drag and drop

Using the steps below, you won’t need to rebuild your version 5.1 skins to support the drag-and-
drop functionality of version 6.0. Refer to the Drag and drop JSP tags section in the
information center to read about the tags you need in your skin JSP files to support this
functionality.
The main tags are:
<dnd:DNDPortletHelper/> must be in the JSP; otherwise, it will not work. This tag loads
several JavaScripts that are needed to make drag-and-drop work.
<dnd:drag/> designates which part of the actual content is dragable.
<dnd:drop/> sets up a drop zone.
<dnd:dragHandle/> designates a part of the portlet to be used as the handle for drag and
drop.
First, in the control.jsp file, add the following import:
<%@ page import="com.ibm.portal.content.LayoutNode"%>
and tag lib declaration:
<%@ taglib uri="/WEB-INF/tld/dnd.tld" prefix="dnd" %>
After the wps:constant tag, add the following:
<%!
private static com.ibm.portal.identification.Identification identification;
public void jspInit(){
try{
/* only perform this JNDI lookup once as this is an expensive call
performance wise */
javax.naming.Context ctx=new javax.naming.InitialContext();
identification=(com.ibm.portal.identification.Identification)
ctx.lookup("portal:service/Identification");
}
catch (javax.naming.NamingException ne){
}
}
%>
<%
String currentLayoutNodeStr="";
if (pageContext.getAttribute("currentLayoutNode", pageContext.REQUEST_SCOPE)
!= null) {
LayoutNode
currLayoutNode=(LayoutNode)pageContext.getAttribute("currentLayoutNode",
pageContext.REQUEST_SCOPE);
currentLayoutNodeStr=identification.serialize(currLayoutNode.getObjectID());
}
else {
LayoutNode
currLayoutNode=(LayoutNode)pageContext.getRequest().getAttribute("com.ibm.wps
.composition.element");
currentLayoutNodeStr=identification.serialize(currLayoutNode.getObjectID());
}
%>
<dnd:DNDPortletHelper />
These set up certain items in the context of the page so they are available for the later tags for
the drag-and-drop feature.
Next, directly after the above, add:
<dnd:drag namespace="wp" type="portlet_windowID"

value="<%=currentLayoutNodeStr%>" includeDragHandle="false"
validator="com.ibm.wps.dnd.impl.DNDDragPortletValidator">
Then add this closing drag tag after the end of the portlet content in the control.jsp file:
</dnd:drag>
The next two tags you need to add are:
<dnd:dragHandle>
</dnd:dragHandle>
The easiest place to add them is around the display part for the portlet title.
8.1.1 Drop zones

You need to add a drop tag inside some element, either a div or table, so that it’s actually large
enough to interact with. Start with UnlayeredContainer-H.jsp and first add:

<dnd:DNDPortletHelper/>
This area will be the start area:
<dnd:drop namespace="wp" type="portlet_windowID" action="#"

name="<%=com.ibm.wps.dnd.util.Constants.PORTLET_INSTANCE_ID%>"
validator="com.ibm.wps.dnd.impl.DNDPortletActionValidator"
optionalActionJavascript="DND_MOVE_PORTLET_JS">
Then at the end of the section, add:

<dnd:additionalAction namespace="wp" type="portlet_ID" action="#"
name="<%=com.ibm.wps.dnd.util.Constants.PORTLET_ID%>"
supportsMultiselect="true" multiselectDelimiter="__DND_DELIM__"
optionalActionJavascript="DND_ADD_PORTLET_JS"/></dnd:drop>
The easiest way to do this would be to add the following above your layout node:

optionalActionJavascript="DND_MOVE_PORTLET_JS"><table><%-- We use these rows
to make the vertical drop zones large enough to interact with.
There is a problem when trying to get a table to expand to fill an entire
region vertically. --%><tr valign="top"><td> </tr><tr
style="height:100%;"><td> </td></tr><tr
valign="bottom"><td> </td></tr></table><dnd:additionalAction
namespace="wp" type="portlet_ID" action="#"
Then add your layout node loop.
And then, at the end, add the following:
<td style="width:10px;" valign="top"><dnd:drop namespace="wp"

type="portlet_windowID" action="#"
optionalActionJavascript="DND_MOVE_PORTLET_JS"><table><%-- We use these rows
to make the vertical drop zones large enough to interact with.
There is a problem when trying to get a table to expand to fill an entire
region vertically. --%><tr valign="top"><td> </tr><tr
style="height:100%;"><td> </td></tr><tr
valign="bottom"><td> </td></tr></table><dnd:additionalAction
namespace="wp" type="portlet_ID" action="#"
This code lets you drag before or after the portlet in that row.
Next, modify the Unlayered-Container-V.jsp file to be able to drag and drop in the
columns by adding this tag lib:
and this tag:
<dnd:DNDPortletHelper/>
In your layout loop, add this code into a row or div element above where your portlet is called to
render:

optionalActionJavascript="DND_ADD_PORTLET_JS" />
</dnd:drop>
After the layout loop you should add a row or div like the following:

supportsMultiselect="true"
multiselectDelimiter="__DND_DELIM__"
optionalActionJavascript="DND_ADD_PORTLET_JS" />
</dnd:drop>
These lines will give you the drop zones before and after the portlets in the column.
8.1.2 Theme changes

Finally, you must add the stylesheet for the page. These styles give your drop zones visible
areas during the drag and drop, so that it is easy to see what areas can be dropped into (very
helpful when you have removed all portlets from a column):
/* DRAG AND DROP */

.dndDropAware{
border: 0px;
background-color: #FFEBC5;
}
.dndDropActive{
border: 0px;
background-color: #FF9000;
}
.dndDragging{
width: 100%;
filter: alpha(opacity=40);
}
.dndDragSelected{
border: 1px;
background-color: #DDDDDD;
}
.dndMoveCursor{
cursor:move;
}
.dndDropCursor{
cursor: pointer;
}
.dndNoDropCursor{
cursor: not-allowed;
}
.layoutRow {width: 100%; }

.layoutColumn {width: 100%; }
The easiest way to do the drop zones is to copy the Unlayered-Container-v and h.jsp
files to your skin from that of the IBM skin, as this sets up the drag-and-drop areas easily.
8.2 Considerations when migrating

Default navigational state. This setting tells the portal container whether to render navigation
nodes in an expanded or collapsed mode. This setting affects the rendering of the navigation
tree as it appears on the left side by default.
In WebSphere Portal version 5, this setting was set to true so that all nodes were shown as
expanded on the right side. The setting caused the navigational loop tags to loop through all the
child tags and display links to all the child pages.
In version 6, this default state is set to false. If you use any coding to create drop-downs or
flyouts that rely on the navigation loop tags producing links to all the children, you must set this
value back to false. Otherwise, it will generate links to only the top level, and your drop-down
lists will not appear fully populated.
To override this setting in version 6, change the setting

navigation.expansion.defaultstate to true in the Configuration Service. For more
information on setting properties in version 6, see the information center topic, Setting
configuration properties.
Behavior of skins. When running your version 5.1 skins on 6.0, you will have an issue if your
portlet supports the edit mode. In version 6.0 the concept of edit_defaults and personalize
modes were added. The standard edit mode is not referred to as personalize, and those values
are stored to the customization database domain. However, edit_defaults will save the
preferences to the release domain.
When any 5.1 theme is used on 6.0 and you click edit, it will go to the personalize mode, even
when an administrator or manager is doing the editing. For this feature to work correctly, you
must add the edit_defaults compatibility mode to your portlet and add a link in your skin. This
provides you with a link from personalize that points to the edit mode, and then one that reads
Edit Default Settings pointing to the edit_defaults mode. The following is an example from the
6.0 menu:
<portal-navigation:urlGeneration contentNode="<%=pageID%>"
layoutNode="<%=windowID%>" portletMode="edit" themeTemplate="" ><c:set
var="title"><a href=<%= wpsURL.write(escapeXmlWriter); %>'<portal-
fmt:text bundle="nls.titlebar" key="edit" /></a>
<portal-navigation:urlGeneration contentNode="<%=pageID%>"
layoutNode="<%=windowID%>" portletMode="edit_defaults"
themeTemplate="" ><c:set var="title"><a href=”<%
wpsURL.write(escapeXmlWriter); %>”><portal-fmt:text
bundle="nls.titlebar" key="edit.defaults" /></a>
9 Conclusion
This white paper has presented you with various points for customization and skills necessary to
create a theme to meet your implementations needs. Additionally we have provided many tools
with which you can create the look and feel that you need, while taking advantage of code reuse
and the latest extension points of the 6.0 theme.
An important point to understand is that when WebSphere Portal finishes with its aggregation
(skins, themes, and portlets ) all that is returned is HTML, CSS, and Javascript. Keep this in
mind when troubleshooting your themes and skins, to keep separate what is a possible
WebSphere Portal code defect and what is an HTML display issue or limitation.
Appendix A: Drop-down navigation example
Drop-down navigation is a common request for changing the navigational structure of
WebSphere Portal. You could replace the table that is shown with whatever you wanted from
the example in figure 8.
Figure 8. Example drop-down navigation
If you want to create a drop-down menu in the version 6 theme, use the URL generation
services and the navigation model API. In the JSP or servlet, find the following:
NavigationModelHome home = (NavigationModelHome)

ctx.lookup("portal:service/model/NavigationModel");
PortalStateManagerServiceHome serviceHome =
(PortalStateManagerServiceHome)
ctx.lookup("portal:service/state/PortalStateManager");
PortalStateManagerService service =
serviceHome.getPortalStateManagerService(request, response);
Then, add the following:
// do something (create URLs etc.)

urlFactory = service.getURLFactory();
EngineURL eUrl = urlFactory.newURL(Constants.SMART_COPY);
//EngineURL eUrl = urlFactory.newURL(new StateHolder(), false, false,
Constants.SMART_COPY);
final SelectionAccessorFactory selectionFct = (SelectionAccessorFactory)
service.getAccessorFactory(SelectionAccessorFactory.class);
// get a selection controller that operates on the URL-specific state
final SelectionAccessorController selectionCtrl =
selectionFct.getSelectionAccessorController(eUrl.getState());
Finally, loop through the navigation model:
NavigationModelProvider provider = (NavigationModelProvider)

home.getNavigationModelProvider();
NavigationModel model = provider.getNavigationModel(request, response);
NavigationNode nodeA = (NavigationNode)model.getRoot();
NavigationNode childNode = null;
NavigationNode childNode2ndLevel = null;
if(model.hasChildren(nodeA)) {
Iterator iter = model.getChildren(nodeA);
NavigationNode homeNode = (NavigationNode)iter.next();
Iterator homeIter = model.getChildren(homeNode);
while (homeIter.hasNext()) {
childNode = (NavigationNode)homeIter.next();
selectionCtrl.setSelection(childNode.getObjectID());
The root node is always ContentRoot, and in most all cases, Home is the first node under the
Content Root. Iterate through those children to build the URLs, which will be built from this piece
of code: href="<%=eUrl%> and the title from childNode.getTitle(localCurrent).
In your default.jsp file, remove the sidenav.jsp include because you will no longer need
side navigation.
The files to update in your theme include flyoutTop.js, topNav.jsp, spacer.gif, and style.css.
You can find these in the Download .zip file accompanying this document, under the following
directory:
filesforwhitepaper\themes\testDropDown.
Appendix B: Right-hand navigation example
Figure 9 shows an example of right-hand navigation.
Figure 9. Right-hand navigation example
To achieve this, change this line in the default.jsp file from this:
<table style="width:100%; height:100%;" cellpadding="0px" cellspacing="0px">

<tr><td valign="top"><portal-logic:if portletSolo="no"><%@ include
file="./sideNav.jspf" %></portal-logic:if></td><td width="100%" height="100%"
valign="top"><a name="wpsMainContent"></a><%-- Call the portal engine command
to render the portlets for this page --%><div id="mainContent"><portal-
core:screenRender/></div></td></tr></table>
To this:
<table style="width:100%; height:100%;" cellpadding="0px" cellspacing="0px">

<tr><td width="100%" height="100%" valign="top"><a
name="wpsMainContent"></a><%-- Call the portal engine command to render
the portlets for this page --%><div id="mainContent"><portal-
core:screenRender/></div></td><td valign="top"><portal-logic:if
portletSolo="no"><%@ include file="./sideNav.jspf" %></portal-
logic:if></td></tr></table>
Appendix C: Removing unwanted space
Other customizations you might want to make on your portal include reducing space between
portlets. The portlet has several things that control the spacing, among which is the style:
#mainContent {
padding:5px;
}
Change it to zero and most of that space goes away; the last bit comes from
.wpsPortletBody {
background-image:none;
margin:5px;
}
The wpsPortlet CSS has a 0px padding, and the rest should go away:
.wpsPortlet{
margin:5px;
border-left: 1px solid;
border-right: 1px solid;
border-bottom: 1px solid;
border-color: #CACACA;
background-image:none;
}
Additionally, the drag-and-drop controls take up some space. If you reduce the padding above,
however, you can make it hard to interact with these controls. These controls are the drop
zones for where you can drop the item you are dragging. If you want to disable drag-and-drop
functionality, you can remove these tags from the portlet skin that is the default for the theme.
Appendix D: Changing properties of the flyout
IBM provides two flyouts with the base theme, the people palette and the portlet palette. In your
implementation, you might have your own directory search portlet that you want to place on the
flyout page instead of using the default user People Search portlet.
If you remove the existing portlet from the people palette and place your own directory search
portlet on the page, you will encounter some problems (such as the URL not being created and
exceptions listed in the log). When you removed the old portlet from the page, you removed a
portlet instance with the unique name of ibm.portal.People Palette Control.
The theme code that creates the URL to the flyout uses the URL generation services and
targets the original People Search portlet by name. After you remove it, the URL generation
services cannot find that portlet instance on the people palette page, so it is unable to render
the icon. You have two options to address this issue:
(1) The recommended way is to give one of the portlets on that page the above unique name,
following only steps 2, 3, and 4 from the IBM Support technote “URLGeneration in
WebSphere Portal v5.1 - Linking to another portlet”.
Export the page (people palette) with this XML code:

<request type="export" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xsi:noNamespaceSchemaLocation="PortalConfig_1.2.xsd">
<content-node action="export" uniquename="ibm.portal.People
Palette" />
</portal>
</request>
The result is similar to this output:
<component action="update" active="true" deletable="false" domain="rel"

modifiable="false" objectid="7_UV9FQLI11O1BF026LUV0FD08G3" ordinal="-1"
orientation="H" type="container" width="undefined">
<component action="update" active="true" deletable="false"
domain="rel" modifiable="false" objectid="7_UV9FQLI11O1BF026LUV0FD08G7"
ordinal="100" orientation="V" type="container" width="undefined">
<component action="update" active="true"
deletable="false" domain="rel" modifiable="undefined"
objectid="7_UV9FQLI11O1BF026LUV0FD0880" ordinal="100" type="control"
uniquename="ibm.portal.People Palette Control" width="undefined">
<portletinstance action="update" domain="rel"
objectid="5_UV9FQLI11O1BF026LUV0FD0884"
portletref="3_UV9FQLI11O1BF026LUV0FD00C6"/>
</component>
</component>
</component>
Notice the line: uniquename=”ibm.portal.People Palette Control”.

Finally, reading from your output, you must modify one of the components surrounding the
portlet and put the uniquename attribute on it with the exact value of ibm.portal.People
Palette Control.
(2) Another possible way to address the issue, though it was not tested, is to edit the URL
generation tag in the head.jspf file and remove the layoutNode attribute from this line:
url:"<portal-navigation:urlGeneration contentNode='ibm.portal.People
Palette' layoutNode='ibm.portal.People Palette Control'
newWindow='true' portletWindowState='Normal'><% wpsURL.write(out);
%></portal-navigation:urlGeneration>",
If you put more than one portlet on the page, you will also need to change the size of the flyout.
To change the width, change the following lines in the file styles_theme.jspf:
<%--===================================================
FLYOUT
===================================================--%>
.portalFlyout{
position: absolute;
left: -390px;
width: 382px;
background-color: ${colors.bodyBackground};
}
Next, make sure that styles.jsp gets recompiled. If you do not have reloading enabled, you
need to restart the server after editing the file. In our example, we changed it to the following:
<%--===================================================
FLYOUT
===================================================--%>
.portalFlyout{
position: absolute;
left: -600px;
width: 600px;
background-color: ${colors.bodyBackground};
}
When making these changes, also change the size of the scrollable area for the flyout:
<div id="wpsFLYflyout" class="portalFlyout" >

<iframe class="portalFlyoutIframe" id="wpsFLY_flyoutIFrame"
frameborder="0px" width="380px" name="wpsFLY_flyoutIFrame" src="<portal-
logic:urlFindInTheme file="./flyoutInit.html" />" scrolling="auto"></iframe>
</div>
In the flyout.jspf file, the value of 380px needs to be changed to whatever you had set the
flyout site to above. In our example we set it to 600.
Then if you want to change the speed at which the flyout happens, change two parts of the
JavaScript. First, in the js directory, open the flyout.js file and change these lines:
wpsFLY_minFlyout=0;var wpsFLY_move=25;if (wpsFLY_isIE)
wpsFLY_move=20;var wpsFLY_scrollSpeed=1;var wpsFLY_timeoutID=1;var
wpsFLY_fromTop=100;var wpsFLY_leftResize;var
wpsFLY_browserDimensions=new
The move variable must be changed, if you want to change the speed of the flyout.
In the same file farther down, change these two lines:
setTimeout('wpsFLY_internalScroll()',1);};function
wpsFLY_internalScrollLeft() {
The default is 20. In the example, it is 1.
Then on this line, change these lines:
setTimeout('wpsFLY_internalScrollLeft()',1);};function
wpsFLY_internalResizeLeft(){
After you make these changes, the flyout will move at a faster speed.
These methods wait X number of milliseconds (from the timeout above) to move it to what you
specified above (in the wpsFly_move settings).
Resources
• IBM WebSphere Portal Version 6.0 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wps/adsetcfg.html
• IBM developerWorks WebSphere Portal zone:

http://www.ibm.com/developerworks/websphere/zones/portal/
About the authors

Ryan Wilson is the Technical Lead for the WebSphere Portal Level 2
API/Migration team in RTP, North Carolina. His areas of expertise include J2EE
application development with IBM WebSphere Studio and Rational Application
Developer. He has participated in many projects, including internal tools
development. Other works include the IBM Rational Application Developer V6
Portlet Application Development and Portal Tools Redbooks publication. Ryan
holds certifications in WebSphere Portal development(5.1, 6.0), and is a Java
Certified Programmer, and Java Certified Web Component Developer.
James Barnes is currently the Level 2 Team Lead for the WebSphere Portal
API/migration team. Jim joined IBM in 1999 first working the Lucent outsourcing
account. After joining Level 2 in 2003, he started focusing on development-related
issues. Jim holds a BS from Virginia Tech in Agriculture and Applied Economics.
Other works include the 5.1 WebSphere Portal Handbook and extensive articles
on the Support web site on migration and development. He holds Certifications for
WebSphere Portal development(5.1, 6.0) and WebSphere Portal
Administrator(5.0, 5.1, 6.0).
Acknowledgements
The authors extend special thanks to William Trotman and Morgan Kinne for their valuable help in
preparing this document.
Trademarks
• IBM, Rational, and WebSphere are trademarks or registered trademarks of IBM Corporation in the
United States, other countries, or both.
• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
• Other company, product, and service names may be trademarks or service marks of others.
IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtml
This edition applies to version 6, release 0, modification 0 of WebSphere_Portal (product number 6.0.0.0)
and to all subsequent releases and modifications until otherwise indicated in new editions.

Developing Themes and Skins in IBM® WebSphere® Portal 6.0.X

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Developing Themes and Skins in IBM® WebSphere® Portal 6.0.X

Hochgeladen von

Copyright:

Verfügbare Formate

Developing themes and skins in IBM® WebSphere®

© Copyright International Business Machines Corporation 2008. All rights reserved.

2 Themes and skins basics

2.1 JSP files for themes

2.2 JSP files for portlet layout and rendering

2.4 JSP files used for JavaScript

2.4.1 Adding items to the onload

if (window.addEventListener) //DOM method for binding an event

2.5 Additional JSP files used by the portal theme

<content-node action="update" ...>

pageContextMenu.jsp, portletContextMenu.jsp render the page and portlet context menus

2.6.1 Navigational tags

<portal-navigation:navigationLoop> This tag always occurs inside the <portal-

An example of this tag’s usage is:

<portal-navigation:navigationShift by="-5" maxPages="6">

<%@ taglib uri="http://www.ibm.com/xmlns/prod/websphere/portal/v6.0/portal-

<portal-navigation:urlParam name="parameter_name" value="parameter_value"> With

2.6.2 Format tags

<portal-fmt:description varname="scripting_variable" /> This tag pulls the description for

welcome = Welcome {0}!

Then, in the JSP file, you can put this snippet:

<portal-fmt:text key="welcome" bundle="nls.engine">

The value for {0} will be replaced with World.

<portal-fmt:user attribute="value"/> This tag returns any attribute as defined in IBM

<portal-logic:pageMetaData/> This tag accesses the metadata for the page.

<portal-logic:unless> This tag is the opposite of the <portal-logic:if attribute="value"> tag

2.6.4 Other items affecting theme rendering

• The image file must be located in the <theme>/images/palette/portlets directory. After

Table 1. Theme policy attributes

Here are descriptions of the theme policies:

DoubleTopNavMinimal – quite similar to the SingleTopNavMinimal, but with the navigation, it

3.1 Exporting and updating a theme policy

<?xml version="1.0" encoding="UTF-8"?>

<?xml version="1.0" encoding="UTF-8"?>

This example sets the theme policy SingleTopNavMinimal to the page

<request type="update" create-oids="true"

Here are some tips to follow when updating a theme policy:

z Export the theme policy.

z Export the entire theme policy structure.

z Export the theme policy you want to modify.

3.2 Adding custom policy attributes

<% boolean isTestAttribute =

• getValueAsBoolean(String key, boolean defaultValue);

Figure 2. Visible paragraph

Then in your JSP code, retrieve the value:

private static final String RENDER_TEST_ATTRIBUTE =

Change the policy bean loading to the following:

Then, you can retrieve your values like this:

4.1 Creating the palette

In this directory is a file called default.properties and a directory called default,

4.2 Assigning the palette to a page

4.2.1 Referencing a color palette in CSS

5.1 Theme extension APIs

Two methods are defined in this interface:

• SetInitializationData is inherited from

The following three methods are inherited from com.ibm.portal.Localized:

There are two types of ThemeContent, ThemeItems and ThemeIncludes:

There are two types of ThemeItem, ThemetextItem and ThemeLinkItem:

ThemeContentDescritporConstants: Constants describing the XML attributes for a

ThemeItemDescriptorConstants: Constants describing the XML attributes for a ThemeItem.

5.1.3 Default implementations

Some attributes do not fit to a particular type and are global:

• description (optional) -- Provides a description about the extension.