Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Prerequisites

You should have a good understanding of basic HTML, JavaServer™ Pages (JSP), cascading stylesheets (CSS), and JavaScript™. Lotus Quickr 8.5, built on Websphere Portal V6.1.5, offers themes as an extension to the existing portal page builder theme. To get the full benefit from this article, you must also be familiar with the page builder theme for IBM WebSphere Porta V6.1.5. See the WebSphere Portal Information Center 6.1.5 for information about portal theme customizations.

Back to top

Getting started

A theme is composed of a set of files that consist of a parent JSP file (Default.jsp) 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. In addition to the theme JSPs, the theme also consists of image files (theme graphics), stylesheets, JavaScript files, and Dojo widgets. The next sections provide details on theme layout and how to make changes to various elements of the theme.

Theme layout

As described in the previous section, the theme is broken into fragments that are compiled through a parent JSP file to put together the theme. The main theme fragments are

• Global navigation
• Title bar
• Place bar
• Side navigation
• Portlet render area
• Footer

The layout of these pieces is shown in figure 1.

To keep the theme simple, there is one JSP or JSP fragment for each section in the layout. For instance, globalNav.jsp is created to render the global navigation. Similarly, topNav.jspf and sideNav.jspf are created to render the titlebar and side navigation, respectively. Figure 2 shows a simplified structure of theme JSPs.

Back to top

Theme customization

Theme customization can range from simple stylesheet changes that add a new color scheme to the page to advanced changes that modify existing elements of the theme and make changes that require integration of custom applications and components. The following sections discuss the basic mechanism of theme customization and cover advanced scenarios of making changes to theme layout and new component integration.

Create a custom theme

Default themes and skins, which are ready to use in the product, are deployed in an EAR file named QuickrThemeApp.ear. To make these changes, you must have administrative access to the server. To create a custom theme or skin, copy QuickrThemeApp.ear to a temporary location and modify it. Your new theme is packaged and deployed as a new EAR file.

Important: Create a custom theme before making changes to the theme. The original Lotus Quickr theme can get redeployed when applying interim fixes to the theme or adding fix packs in general.

The following steps provide details on creating a theme EAR file.

1. Copy the default theme file wp_profile/installableApps/QuickrThemeApp.ear to a temporary location.
2. Unpack the QuickrThemeApp.ear file.
3. Modify the QuickrThemeApp.ear/META-INF/application.xml file to add a unique display name, module ID, and context root.
4. Rebuild the EAR file. The new EAR file must have a different name than the original QuickrThemeApp.ear file.
5. Deploy the new EAR file by copying it back onto the server. See Deploying the theme in the WebSphere Portal 6.1.5 Information Center.
6. Register the new theme and skin. See the sample xmlaccess script shown in listing 1 to import the custom theme.

NOTE: Within the script, you must supply a unique context root (provided in step 3) that identifies this custom theme application.

<?xml version="1.0" encoding="UTF-8"?>
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="PortalConfig_6.1.0.xsd" 
type="update" create-oids="true">
    <portal action="locate">
        
        <skin action="update" active="true" default="false" domain="rel" 
        objectid="ibm.portal.skin.qkr_custom" uniquename="ibm.portal.skin.qkr_custom" 
        resourceroot="QkrSkin" context-root="/QuickrTheme_custom" type="default">
            <localedata locale="en">
                <title>QkrSkin_custom</title>
            </localedata>
        </skin>
        <skin action="update" active="true" default="false" 
        domain="rel" objectid="ibm.portal.skin.qkrthin_custom" 
        uniquename="ibm.portal.skin.qkrthin_custom" resourceroot="QkrThinSkin" 
        context-root="/QuickrTheme_custom" type="default">
            <localedata locale="en">
                <title>QkrThinSkin_custom</title>
            </localedata>
        </skin>
        <theme action="update" active="true" 
        context-root="/QuickrTheme_custom" default="false" 
        defaultskinref="ibm.portal.skin.qkr_custom" domain="rel" 
        objectid="ibm.portal.theme.qkrtheme_custom" resourceroot="Quickr" 
        uniquename="ibm.portal.theme.qkrtheme_custom">
            <localedata locale="en">
                <title>QkrTheme_custom</title>
            </localedata>
            <allowed-skin skin="ibm.portal.skin.qkr_custom" 
            update="set"/>
            <allowed-skin skin="ibm.portal.skin.qkrthin_custom" 
            update="set"/>
        </theme>       
        		
    </portal>
