Customizing themes in IBM Lotus Quickr services for IBM WebSphere Portal V8.0

Learn about the default theme used in IBM Lotus Quickr services for IBM WebSphere Portal and discover how to customize it.

Richa Bansal (bansalr@us.ibm.com), Software Developer, IBM

Richa Bansal is a Software Developer for IBM in Durham, NC. She focuses on Content Management - IBM Lotus Quickr. You can reach her at bansalr@us.ibm.com.



15 January 2008

Also available in Russian

This article provides an overview of the default theme used in IBM Lotus Quickr services for IBM WebSphere Portal and gives the details you need to perform desired customizations of the theme. The main sections of the article focus on how to change the theme, how to customize the welcome page, how to put your own skin on all the Lotus Quickr pages, and how to make your deployment look like your place.

Prerequisites

You should have a good understanding of basic HTML, Java Server Pages (JSP), Cascading Style Sheets (CSS), and JavaScript. To get the full benefit from this article, you must also be familiar with IBM WebSphere Portal themes. Refer to the WebSphere Portal Information Center for information on WebSphere Portal themes and WebSphere Portal theme customizations.


Getting started

To make modifications to the theme, you need administrative access to the Lotus Quickr server. The Lotus Quickr theme is shipped in a folder named QPG in the WebSphere Portal theme directory. The section that follows describes how to create custom themes and skins from Lotus Quickr and how to apply them to the desired team places. It also describes the steps you take to enable JSP reloading on the custom theme. This approach helps save development time when you make changes to the theme.

Create a custom skin

Lotus Quickr uses QuickrSkin as the default skin for the QPG theme. If you choose, you can create a new skin that is more suited to your custom environment. The skin files are located here :

was_profile_root/installedApps/cellname/wps.ear/wps.war/skins/html/

Use the default skin called QuickrSkin as the starting point for your custom skin. To do this, copy the existing QuickrSkin folder to a new folder and rename that folder custom_skin. You can now set this skin as the default skin for your custom_theme.

Create a custom theme

To create your custom theme, first make a copy of the Lotus Quickr theme folder and rename that folder to a name that is appropriate to your theme. The WebSphere Portal theme files are located here:

was_profile_root/installedApps/cellname/wps.ear/wps.war/themes/html

You need to make a copy of the QPG folder and paste that copy back into the WebSphere Portal theme folder at the above location. After pasting it, you can rename the folder custom_theme. You are now ready to set the custom_theme on the desired places in your workspace.

Set theme to a place

Your next step is to register your custom_skin and custom_theme with WebSphere Portal, and then to set them both on the desired team places. To do this, you first need to create a new theme in WebSphere Portal and point that to the custom_theme folder. Choose Site Administration – Advanced Administration – Themes and Skins. If you created a custom_skin, register your new skin by clicking the Add New Skin button on this page. See figure 1.

Figure1. Adding a new skin
Adding a new skin

Choose Site Administration – Advanced Administration – Themes and Skins. If you created a custom_skin, register your new skin by clicking the Add New Skin button on this page.

You are now ready to register your theme and set your custom_skin as the default skin for your custom_theme. The directory name listed on the WebSphere Portal site administration page must match the folder name that you created in the WebSphere Portal theme directory. In this example, the new theme name and directory name are both set to custom_theme. At this point, you have the option to add any skins desired by your theme, and then to set the custom_skin as the default skin. See figure 2.

Figure 2. Setting the default skin on a theme
Setting the default skin on a theme

After you have created the new theme and registered it in WebSphere Portal, you can apply it to one or more places. Choose Site Administration – Advanced Administration – Portal User Interface – Manage Pages, and then follow these steps. See figure 3.

  1. Click the content root under the My Pages header on the right side.
  2. In the list of pages that appear on this page, navigate to your place under Application Root or search for it by typing its name in the search box.
  3. Click the Edit properties icon for the desired place.
  4. Select custom_theme from the drop-down box under Theme header, and then click OK.
Figure 3. Setting the theme on a place
Setting the theme on a place

At this point, you are ready to start applying your customization to the custom_theme.

Enable automatic JSP reloading

To view changes to your theme JSPs without restarting WebSphere Portal, you can force the application server to automatically check for new versions of JSPs. Even though this is ideal for development and testing purposes, you should disable automatic JSP reloading in a production environment. Enabling automatic reloading forces the IBM WebSphere Application Server engine to check the file system for updated files on every page refresh and slows down the overall performance.

Follow these steps to enable automatic JSP reloading:

  1. Open the file was_profile_root/config/cells/cell_name/applications/wps.ear/deployments/wps/wps.war/WEB-INF/ibm-web-ext.xmi.
  2. Find the entry shown in listing 1 in this file.
    Listing 1. ibm-web-ext.xmi file
    <webappext:WebAppExtension xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" 
              xmlns:webappext="webappext.xmi" xmlns:webapplication="webapplication.xmi" 
              xmlns:commonext="commonext.xmi" xmlns:common="common.xmi" 
              xmi:id="IBM_WPS_Ext" reloadInterval="3" reloadingEnabled="false" 
              fileServingEnabled="true" directoryBrowsingEnabled="false" 
              serveServletsByClassnameEnabled="false" preCompileJSPs="false">
  3. Change the value for reloadingEnabled to true.
  4. Save the file.
  5. Restart WebSphere Portal.

Lotus Quickr theme components

This section provides an overview of the Lotus Quickr theme and its artifacts. By convention, WebSphere Portal themes are broken down into four subfolders: colors, icons, images, and js. Each of these folders contains a set of theme files as suggested by the folder name. Essentially, a theme includes four main elements: Java Server Pages, stylesheets, script files, and theme graphics that include image and icon files. The next sections provide details on the content contained in each folder along with brief descriptions of the files they contain.

Theme JSPs

Java Server Pages are text documents that contain static data and dynamic data. Static data can be expressed in any text format; dynamic data is used to construct the dynamic content of the page. Lotus Quickr JSP files are located at the root of the QPG folder located in the WebSphere Portal themes directory at:

was_profile_root/installedApps/cellname/wps.ear/wps.war/themes/html/QPG

The theme is composed of a set of files that consist of a parent JSP file and subsequent fragments of the parent JSP. The fragment JSPs are included from within the parent JSP, and by convention, they are saved with JSPF extensions. For most requests, the portal page is rendered starting with Default.jsp in the themes directory unless the request has been modified by a newWindow="true" parameter. In this case, the page is rendered using Plain.jsp. Figure 4 shows an overview of all the theme files and how they are laid out with respect to the parent file and to each other.

Figure 4. Theme file hierarchy
Theme file hierarchy

Default.jsp is the parent JSP file that includes the JSP fragments (denoted by the JSPF extension) and tag libraries that are needed to render the theme elements. The fragments are compiled into the servlet for Default.jsp. Whenever you make a change to a fragment, resave Default.jsp to force the servlet to recompile. Resaving Default.jsp ensures that the servlet picks up the latest modifications to the fragments.

The head.jspf file is the first fragment included in Default.jsp. This file contains header elements of an HTML page. In the Lotus Quickr theme, all the stylesheets and client-side script files are linked from head.jspf. The page title and text direction are also set in this file. For better performance, link any additional files added to the theme in head.jspf. This approach consolidates all downloads to the beginning of the page and avoids retrieval in the middle of page rendering.

The banner.jspf file, as suggested by its name, displays the page banner shown in figure 5. The banner includes the product logo, search box, and action links to login and logout. It also includes the banner breadcrumb that displays the Back To Home button, a button that lets you expand or compact the screen width, and Lotus Quickr help. Like Default.jsp, the banner also includes fragment files that are compiled in banner.jspf. These fragments are:

  • banner_toolbar.jspf. This fragment renders the toolbar at the top that includes the product logo and search control box and links to login and logout.
  • banner_searchControl. This is a subfragment of banner_toolbar.jspf. It renders the search control box at the right end of the banner toolbar.
  • banner_crumbtrails.jspf. This fragment renders the Back to Home link on a theme page.
  • banner_globalActions.jspf. This fragment contains the code that points to the links to expand and compact the page width and to Lotus Quickr help.
Figure 5. Page banner
Page banner

This section of the theme, contained in pageHeader.jspf and shown in figure 6, displays the application header. In this JSP, you can find the source that retrieves the application name and favorite status. The Customize link that is displayed at the right end of the application header is also rendered in this fragment. The Customize link displays a dynamic palette that is rendered with pageHeaderContent.jspf and shown in figure 7.

Figure 6. Page header
Page header
Figure 7. Customize palette
Customize palette

The pageHeaderContent.jspf file contains the source that renders the customize shelf. The customize shelf provides the ability to add components, members, and new pages or to modify the properties for an existing place.

The topNav.jspf file is a simple and short file that renders the tabbed navigation row that allows users to switch between different components in the same application; see figure 8. The fragment uses different styles to differentiate between the selected and unselected tabs.

Figure 8. Tabbed navigation
Tabbed navigation

The sideNav.jspf file renders subpages created under the top-level navigation node in a place. By default, child nodes to the parent page in a place are displayed in a side-tree navigation. In a later section of this article, we discuss an example to change the default styles to a horizontal navigation style instead.

The footerLarge.jspf file renders the section at the bottom of the page that contains quick links to commonly accessed areas of Lotus Quickr; see figure 9. The links are internal links to portal pages, and they appear in an expanded or a collapsed state.

Figure 9. Footer
Footer

Stylesheets

The layout content is contained in the theme JSP files, but the presentation details of the content are defined in stylesheets. Lotus Quickr stylesheets are located in the same folder with the theme JSP files at:

was_profile_root/installedApps/cellname/wps.ear/wps.war/themes/html/QPG

Similar to the theme JSPs, the stylesheets are broken into several fragments that are included from the parent stylesheet named styles.jsp. Stylesheets are saved as JSP files to accommodate differences in locale and browser support. Similar to default.jsp, the parent stylesheet must be recompiled to pick up the updates to the fragments included in it. Here is a list of stylesheets and a brief description of the contents of each file:

  • styles_cacheSettings.jspf. Used to set the cache headers for all CSS JSPs.
  • styles_extension.jspf. Contains theme extension styles.
  • styles_help.jspf. Contains the styles used to render Lotus Quickr help content.
  • styles_ibm.jspf. Contains styles for the WebSphere Portal administrator portlet page.
  • styles_ibmportlet.jspf. Exclusive to the Lotus Quickr theme, contains styles used by the document library and web content management components in Lotus Quickr.
  • styles_oobQuickr.jspf. Contains styles for the My Places Navigation portlet.
  • styles_people.jspf. Contains styles in the person card.
  • styles_portlet.jspf. Contains the default styles that are shipped with the IBM theme.
  • styles_qpg.jspf. Contains styles for Lotus Quickr administrative portlets only.
  • styles_rules.jspf. Sets browser- and locale-specific CSS rules.
  • styles_theme.jspf. Contains general theme styles that are used in the theme files and fragments.
  • styles_themeSolo.jspf. Is included when the toolbar render is turned off. Adjusts the page elements to display well without the toolbar.

Images

Images are used for icons and tools in the theme pages. These files are placed in the images folder at the root of the theme directory at:

was_profile_root/installedApps/cellname/wps.ear/wps.war/themes/html/QPG/images

When you customize a new theme, you can modify the existing image file or create new ones and place them in the images directory. Image files are spread across various subfolders that are created to keep the image files grouped with respect to various sections of the page.

Color palette

A color palette allows you to set the color scheme of the theme. In WebSphere Portal, the color palette is defined by a property file that contains key value pairs holding references to colors and graphics used in the theme. This is a useful concept that lets users change the color scheme of the theme without making any changes to the stylesheets. You can assign a color palette to an entire theme or to a single page depending upon the design requirements. Refer to the section, "Using color palettes in the theme," in the WebSphere Portal Infomation Center to get details on creating, using, and referencing color themes in WebSphere Portal.

Out of the box, the QPG theme uses the default color palette. The color palette for the Lotus Quickr theme is set in the page metadata inside the head.jspf file. It can be modified to a different color palette by updating the default parameter value shown in listing 2.

Listing 2. Setting/modifying the color palette
<portal-logic:pageMetaData varname="pageMetaData">
  <%-- pageMetadatatag colorPalette: ${pageMetaData.colorPalette} --%>
    <c:set var="colorPalette" scope="request">
      <c:out value="${pageMetaData.colorPalette}" default="custom_palette"/>
    </c:set>
  </portal-logic:pageMetaData>

NOTE: Text is contained in head.jspf. Modified text to update the color palette is highlighted in bold.

The theme expects the page metadata key to be colorPalette and the value to be the color palette identifier (the name of the color palette properties file without the extension).

After the color palette is set, it is loaded into a string and stored in a map request attribute colors for use by the CSS style definitions. The process of loading is done in styles_rules.jspf as shown in listing 3.

Listing 3. Loading of the color palette
java.io.StringBufferInputStream sbis = new
java.io.StringBufferInputStream((String)pageContext.findAttribute
("colorPropertiesStr"));
java.util.Properties colorProperties = new java.util.Properties();
colorProperties.load(sbis);
request.setAttribute("colors", colorProperties);

You can now access the color properties through Expression Language (EL) that uses dot notation to reference map values. The example in listing 4 shows how the color palette properties can be referenced from the CSS.

Listing 4. Referencing color palette properties in a stylesheet
Palette Property:
bodyMarginBackground=url(./colors/qpg/body_background.gif) repeat-x                

Referenced in styles_theme.jspf:
body {
   	font-family: ${requestScope.cssRules.fontFamilySansSerif};
	font-size: ${requestScope.cssRules.bodyFontSize};
	background: ${colors.bodyMarginBackground};
	color: ${colors.bodyText};
	margin: 0px auto;
	padding: 0px;
	width: 100%;
}

Theme policy

A theme policy is an XML file that controls how various parts of the theme are rendered on a page. This design concept allows you to display a single theme in multiple ways. For instance, in Lotus Quickr, the default QPG theme is displayed with slight differences on the Lotus Quickr home page and a Lotus Quickr place page.

Theme policies are an important part of the theme and theme customizations. Lotus Quickr installation is shipped with two policies used to render the Lotus Quickr pages: QuickrMyPlaces and QuickrSpaces.

Lotus Quickr theme policies

The default Lotus Quickr installation comes with ready-to-use theme policies that are contained in the createThemePolicyNode.xml file located at:

portal_server_root/Teamspace/Teamspace/teamspace/work/config/xmlaccess

To set up a new policy, you must create and install it using the XML configuration utility as described in the WebSphere Portal Information Center.

After you have installed a policy in WebSphere Portal, it can be set on a page by accessing Page properties under Manage Pages in Portal Site Administration. To do this, follow these steps (see figure 10):

  1. Search for the desired page under Manage Pages, for example, Home.
  2. Click the Edit page properties icon for the page that has the unique ID ibm.qp.Home. This is the first page that you see when you log into Lotus Quickr.
    Figure 10. Setting theme policy on a place
    Setting theme policy on a place
  3. The desired policy can be selected from the drop-down box under Navigation Type on this page as shown in figure 10.

As mentioned at the beginning of this section, in Lotus Quickr you use two main theme policies, one to render the theme for Lotus Quickr Home page and the other to render Lotus Quickr team place's pages. While the Lotus Quickr Home page is set to QuickrMyPlaces, Lotus Quickr place pages use QuickrSpaces. The same theme renders two different views on the home page and on a place page. Figure 11 and 12 show the two screens.

Figure 11. Lotus Quickr Home Page
Lotus Quickr Home Page
Figure 12. A Lotus Quick place
Lotus Quick out-of-box place

Tables 1 and 2 list the policy attributes and their values for the two Lotus Quickr theme policies.

Table 1. Lotus Quickr policy attributes and values for QuickrMyPlaces
AttributeType
renderMainMenufalse
renderTopNavigationtrue
renderMainMenuActionsfalse
renderSelfCaretrue
renderBreadCrumbTrailtrue
renderSearchtrue
renderToolBartrue
renderUserActionstrue
renderContentPalettefalse
renderPeoplePalettefalse
renderContextMenusfalse
renderSideNavigationfalse
renderTaskBar true
renderFavoritestrue
renderExtensionstrue
renderBannerTitleGraphic false
renderBannerTitlefalse
renderPageHeaderfalse
renderPageHeaderActionsfalse
renderPortletFragmentIDAnchortrue
rootNavigationStartLevel1
rootNavigationStopLevel1
topNavigationNumRows1
topNavigationStartLevel3
topNavigationStopLevel 3
Table 2. Lotus Quickr policy attributes and values for QuickrSpaces
AttributeType
renderMainMenufalse
renderTopNavigationtrue
renderMainMenuActionsfalse
renderSelfCaretrue
renderBreadCrumbTrailtrue
breadCrumbMaxLevels5
breadCrumbStartLevel0
renderSearchtrue
renderToolBartrue
renderUserActionstrue
renderContentPalettetrue
renderPeoplePalette false
renderContextMenusfalse
renderSideNavigationtrue
renderTaskBar true
renderFavoritestrue
renderExtensionstrue
renderBannerTitleGraphicfalse
renderBannerTitlefalse
renderPageHeadertrue
renderPageHeaderActionstrue
renderPortletFragmentIDAnchortrue
rootNavigationStartLevel1
rootNavigationStopLevel4
topNavigationNumRows
topNavigationStartLevel3
topNavigationStopLevel3

Accessing policy attributes

With the policy setup taken care of, make sure that the theme contains the code snippet shown in listing 5 to load the policy map into a bean that can then be accessed anywhere in the theme.

Listing 5. Loading a theme policy in the theme
<portal-theme-ext:initthemepolicy/>
<jsp:useBean id="themePolicy" 
class="com.ibm.portal.theme.policy.ThemePolicyBean" scope="page"/> 
<%
	themePolicy.setValuesMap(portalThemePolicyMap);
%>

To create new policies or to modify existing policies, you must have a good understanding of theme policies. A policy file is an XML file that contains multiple attributes to define a single policy. Each attribute is like a policy property that is evaluated at the time of theme render. An example of a policy value (attribute) is shown in listing 6.

Listing 6. Example policy value
<policyValue
      Name="renderSideNavigation"
      Factory="com.ibm.wps.policy.parse.BooleanFactory">
      <value>true</value>
</policyValue>

In this example, the policy defines an attribute renderSideNavigation and sets the attribute value to true. This value is evaluated in the theme with a check similar to the example shown here:

c-rt:if test = "${themePolicy.renderSideNavigation}">
<%@ include file="./sideNav.jspf" %>
</c-rt:if>

More examples of theme policy nodes and their application can be found in individual JSPs in the Quickr theme.


Customize the theme

The next sections cover examples of common theme customization. This article uses the Greener Autos site as an example of different themes and component customization. The Greener Autos team place is used as a collaboration tool by an auto company to communicate and share content.

As discussed previously, the theme is broken into fragments that are compiled through a parent JSP file to put together the theme. The main theme fragments are:

  • Theme banner
  • Banner breadcrumb
  • Page header
  • Top navigation row
  • Page area (portlet render area)
  • Page footer

The layout of these pieces is shown in figure 13.

Figure 13. Lotus Quickr theme layout
Lotus Quickr theme layout

The first steps you take when updating the theme to a custom environment require updating the default Lotus Quickr icons with custom product icons that are tailored to the design of your place. Multiple themes can coexist on a single Lotus Quickr server and can then be assigned to multiple places as desired. Before beginning this section, you must complete the steps listed in the "Create a custom theme" section to create and set a custom_theme on a team place. You are now ready to apply changes to your custom_theme and to view how it affects the theme on your server.

Page background

Updating the page background image is the first step in modifying the Lotus Quickr theme to a customized look and feel. You can do this easily using the color palettes. The color palette used by Lotus Quickr is default.properties.

To update your theme background, follow these steps:

  1. Open default.properties located at custom_theme/colors.
  2. Find property bodyMarginBackground = url(./colors/qpg/body_background.gif).
  3. Update this property to point to your custom background image:
    bodyMarginBackground = url(./colors/ custom/pagebg.gif)
  4. Next, resave styles_rules.jspf, styles.jsp, and Default.jsp. This step updates the timestamps on all the files and forces the theme to recompile the files and to read the color palette into the theme again. After these changes occur, the page background is updated to look similar to the one shown in figure 14.
Figure 14. After page background is updated
After page background is updated

Theme banner

The next step is to update the logos and icons in the theme with custom icons designed for the custom team place. You can start with the Lotus Quickr banner, which consists of a banner background image and a banner logo. Follow the steps listed here to tailor the banner to your custom environment.

Figure 15 displays the banner logo highlighted in pink. You can update this to a custom logo by making modifications in the banner_toolbar.jspf file that is located in /custom_theme.

Figure 15. Banner logo
Banner logo
  1. Find the text shown in listing 7.
    Listing 7. Banner title <div> element
    <div class="bannerTitle">
    	<img alt="Lotus Quickr" title="Lotus Quickr" src='<portal-logic:urlFindInTheme 
    	file="colors/${colorPalette}/toolbar_logo.gif"/>' /> 	
     </div>
  2. Update the file path parameter value to point to your custom logo file="colors/custom/logo.gif" where logo.gif is the name of your custom logo icon.
  3. The banner is updated to look like the image shown in figure 16.
    Figure 16. The Greener Autos banner
    The Greener Autos banner

The banner font properties, font styles, and font color can be modified in the color palette.

  1. In the color palette, find the text properties used to set the text color in the banner.
  2. Update these to #295500 (green) from black. Find other occurrences of text color in the file and replace them with the same color code as well. This updates the following properties to the ones shown in listing 8.
    Listing 8. Banner color palette properties
    toolbarText=#295500
    bannerText=#295500
    userActionsButtonText=#295500

The search icon is contained in the banner_searchControl.jspf file. Find the code below and update the path to the custom search icon.

String ic = (bidiImageRTL == null) ? "icons/custom/Go.gif" :
"icons/custom/Go "+bidiImageRTL+".gif";

The banner background can be updated from the color palette without modifying the theme.

  1. In the color palette, find the property:
    toolbarBackground=#FFDB4A url(./colors/qpg/toolbar_background.gif) repeat-x
  2. Update the property value to:
    toolbarBackground=#FFFFFF This updates the color of the original yellow background to white. You can distinguish the toolbar section from the rest of the page by adding a background image to the toolbar section.
  3. Find this property in the color palette:
    bannerBackgroundImage=none
  4. Update the parameter value to:
    bannerBackgroundImage=url(./colors/custom/topbanner3.gif)
  5. You should now see a banner that looks like this one in figure 17.
    Figure 17. Updated banner for Greener Autos
    Updated banner for Greener Autos

You can leave the banner like this, or you can add an opacity parameter to the banner background to partially see the page background through the banner. Here's an example that shows how to do this:

  1. In the styles_theme.jspf file located at /custom_root, find the .banner and .toolbar classes. Update these classes as shown in listings 9 and 10.
    Listing 9. Banner style definition
    .banner {
    	color: ${colors.bannerText};
    	background: ${colors.bannerBackgroundImage};
    	background-color: ${colors.bannerBackground};
    	margin: 10px 0px 0px;
    	padding: 0px;
    }

    Listing 10. Toolbar style definition
    .toolbar {
        color: ${colors.toolbarText};
        background:${colors.toolbarBackground};
        margin-${requestScope.cssRules.bidiRight}: 0px;
        border-bottom: 1px solid ${colors.toolbarBorder};
        border-left: 1px solid ${colors.toolbarBorder};
        border-right: 1px solid ${colors.toolbarBorder};
        -moz-border-radius-bottomright: 4px;
        -moz-border-radius-bottomleft: 4px;
        opacity:0.87;
    }
  2. The banner should now look like the one shown in figure 18.
    Figure 18. Updated banner
    Updated banner
    The toolbar shadow appearing at the bottom of the toolbar looks inconsistent with the new color scheme of the page. This can be updated with a custom image, or you can remove it from the banner altogether. In this example, we remove the toolbar shadow.
  3. Delete the following text from banner_toolbar.jspf:
    <div class="toolbarShadow"><!-- IE hack --></div> NOTE: The comment text <! - - IE hack - - > is inserted to fix a problem in Microsoft Internet Explorer. Inserting the comment text prevents hiding styles that are displayed by empty <div> tags.
  4. The banner should be updated to look like the one shown in figure 19.
    Figure 19. Updated banner
    Updated banner

After you update the banner background and the banner image, you should update the links in the banner breadcrumb to make these consistent with the custom theme. These links are distributed across two JSP fragments: banner_crumbtrails.jspf and banner_globalActions.jspf. First, find the right text to update the Back to Home button image to an appropriate color for this theme.

  1. Update the section in styles_theme.jspf like shown in listing 11. This updates the background image used for the Back to Home link.
    Listing 11. The returnHome style definition
    a.returnHome{
    	background: #295500 
    	url(images/quickr/returnHome_green_${requestScope.cssRules.bidiLeft}.gif) 
    	center ${requestScope.cssRules.bidiLeft} no-repeat;
    	border: 1px solid ${colors.breadcrumbBorder};
    	padding: 1px 15px !important;
    	display: block;
    }
  2. Next, update the color scheme for the breadcrumb in the color palette as well. This can be done by updating the properties as shown here:
    breadcrumbText=#295500
    breadcrumbBorder=#295500

Finally, update the icons and color scheme for the text appearing in the banner global actions. The global action section contains the expand/compact icon and a link to Lotus Quickr help at the bottom right of the banner. They can be updated in the banner_globalActions.jspf and the color palette.

In your custom environment, you can remove the JSP fragment altogether or remove sections that render each link if you do not need them. For instance, if you want to remove the expand/compact link, you can delete the code shown in listing 12 from the banner_globalActions.jspf file.

Listing 12. Expand/collapse link from breadcrumb
<% if(user!=null) {%>
	<a tabIndex="8" href='#' id="widthPage" class="globalActionLink" 
	onClick="changeWidth("<%= user %>", "fluid"); 
	return false;"><img src="<portal-logic:urlFindInTheme 
	file='images/quickr/set100.gif'/>" style="width: 18px; height: 18px;" 
	alt=<portal-fmt:text key="fluidWidth" bundle="nls.quickr"/> 
	title=<portal-fmt:text key="fluidWidth" bundle="nls.quickr"/> /></a>
	<a style="display:none;" tabIndex="6" href='#' id="widthPageFixed" 
	class="globalActionLink" onClick="changeWidth("<%= 
	user %>", "fixed"); return false;"><
	img src="<portal-logic:urlFindInTheme file='images/quickr/setfixed.gif'/>" 
	style="width: 18px; height: 18px;" alt=<portal-fmt:text key="fixedWidth" 
	bundle="nls.quickr"/> title=<portal-fmt:text key="fixedWidth" 
	bundle="nls.quickr"/> /></a>
	<% } %>

You can also change the color of the Help link by modifying the color palette (see figure 20)

globalActionText=#295500

Figure 20. Update Back To Home link
Update Back To Home link

To be consistent with the theme scheme, the Help text can also be replaced with a button similar to the Back to Home link. The Help link is rendered from banner_globalActions.jspf. In this file, find the text shown in listing 13.

Listing 13. Intial Help button code
<%-- Help --%>
	<% 
		String user = request.getRemoteUser();
	%>	
	<a tabIndex="9" href='javascript:void(0);' class="" 
	onClick="showHelpWindow('com.ibm.qpp.places.help/ts/h_ts_places_welcome.html', 
	'<%=preferred%>'); return false;">
	<img class="breadCrumbImage" border="1" 
	src="<portal-logic:urlFindInTheme file='images/custom/help.gif'/>" 
	alt=<portal-fmt:text key='link.help' bundle='nls.engine'/> />
	</a>

Modify this code to insert an image background for the Help link as shown in listing 14.

Listing 14. Updated Help button code
<%-- Help --%>
	<% 
		String user = request.getRemoteUser();
	%>	
	<a tabIndex="9" href='javascript:void(0);' class="globalActionLink" 
	onClick="showHelpWindow('com.ibm.qpp.places.help/ts/h_ts_places_welcome.html', 
	'<%=preferred%>'); return false;">
	<img border="0" src="<portal-logic:urlFindInTheme file='images/custom/help.gif'/>"
	 alt=<portal-fmt:text key='link.help' bundle='nls.engine'/> />
	<portal-fmt:text key='link.help' bundle='nls.engine'/>
	</a>

To align the button correctly, you may also remove the margin property:

margin-${requestScope.cssRules.bidiRight}: 5px;

from the style in styles_theme.jspf as shown in listing 15.

Listing 15. globalActions style definition
.globalActions {
    float:${requestScope.cssRules.bidiRight};
    color: ${colors.globalActionText};
    background:${colors.globalActionsBackground};
    margin-${requestScope.cssRules.bidiRight}: 5px;
    padding: 0 5px;
}

After you save these changes, the theme banner should look like the one shown in figure 21.

Figure 21. Updated Help link
Figure 21. Updated Help link

This completes the modifications to the Lotus Quickr banner.

Theme footer

Figure 22 shows the default footer shown in the Lotus Quickr theme. This footer can be collapsed into a minimal version that includes only the more commonly used links. For footer customizations, you may choose the collapsed footer state as the default state, modify links in the footer, modify or remove the IBM logo from the footer, or even remove the footer altogether.

Figure 22. Footer
Figure 22. Footer

You can easily update the IBM logo displayed in the footer. The entire footer is rendered using footerLarge.jspf. Within this fragment, find the image tag that is currently pointing to the IBM logo (footerIBM.gif). You can update the location of the existing logo to point to a custom logo as follows:

<img class="ibm" src="<portal-logic:urlFindInTheme
file='images/custom/footerCustom.gif'/>" alt="IBM">

As described previously, the default is displayed in its expanded state, which includes all the necessary footer links. To save page real estate, you can collapse the footer to look like the one shown in figure 23.

Figure 23. Collapsed footer
Collapsed footer

This can be modified to make the collapsed state the default footer state by making a few changes in the footerLarge.jspf file. This JSP uses a CSS property that sets the display style to none to toggle between the two states. The property is set to hide the expand link and the <div> tag that displays the collapsed state. The code in listing 16 shows the code snippet that renders the Expand and Collapse links in the footer. Add the code shown in bold, and delete this code:

style="display: none;"

shown in italics in listing 16. These modifications are needed to switch the default footer state.

Listing 16. Modify footer state
<% if(usernameID!=null){ %>
	<a id="footerLinkIDCollapse" style=”display: none;” class="footerLink" href="#" 
	onclick="expandFooter(); changeFooter("<%=usernameID%>
	"); return false;"><portal-fmt:text key="footer.collapse" 
	bundle="nls.quickr"/></a>
	<a id="footerLinkIDExpand" style="display: none;" class="footerLink" href="#" 
	onclick="expandFooter(); changeFooter("<%=usernameID%>"); 
	return false;"><portal-fmt:text key="footer.expand" 
	bundle="nls.quickr"/></a>
	<% } %>

Similar changes are also required for the <div> tags that contain the links for the expanded and the collapsed state. By default, the footerSmall <div> that wraps the links for collapsed state is hidden and the footerMain <div> that contains the expanded state of links is visible. This can be modified like this below:

<div id="footerSmall" style="display: none;">

Add the text in bold:

<div id="footerMain" style="display: none;">

With these changes, you should now see the collapsed footer upon page refresh.

In some instances, the design requirements may specify that you remove the footer from the theme completely. You can do this easily by simply removing the include statement for the footerLarge fragment. In the default.jsp, find and remove this code:

<portal-logic:if portletSolo="no"> <!-- <%@ include file="./footerLarge.jspf" %> --> </portal-logic:if>

Page area

The following section provides guidance on updating the page area in the Lotus Quickr theme. As indicated by the name, the page area in the theme is wrapped in a <div> tag with the ID value pageArea. This <div> tag acts as a wrapper for the page header, the top navigation, portlet render area, and the page footer.

Figure 24 shows the page area of the theme and highlights pieces that are put together to render the page area.

Figure 24. Page area view
Page area view

The first step is to customize the pageArea wrapper itself. The wrapper controls the display for the pageArea border as well as the background. This style can be modified in the styles_theme.jspf file as follows.

  1. Find the pageArea ID in the CSS styles file, and modify it to look like listing 17.
    Listing 17. pageArea style definition
    #pageArea {
        background-color: ${colors.bodyBackground};
        border: 2px solid ${colors.bodyBorder}; // #295500
        padding: 10px;
        -moz-border-radius: 4px;
    }
  2. You may modify the property value for bodyBorder in the color palette to be consistent with the remaining theme as well. You can do this by updating the property:
    bodyBorder=#295500

This change adds a green border around the page area to produce a screen looking like the one shown in figure 25.

Figure 25. Page area after border style updates
Page area after border style updates

The page header, shown in figure 26, is the first section rendered within the page area. This space is used to display the application title, the application favorite status, and the Customize link that allows users to control access to the place and add pages or components to a place. Common customizations to this section include updating the background image, font styles, and header dimensions.

Figure 26. Page header
Page header

Here are a few examples of different customizations for the page header.

  • The background gradient for the header is a property that can be updated in the color palette by updating the property value as follows:
    customizeBackground=#EEEEEE
  • The font properties can be updated in the color palette as well. Find the pageHeader property in the color palette, and update that to the default font color for your custom theme.
    pageHeader=#295500
  • Similarly, the text color for the Customize link can also be updated from the color palette. This property value can be update as follows:
    customizeLink=#295500

After these changes are made, the page header now looks similar to the one shown in figure 27.

Figure 27. Page header after updates
Updated styles in page header

Figure 28 shows the top navigation row that contains all the pages for a team place. The section of the theme has scope for some advanced customizations. Let's walk through the common customizations: updating navigation background, font properties, and more.

Figure 28. Top navigation
Top navigation

First, modify the styles to make the top navigation row consistent with your remaining theme. To do this, add a background color to the parent <div> tag of the navigation row like this:

.topnav{
background-color: ${colors.customizeBackground};
}

To update the styles for the row boundary, remove the line:

background: #EEEEEE bottom left repeat-x;

from the code shown in listing 18.

Listing 18. wpsPageBarFirstRow style definition
.wpsPageBarFirstRow{
	margin:0px;
	clear: both;
	white-space: nowrap;
	float:${requestScope.cssRules.bidiLeft};
	*float: none;
	padding-${requestScope.cssRules.bidiLeft}: 0px;  
	<%--browsers default to either left margin or padding of 
	40px for li indention --%>
	background: #EEEEEE bottom left repeat-x;
	width: 99%;
	font-family: ${requestScope.cssRules.fontFamilySansSerifLarge};
	font-size: ${requestScope.cssRules.fontSize.normal};
	font-weight: bold;
}

The font properties also need to be updated in the color palette. Update the following properties:

tabsTextSelected=#f6931c
topNavFirstRowUnSelectedText=#999

At this point, search all other occurrences of color property value #999 and update them to custom_theme font color #295500 as shown in listing 19. This change takes care of other instances where the color code needs to be updated in the theme.

Listing 19. Top navigation style properties
topNavRowUnSelectedText=#295500
topNavFirstRowText=#295500
launchButtonText=#295500
menuPortletseparator=#295500

After you make these changes, the top section of the page header should look like the one shown in figure 29.

Figure 29. Top navigation after updated styles
Top navigation after updated styles

The customization examples so far have focused on updating icons and changing logos, style properties, and CSS to provide a consistent and professional design to any custom theme. The next section demonstrates how to change the navigation styles in the theme by modifying a few styles and making some changes to the theme JSP files.

In the previous section, we discussed the top navigation level. If desired, the theme allows an additional navigation level below the parent page for each place tab. You can add these child pages from the Customize shelf that provides access to the page properties.

  1. Click the Customize link in the page header.
  2. Go to the Pages tab, and click Advanced Layout.
  3. Click the New Page button to add a new page. You can name this page Test Page.
  4. Click Done and notice that a new page has been added to your team place in the top navigation row.
  5. Next, follow steps 1 and 2 to get to Manage Pages. Select the new added Test Page to add child pages under this page.
  6. Add two new pages, Page 1 and Page 2, on Test Page.

At this point, your team place looks like the one shown in figure 30.

Figure 30. Page area after updated styles
Page area after updated styles

The subpages added on Test Page appear in tree-style side navigation. The following example provides steps to change the side navigation into a horizontal navigational style.

NOTE: The changes listed here can cause JSP errors in the theme if they are not made correctly. Make backup copies of the latest version of your modified files before you edit them.

In your copy of Default.jsp, find the table with the ID value portletRenderWidth, and then modify the table with changes listed in red in listing 20. These changes insert a new row in the table that can be accessed with CSS to display a horizontal navigation instead of the default vertical one.

Listing 20. HTML to render the navigation row
<table style="width:100%; height:100%;" cellpadding="0px" 
cellspacing="0px" id="portletRenderWidth">
   <tr>
   <% if(nodeSel == null ) {%>
    <td  width="100%" height="100%" valign="top">
   <%}else{ %> 
    <td valign="top">
    <%}%>
  <portal-logic:if portletSolo="no">
	<%@ include file="./sideNav.jspf" %>
  </portal-logic:if>
    </td>
    <% if(nodeSel == null ) {%>
   </tr>
   <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">
  <%  if (nodeSel != null){
   if(nodeSel.equals("wps.Login")){ %>
        <portal-logic:if portletSolo="no">
          <%@ include file="./login.jspf" %>
        </portal-logic:if>
   <% } } %>
	<portal-core:screenRender/>
  </div>
    </td>
  </tr>
  </table>

The sideNav.jspf file includes the logic that reads in the child elements of the page and renders them on the screen. To update the navigation styles, create new style definitions that render a horizontal menu bar, and then add these classes to the existing HTML elements in the side navigation. The example in listing 21 shows how to create new style definitions. These style definitions are copied from the existing Side Navigation styles (CSS class wpsSideNav). Then, modify the default styles to display a horizontal menu instead.

Listing 21. Style definition for Horizontal menu
<%--===================================================
    Page Horizontal Navigation
====================================================--%>
.wpsHorizontalNav{
    background: #F0F0F0 url(./images/portlet/tableBg.gif) repeat-x scroll left top;
	margin:0px;
	clear: both;
	white-space: nowrap;
	float:${requestScope.cssRules.bidiLeft};
	width: 99%;
	padding-left: 0px;
	font-size: ${requestScope.cssRules.fontSize.normal};
	border: 1px solid;
	border-color: ${colors.sideNavBorder};
	text-decoration: none;
	
}
.wpsHorizontalNav li{
	font-family: ${requestScope.cssRules.fontFamilySansSerifLarge};
	float:${requestScope.cssRules.bidiLeft};
	display:inline;
	list-style: none;
	margin-${requestScope.cssRules.bidiLeft}: 0px;
	padding: 4px 12px 6px 0px;
    /** padding-${requestScope.cssRules.bidiLeft}: 0px; **/
}

/* for Selected node in the first sub-layer i.e. the second layer */
.wpsHorizontalNav .selectedElem{
    background-color: #FFFFFF;
}

/* first sublist is not indented */
.wpsHorizontalNav ul{
    margin-${requestScope.cssRules.bidiLeft}: 1.5em;
    padding-${requestScope.cssRules.bidiLeft}: 0px;
}
/* indent sublists nested 2 levels or deeper  */
.wpsHorizontalNav ul ul{
    margin-${requestScope.cssRules.bidiLeft}: 1.5em;
    padding-${requestScope.cssRules.bidiLeft}: 0px;
}

.wpsHorizontalNav .wpsNavItem{
	text-decoration: none;
	display:block;
	white-space:nowrap;
	color:${colors.sideNavText} !important;
}

.wpsHorizontalNav .wpsNavItem a {
	display: inline;
}

.wpsHorizontalNav .wpsNavItem a:hover {
	text-decoration: underline;
}

.wpsHorizontalNav .selected{
	/* color: ${colors.sideNavSelectedText} !important; 
	background:#FFFFFF none repeat scroll 0%;   */
	text-decoration: none;
	/*padding:3px 3px; */
	display:block;
	cursor:default;
	white-space:nowrap;
}
display: inline;
	cursor: pointer;
	text-decoration: none;
}

.wpsHorizontalNav .selected a:hover{
	color:  #666666 !important;
	text-decoration: none !important;
}

.wpsHorizontalNav .wpsNavIcon{
    height: 9px;
    width: 9px;
    border: 0px;
    padding: 0px;
    margin: 0px;
    vertical-align: baseline;
}


.wpsHorizontalNav .menuLinkSideNav {
    border: 0px;
    margin-${requestScope.cssRules.bidiLeft}: -10px;
    padding: 0px 10px;
}

.wpsHorizontalNav .wpsNavLevel1{
	color:  #999999 !important;
	font-size: ${requestScope.cssRules.fontSize.bold};
	padding-top: 3px;
}

.wpsHorizontalNav .selected .wpsNavLevel1{
	color:  colors.sideNavTopLevelSelectedText !important;
}


.wpsHorizontalNav .wpsNavLevel2 wpsNavLevel3 wpsNavLevel4 wpsNavLevel5 
wpsNavLevel6 wpsNavLevel7 wpsNavLevel7{
	text-indent:36px;
}

The last step is to update the HTML elements in sideNav.jspf to use the new style definitions. These updates to the side navigation are shown in listing 22 in bold.

Listing 22. HTML elements for side navigation
<ul <% if(previousNavLevel==0 && nodeSel == null){%>
 class="wpsHorizontalNav"<%} else{%> class="wpsSideNav" 
<%}%> >
<li <%if (isNodeSelected) { %> class="selectedElem" 
id="portalSelectedNode" onmouseover="showSidePageAffordance(); return false;" 
onmouseout="hidePageAffordance(); return false;" <% } %> >

<c-rt:when test="<%=nodeSel!=null && nodeHasChildren && 
isExpanded%>">
	<a href='<portal-navigation:navigationUrl type="collapse"/>'>
	<img alt="<portal-fmt:text key='link.collapse' bundle='nls.engine'/>" 
	title="<portal-fmt:text key='link.collapse' bundle='nls.engine'/>" 
	class="wpsNavIcon" src="<portal-logic:urlFindInTheme 
	file='images/sideNav/minus.gif' />"></a>
</c-rt:when>

Now, make one last tweak to the color palette:

sideNavTopLevelSelectedText=#295500

The final result is shown in figure 31.

Figure 31. Updated view of the place
Updated look of the place

Lotus Quickr skin

Skins represent the wrapper that goes around the components. They are made of row containers, column containers, and controls. The containers act as a wrapper for the inside portlet application, and the control section renders portlet controls.

By default, Lotus Quickr uses QuickrSkin, which was designed specifically to work with Lotus Quickr themes and pages. In the "Getting Started" section of this article, we created a custom_skin from the default Lotus Quickr skin. This skin directory contains three main JSP files:

  • UnlayeredContainer-H. This is the row container.
  • UnlayeredContainer-V. This is the column container.
  • Control.jsp. This renders the controls for the portlet application.

Translation files

The language bundles for Lotus Quickr theme are located at:

portal_server_root\shared\app\nls

They follow the naming pattern quickr_[language].properties. To add new strings to the theme, you may add new resource bundles into the same directory. More details on adding resource bundles can be found in the WebSphere Portal Information Center.


Conclusion

This article summarizes common customizations to the Lotus Quickr theme for WebSphere Portal. It describes how to create a new theme and skin and how to apply it to a place. It also talks about the theme components and the role that each component plays in the theme. Finally, the article went over individual theme sections and provided examples of common customizations to modify the theme.


Download

DescriptionNameSize
Code samplegreenautostheme.zip13780KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=282020
ArticleTitle=Customizing themes in IBM Lotus Quickr services for IBM WebSphere Portal V8.0
publish-date=01152008