</request>

For more details, see Importing a theme in the WebSphere Portal 6.1.5 Information Center.

You see your custom theme and skin listed under Home – Advanced Administration – Portal User Interface – Themes and Skins.

For initial development, create a test page or place and apply the custom theme to it. The theme can be assigned to a place using Place Actions – Edit Place. After the theme is modified and unit tested, update the default theme of the server to your custom theme. This task can be done on the themes and skins page under advanced administration. Unless an existing place is set to use a theme other than the default, all the places are automatically updated to use the custom (default) theme.

Modify theme files

As mentioned in the previous section, the theme is composed of a set of JSPs and stylesheets that define the presentation semantics of the theme. In Lotus Quickr 8.5, the theme stylesheets are shared across several components including the theme, places catalog, and individual Lotus Quickr components such as blog, library, and so on. There are also some parts of the layout, for instance the footer, that are also common among Lotus Quickr teamplaces, places catalog, and places administration. For simplicity, all of these resources have been bundled separately under a common resources application. The location of both the theme application and common resources application is listed below.

Theme:

Common resources:

In the rest of this article, we refer to the above theme location as the theme_root directory and the common resources application location as the common_resources_root directory.

Important: Create and deploy a custom common resources EAR file. Follow the steps in the section "Create a custom theme” to do this task.

Adding stylesheets

Lotus Quickr 8.5 contains a set of ready-to-use stylesheets. These stylesheets can be selected and applied from the Lotus Quickr custom palette. Figure 3 shows the available stylesheets and sample color schemes applied to a teamplace.

If none of the ready-to-use stylesheets provides the color scheme that you are looking for, you can make new stylesheets, add them to the custom palette, and selectively apply them to places. Alternatively, you can also modify the default stylesheet (in the common resources application) to update the color scheme for all places and for the Lotus Quickr home page.

Creating custom stylesheets

Creating stylesheets is quick and simple. With only a couple of colors used in the theme, new stylesheets can be created from existing ones by replacing existing color codes with ones that match your new color scheme. The primary colors to update in a stylesheet are these:

• Body background
• Text, button text, titles, both selected and unselected
• Button background colors
• Side navigation, including background and border

The colors for the preceding elements are used in several style classes to achieve the overall color scheme of the theme. After identifying new color codes for each of these elements, the existing color code can be replaced with the new ones at every occurrence in the stylesheet.

The following steps describe how to create stylesheets and add them to customize the palette.

1. Open the QuickrCommonResourcesApp.ear file in
   
   custom_common_resources_root \css

   There is a list of folders (greyTheme, purpleTheme, and so on), each associated with a style listed on the customize palette. Each folder contains a stylesheet that defines the color scheme and a set of images to match the color scheme.

2. Define your custom stylesheet by copying an existing style folder. for example, greyTheme. Rename this folder to <yourCustomTheme>. Also rename the stylesheet to <yourCustomTheme>.css.
3. Update the custom CSS file to include your company’s theme colors. Save the changes.

   Next, you need to make your custom stylesheet available on the custom palette.

4. Open and edit the custom_theme_root\system\styles.json file.

   The JSON file contains entries for each stylesheet listed on the customize palette. To add an entry for the custom stylesheet, copy an existing entry and edit the ID to point to the path of your custom sheet. Here is an example of a new entry:

   {'label':'<newLabel>','id':'<yourCustomTheme>/<yourCustomTheme>
.css','thumbnail':ibmPortalConfig.themeRootURI+'/images/changeStyle/
<yourCustomTheme>.gif','help':''}

NOTE: Any errors in this file can prevent you from loading the custom palette on the server. If this problem is the case, check the file for missing commas, open braces, or any other syntax errors.

After completing the steps, you can see your custom stylesheet available on the shelf. Figure 4 shows the custom sheet.

Updating styles for the places catalog

The landing page upon login (the places catalog) displays the list of all available places. The styles for this page are set using a JSP stored in the common resources application. The following steps show how to apply your custom stylesheet to the places catalog page.

1. Copy the custom_common_resources_root\defaultTheme\commonstyles.jsp file to the custom_common_resources_root \<yourCustomTheme> folder.
2. Open the custom_common_resources_root \<yourCustomTheme>\commonStyles.jsp file and replace the defaultTheme.css file with the <yourCustomTheme>.css file.
3. Finally, edit the JSPs listed by replacing lines of text text as shown here:
   
   

   JSP to replace:

   1. wp_profile/installedApps/qkr/placeCntrApp.ear/placeCntrAppUI.war/WEB-INF/jsp/catalog.jsp
   2. wp_profile/installedApps/qkr/placeCntrApp.ear/placeCntrAppUI.war/WEB-INF/jsp/search.jsp
   3. wp_profile/installedApps/qkr/placeCntrApp.ear/placeCntrAppUI.war/WEB-INF/jsp/templates.jsp
   4. wp_profile/installedApps/qkr/placeCntrApp.ear/placeCntrAppUI.war/WEB-INF/jsp/noPermission.jsp
   5. wp_profile/installedApps/qkr/searchApp.ear/searchCenterUI.war/WEB-INF/jsp/PlaceSearchCenter.jsp
   6. wp_profile/installedApps/qkr/searchApp.ear/searchCenterUI.war/WEB-INF/jsp/ECMSearchCenter.jsp

   Replace text line

   <link rel="stylesheet" href="${commonRes}/css/defaultTheme/
commonstyles${rtlSuffix}.jsp" type="text/css" />

   With

   <link rel="stylesheet" href="${commonRes}/css/
<yourCustomTheme>/commonstyles${rtlSuffix}.jsp" type="text/css" />

After you save your changes and refresh the browser, you can see the custom stylesheet applied to the Places Catalog page.

Back to top

Updating the default stylesheet

Logo

To update to your company logo, drop in the new logo to replace the following files:

• custom_theme_root\css\images\logo_black.png
• custom_theme_root \css\images\logo_white.png
• custom_theme_root \css\images\logo.png

Logo style classes are compacted in the themeroot\css\themeStyles.jsp file. Update this JSP to adjust the height, width, background color, and so on for the logo.

Global navigation and place tabs

Navigation links at the top of the page remain constant across all pages in Lotus Quickr. These links are referred as the global navigation links. Figure 5 shows the ready-to-use global navigation as rendered.

The existing global navigation is rendered with a Dojo widget. You can modify the navigation bar without making changes to Dojo. The example that follows shows how to add entries on the navigation as shown in figure 6 and listing 2.

<ul id="quickrGlobalNav" class="lotusInlinelist lotusLinks">
<li class="lotusSelected"><a href="/places">Places</a></li>
<li class="lotusInlinelist"><a href="http://yourPortalURL">Portal</a></li>

</ul>

Similarly, you can make changes to place a tab row by editing the custom_theme_root\topNav.jspf file. The code snippet in listing 3 adds another tab to the place tab row as shown in figure 7.

<ul class="lotusTabs lotusLeft" style="width: 50%" id="quickrTopNav">
<li class="lotusFirst">
<a href="/places/publicplaces">Public Places</a></li>
    <li class="lotusFirst">
    <a href="/places/myplaces">My Places</a></li>
    <li class="lotusFirst">
    <a href="http://yourcustomURL">Custom Service</a></li>
</ul>

Alternatively, you can also use the existing widget code to pull links to custom services added to the LotusQuickr-config file. For more details about how to add a custom service to the Lotus Quickr configuration service, follow the steps in the Lotus Quickr 8.5 Information Center.

Side navigation

Side navigation, also known as the left navigation, renders pages inside a Lotus Quickr place. By default, the side navigation is created using a Dojo widget. Users can modify the side navigation to edit the color scheme or element layout or to add entries. While changes such as updated colors or other presentation semantics can be modified by updating the CSS in common resources app, other changes, such as adding more links similar to the existing Members link, require modification to the sideNav.jspf file located in <themeroot>.

Listing 4 is an example that shows how to add more entries to the side navigation.

<ul>
     <li <c:if test="${!inPlace}">class="lotusSelected"</c:if>>
        <a id="membersLink" href="${appMembers}
        &mp=${mp}&mr=${mr}&eap=${eap}'
        cp=${colorPalette}<%= ref %>" <c:if 
        test="${!inPlace}">style="cursor:pointer"</c:if>>
        <portal-fmt:text key="view.membership" 
        bundle="nls.quickr" /></a>
     </li>
     <li><a href="">Item 1</a></li>
     <li><a href="">Item 2</a></li>
     <li><a href="">Item 3</a></li>
     \</ul>

Figure 8 shows a sample side navigation menu with updates to colors, menu styles, and layout. Styles applied to the side navigation are stored in the common resources application.

Customize shelf

Customize shelf provides a place for place managers to customize their places by selecting from a variety of available page layouts, color themes, and Lotus Quickr components. The customize shelf is not available to place users who are not managers.

In its ready-to-use state, the customize shelf consists of three tabs: Add Content, Change Layout, and Change Styles. While you use Add Content to add components to a place, Change Layout and Change Styles provide layouts and stylesheets to customize the presentation of your place.

The previous section on "Adding stylesheets" described how to create and add stylesheets to a custom theme. Similarly, you can modify the custom_theme_root\new_quickr.json file to add custom components on the shelf. After it is added, your custom component is available to every place manager in Lotus Quickr.

The following steps describe the changes required to add components to customize shelf.

1. Open and edit the custom_theme_root \new_quickr.json file.
   
   

   The JSON file contains entries for each component listed on the customize palette. To add an entry for the custom component, copy an existing entry and edit the values label for your custom component: component_title, description, portletID (uid for portlet), id (uid for portlet), and thumbnail. Listing 5 is an example of a new entry.

   
   
   Listing 5. Example entry: new_quickr.json
   

   {'label':'CustomComponent’, 'component_title':' CustomComponent ', 'description':'This is my custom component', 'applicationID':ibmPortalConfig.appID, 'portletID':'wps.p.teamCalendar', 'id':'wps.p.teamCalendar', 'redirect':'true', 'nodesOnLevel':ibmPortalConfig.nodesOnLevel, 'samePage':'true', 'cmdUrl':ibmPortalConfig.myurl, 'thumbnail': 'class:qkrSprite-components qkrSprite-components-events-16x16'}

   
   

After completing these steps, you can see your custom component available on the shelf.

Tip: If you add a new entry as the last entry in the JSON file, insert a comma at the end of the previous line to ensure correct file format. Any errors in this file can prevent you from loading the custom palette on server.

See the Lotus Quickr wiki article, “Adding components to customize shelf: qp85,” for more details about adding custom components to customize shelf.

Footer

Theme footer, which is the section at the bottom of the theme page, is common across all pages in a Lotus Quickr place, places catalog, or places administration page. The common footer is included in the Lotus Quickr common resources application. The footer JSP can be customized to add or remove entries, change the layout, or modify footer styles. You can make changes to the theme footer by accessing the custom_common_resources_root/jsp/footer.jsp file.

Back to top

Skin customization

Portlet skin is the wrapper that goes around the portlet. The portlet title, portlet menu actions, and a border to mark the portlet area are all rendered by the skin. Skins are bundled inside the theme EAR and located at:

Figure 9 shows the default skin as it shows in Lotus Quickr.

In its ready-to-use state, Lotus Quickr ships with two primary skins:

• XQkrSkin (default skin used in the Lotus Quickr theme)
• QkrThinSkin

Users can select from either skin type depending on requirements. While the default QkrSkin looks as shown in figure 9, QkrThinSkin hides the skin wrapper and makes it visible only when the mouse pointer is over the portlet area. Similarly, users can also create custom skins and apply them to places. Figure 10 shows a place with QkrThinSkin.

Notice that there is no skin wrapper around the portlet this time. However, the wrapper shows if you point to the portlet. This wrapper can be customized to never show the skin or show only the portlet menu at all times.

Back to top

Translation files

The language bundles for the Lotus Quickr theme are located at:

They follow the naming pattern quickr_[language].properties. You can add new strings to the theme by adding new resource bundles to this directory. More details about adding resource bundles can be found in the WebSphere Portal Information Center V6.1.5.

Back to top

Conclusion

This article summarizes the common scenarios for customizing themes in Lotus Quickr 8.5. With the information included in this article, you should be ready to create themes and turn them into your theme. Use this article as a guide to understand how to modify the different parts of the theme.

Resources

• Participate in the discussion forum.
  
  
• Read the developerWorks® article, "Customizing themes in IBM Lotus Quickr services for IBM WebSphere Portal 8.0."
  
  
• See the Lotus Quickr 8.5 for WebSphere Portal documentation.
  
  
• See the Lotus Quickr wiki.
  
  
• See the WebSphere Portal 6.1.5 Information Center.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Prerequisites
• Getting started
• Theme customization
• Updating the default stylesheet
• Skin customization
• Translation files
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express

Dig deeper into Lotus on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers