Deploying IBM Lotus Connections: Branding and customization

Part 5 in our article series demonstrates how to brand and how to customize the IBM Lotus Connections user interface. Learn how to make changes to ensure that Lotus Connections has the right look and feel for your enterprise.

Eugene Louie (eugene_louie@us.ibm.com), Senior I/T Specialist, IBM

Eugene Louie is a Senior I/T Specialist with IBM Software Services for Lotus. Since joining the team in late 2006 he has been engaged on IBM Lotus Connections and IBM Lotus Sametime V7.5.1 projects. Prior to this, Eugene was a Software Engineer on the Lotus Component Designer team in Westford, Massachusetts. You can reach Eugene at eugene_louie@us.ibm.com.



11 September 2007 (First published 28 August 2007)

Also available in Japanese

IBM Lotus Connections provides a mechanism to customize the navigation bar as well as other areas of the product. This article outlines the steps you take to change the navigation bar and offers examples for changing the content of existing pages. This article is intended for I/T specialists and I/T architects and assumes that you have a solid understanding of HTML tags and some Java and JSP skills.

Customizing the Lotus Connections navigation bar

Lotus Connections provides a default navigation bar that lets you navigate among the Lotus Connections features. Sometimes, though, one size does not fit all. Luckily, the Lotus Connections development team has built the navigation bar so that it is easily customizable. This section explains how the navigation bar is built and how you can change it to ensure that the proper branding appears for your environment.

How the navigation bar is created

Before customizing the navigation bar, you need to understand how it is created. Viewing the HTML source of a rendered Lotus Connections page does not reveal the HTML behind the navigation bar. The navigation bar is rendered on the Blogs pages with the following JavaScript:

<script type="text/javascript" language="Javascript" src="/blogs/nav/header.js">

One key point to keep in mind is that each Lotus Connections feature comes bundled with its own version of the navigation bar located in the same directory relative to the Lotus Connections feature directory. For example, you can find the navigation bar application for the Profiles feature in <was_profile_root>/installedApps/<cell_name>/Profiles.ear/sn-nav.war. An examination of the servlet mappings in the web.xml file in sn-nav.war located in the WEB-INF directory reveals the classes involved in creating the navigation bar.

Changing the navigation bar

Lotus Connections provides an easy method to change the content and the look and feel of the navigation bar. Lotus Connections uses two default-style navigation bar templates, custom-styles.css and header.html, to provide the style and content for the navigation bar. Follow the steps outlined in the "Customizing the navigation bar section" of the Lotus Connections Information Center to ensure that changes to the navigation bar are referenced by each installed Lotus Connections feature.

The role of header.html

Header.html defines the HTML elements that appear on the navigation bar. For Dogear, this file can be found in the <was_profile_root>/installedApps/<cell_name>/Dogear.ear/sn-nav.war/templates directory. The default Lotus Connections navigation bar contains the installed Lotus Connections features, the user name, and the logout button as shown in figure 1.

NOTE: The element that displays the logged-in user's name and the logout/login links should not be changed. In the case of Profiles, some elements are requested with Ajax calls after the page is loaded because of the need to keep certain pages cacheable.

Figure 1. Contents of header.html
Contents of header.html

Adding links

You can add new elements to the navigation bar by adding markup to the header file. The elements surrounded by curly braces are replaced with dynamic data by the navigation servlets. For example, the {{application links}} text is replaced with links to the Lotus Connections features, and the {{label.header.logout}} text is replaced with translated text from the appropriate resource bundle. Create a menu item by adding links to the list. In this example, we add a menu item to link to the Lotus home page.

Follow these steps:

  1. Save a backup of header.html.
  2. Open header.html in a text editor.
  3. Add the text highlighted in bold in the following code sample after the {application links} element.
    <ul class="inlinelist links">
    {{application links: li }}
    <a href="http://www.lotus.com">Lotus Software</a>
    </ul>
  4. Save the file, and restart Dogear.

The new navigation bar is shown in figure 2.

Figure 2. The new menu item in the navigation bar
The new menu item in the navigation bar

Using JavaScript on the navigation bar

In addition to HTML markup, you can add dynamic content to the navigation bar by using inline JavaScript. For example, you can add the current date to the right-hand side of the navigation bar using JavaScript.

To do this, follow these steps:

  1. Save a backup of header.html.
  2. Open header.html in a text editor.
  3. Add the code in bold highlighted in listing 1.
  4. Save the file, and restart Dogear.
Listing 1. Code to add the date to the Dogear navigation bar
<!-- Copyright IBM Corp. 2007  All Rights Reserved. -->
<div id="headerInner">  
    <a href="#mainContent" accesskey="S" class="hidden"><img src="{{images}}/blank.gif" 
    alt="Skip to main content link. Accesskey S"></a>
    <h1 style="display: none;">Lotus Connections</h1>
     <ul class="inlinelist links"> 
         {{application links: li }}
     </ul>
    <ul class="userlist">
        <li class="first" id="headerUserText" style="display:none">
        <span id="headerUserName"><em>unknown user
        </em></span></li>
        <li class="divide" id="logoutLi" ><a href="#" id="logoutLink" >
        {{ label.header.logout }}</a></li>
        <script type="text/javascript">
                var currentTime = new Date();
                var month=currentTime.getMonth()+1;
                var day=currentTime.getDate();
                var year=currentTime.getFullYear();
                document.write(month + "/" + day + "/" +year);
        </script>
    </ul>
</div>

The new navigation bar is shown in the figure 3.

Figure 3. The result of adding the inline JavaScript to add the date
The result of adding the inline JavaScript to add the date

The role of custom-styles.css

The custom-styles.css is the navigation bar's cascading style sheet (CSS). This file defines, among other things, the fonts, the colors, and the background image used in the navigation bar. For Dogear, this CSS file can be found in the <was_profile_root>/installedApps/<cell_name>/Dogear.ear/sn-nav.war/templates directory.

Apply an existing style

The new menu item added in the previous example lacked style information and appeared in blue with a mix of uppercase and lowercase characters. To make the style consistent with the other items on the navigation bar, we enclose the menu item in a <li> or line item tag.

To do this, follow these steps:

  1. Save a backup of custom-styles.css.
  2. Open custom-styles.css in a text editor.
  3. Find the following line:

    <a href="http://www.lotus.com">Lotus Software</a>

    And replace it with:

    <li><a href="http://www.lotus.com">Lotus Software</a></li>

  4. Save the file, and restart Dogear.

The new navigation bar is shown in figure 4. By enclosing the new menu item in a <li> tag, the menu item inherits the style assigned to the <li> tag specified in the CSS file.

Figure 4. Menu item with the style assigned to the <li> tag
Menu item with the style assigned to the <li> tag

Create a new style

New styles can be defined by adding the style to custom-styles.css. This section provides an example of creating a style to render the menu item using the Courier New font to differentiate the new menu item. The following process defines a new style named myLinks in custom-styles.css:

  1. Save a backup of custom-styles.css.
  2. Open custom-styles.css in a text editor.
  3. Insert the following code at the end of the file:

    #header .myLinks {font-family: Courier, "Courier New", monospace}

  4. Save and close the file.
  5. Open header.html, and find the following line:

    <li><A HREF="http://www.lotus.com>">Lotus Software</A></li>

    And replace it with:

    <li class="myLinks"><A HREF="http://www.lotus.com>">Lotus Software</A></li>

  6. Save and close the file.
  7. Restart Dogear.

The new navigation bar is shown in figure 5.

Figure 5. The new menu item with the new style applied
The new menu item with the new style applied

Changing the background image of the navigation bar

CSS also defines the navigation bar background image. In order for the navigation bar image to appear correctly at varying browser window widths, the background image is a composite of two images. The first image specifies the left side of the navigation bar and the second image specifies its right side. To avoid issues when rendering the image, the size of the left image should be 1600x100, and the size for the right image should be 300x100. Remember to copy the new background images to the images subdirectory of the sn-nav.war directory.

Follow these steps to change the default navigation bar background images:

  1. Save a backup of custom-styles.css.
  2. Open custom-styles.css in a text editor.
  3. Change the code highlighted in bold in listing 2 to specify your own files.
  4. Save and close the file, and then restart Dogear.
Listing 2. Custom-styles.css specifying the background image of the banner
#header { 
	/*font: normal .75em/1.5em Helvetica, Arial, Verdana, sans-serif; */
	background: transparent url("{{images}}/yellowBanner_left.gif") 
	bottom left no-repeat;
	color: #5b3feb;
	/*height: 4.0em; */
	height: 47px;
	padding: 0;
	text-align:right;
	/*font-size: .9em;*/
}

#header #headerInner {
	/*height: 3.75em;	*/
	height: 47px;
	background: transparent url("{{images}}/yellowBanner_right.gif") 
	bottom right no-repeat;
}

Figure 6 shows the new navigation bar.

Figure 6. The new banner with the new images and application links
The new banner with the new images and application links

Customizing Lotus Connections pages

To customize Lotus Connections, you need to understand how pages are rendered. Lotus Connections is built on the Struts framework. Struts is an open source framework from the Apache Jakarta project for developing Web applications using a Model View Controller (MVC) design pattern. The Struts framework is outside the scope of this article, but we introduce basic Struts concepts as required. For more information on Struts, visit the Apache Struts site.

In the following examples, you learn how to change field labels and error messages, and you discover how to customize the Profiles component by adding a required field to it.

NOTE: Changes to config files should be performed by an experienced user.

Customize text, field labels, and error messages

Lotus Connections stores labels, error messages, and other text in property files specific to each locale. You can add or modify entries in the property file to create or change field labels and error messages. Property files follow the key=value format, where key is the value specified in either the JSP or tag attribute and value is the text to display.

Each Lotus Connections component has its own set of property files, which have a PROPERTIES extension. Table 1 outlines the location of these property files.

To edit the property files, follow these steps:

  1. Extract the JAR file containing the property files (for example, peoplepages.web.jar) to a temporary location.
  2. Save a backup of the property file you need to edit.
  3. Open the appropriate property file in a text editor.
  4. Make your changes as appropriate.
  5. Save and close the file.
  6. Re-create the archive to include your changes.
  7. Restart the appropriate Lotus Connections feature.
Table 1. JAR file names and property files
FeatureLocationPath
Activities<WAS_PROFILE_ROOT>/installedApps/<cellname>/
Activities.ear/oawebui.war/WEB-INF/lib/oawebui.jar
com/ibm/openactivities/web/coreui/
resources/resources.properties
Blogs<WAS_PROFILE_ROOT>/installedApps/<cellname>/
Blogs.ear/blogs.war/WEB-INF/classes/
ApplicationResources.properties
Communities<WAS_PROFILE_ROOT>/installedApps/<cellname>/
Communities.ear/tango.web.ui.war/WEB-INF/lib/tango.web.ui.jar
com/ibm/tango/web/ui/resources/
resources.properties
Dogear<WAS_PROFILE_ROOT>/installedApps/<cellname>/
Dogear.ear/dogear.webui.war/WEB-INF/lib/dogear.svc.jar
com/ibm/dogear/resources/
jspresources.properties
Profiles<WAS_PROFILE_ROOT>/installedApps/<cellname>/
profiles.ear/peoplepages.war/WEB-INF/lib/peoplepages.web.jar
com/ibm/peoplepages/webui/resources/
resources-general.properties and resources-attributeLabels.properties

Adding a field to the Profiles feature

The Profiles feature displays a set of default fields, but because every organization's directory is unique, the Profiles feature provides the ability to extend the application with up to three custom extensions, property1, property2, and property3. In this example, you add a mentor field to the Profiles feature using the custom extensions.

The custom extension fields require that a row exist for each user in the Profile_Extension table of the Profiles database. In the V1.0 release of Profiles, the Profile_Extension table is not populated with data by the IBM Tivoli Directory Integrator scripts. This will be addressed in release 1.0.1. The following example is based on that release.

Enabling the custom extension properties

To use the custom extension properties, follow these steps:

  1. Modify the profiles_extensions.properties file in the Tivoli Directory Integrator directory to indicate the property to extend, the property's name, data type, and key as shown in the following code sample:
    PROPERTY_IDS=property1
    PROF_NAME.property1=Mentor
    PROF_DATA_TYPE.property1=String
    PROF_KEY.property1=Mentor
  2. Edit the map_dbrepos_from_source.properties file to map the custom extension to a field in your source LDAP directory, for example: PROF_VALUE.property1=property1.

For more information refer to the "Mapping fields" section of the Lotus Connections 1.0 Installation Guide.

After you run the Tivoli Directory Integrator script to import data, the Profile_Extensions table of the Profiles database is populated.

Enabling the mentor field on the Edit My Profile tab

The fields that appear on the My Profiles tab are specified using the profiles-config.xml file located in the <was_profile_root>/config/cells/<cell_name>/nodes/<node_name>/LotusConnections-config directory. Generally speaking, changes to profiles-config.xml should be performed with the wsadmin client scripting interface. Because there are no wsadmin commands to modify the profilesDataModel, you can make changes to the profilesDataModel with a text editor.

Use the wsadmin checkout command to check out the file prior to making changes. Similarly, use the wsadmin checkin command when your changes are complete. The checkout and checkin processes perform a schema validation on the config file. For more information on the wsadmin scripting interface, refer to the "Editing feature settings with the wsadmin client" section of the Lotus Connections Information Center.

There are three child elements under the profileDataModel element that correspond to the three sections in the My Profile tab: Job Information, Contact Information, and Associated Information. The order in which the fields appear in the config file reflects the order in which they appear on the form. Therefore, you can very easily re-order the attributes without needing to modify any JSP files.

To add the mentor field to the Contact Information section of the My Profile tab, follow these steps:

  1. Save a copy of the profiles-config.xml file.
  2. Open the file in a text editor.
  3. Add the following line as a child element to the contactInformation element as shown in bold in listing 3:

    <editableAttribute showLabel="true" hideIfEmpty="true" hcard="true">property1</editableAttribute>

  4. Save and close the file.
  5. Restart Profiles to see your changes.
Listing 3. Adding the Mentor field to Profiles
<!-- <editableAttribute showLabel="true" link="true">calendarUrl</editableAttribute> -->
<!-- <editableAttribute showLabel="true" link="true">freeBusyUrl</editableAttribute> -->
<editableAttribute showLabel="true" 
hideIfEmpty="true" hcard="true">property1</editableAttribute>
</contactInformation>

The hcard attribute enables the name type-ahead feature. For more information regarding the editableAttribute element and its attributes, refer to the "Specifying attributes for Profiles" section of the Lotus Connections Information Center.

The label of the field is specified in the resources-attributeLabels.properties file of peoplepages.web.jar. The property key value used to display the label is a concatenation of the word label, the page section, and the text enclosed in the tag. In this example, the property file key is label.contactInformation.property1. To ensure that the label is properly rendered, add the following code to the resources-attributelabels.properties file:

label.contactInformation.property1=Mentor:

Restart the Profiles component, and click the Edit My Profile tab. The mentor field appears in the Contact Information section of the Edit My Profile tab as shown in figure 7 and in the My Profile tab as shown in figure 8.

Figure 7. The Mentor field in the Edit My Profile tab
The Mentor field in the Edit My Profile tab
Figure 8. The Mentor field in the My Profile tab
The Mentor field in the My Profile tab

Specifying a required field

Because Lotus Connections is built on Struts, you can leverage the Struts validation framework to validate form data. Validation.xml and validation-rules.xml are both part of the Struts validation framework. Validation.xml defines the validation types that are applied to the fields; validator-rules.xml defines a set of standard validation routines. Validation routines such as required and maximum length are included in the validation framework. For more information on the Struts validation framework, consult the Apache Struts Validator Guide.

In this example, you make the mentor field a required field. To do this, follow these steps:

  1. Save a copy of the <was_profile_root>\installedApps\<cell_name>\profiles.ear\
    peoplepages.war\WEB-INF\validation.xml file.
  2. Open the file in a text editor.
  3. Add the code highlighted in bold in listing 4 to the file.
  4. Save and close the file.
  5. Restart Profiles so that the changes go into effect.
Listing 4. Changes to validation.xml to enable field validation of the mentor field
<form-validation>
  <formset>
    <form name="editProfileForm">
      <field property="attribute(contactInformation.property1)" depends="required">
        <msg name="required" key="errors.requiredfield" />
      </field>
      <field property="attribute(associatedInformation.description)" depends="maxlength">
        <msg name="maxlength" key="errors.aboutMe" />
          <var>
	    <var-name>maxlength</var-name>
	    <var-value>1500</var-value>
	  </var>
       </field>

Table 2 lists some of the attributes of the field element. The information in this table should help you specify your own validation requirements.

Table 2. Attributes of the validator
AttributeRole
propertyThe name of the field you want to make required. You obtain the field name by viewing the source of the rendered page.
dependsThe name of the validation to run. In this case, you want a required validation to run.
msg nameOverrides the default required error message. This value matches the validator's name attribute.
msg keyThe message to be displayed when the validation fails. The key in the property file contains the error message to display when validation fails. This is the key you need to add to the property file.

Last, create a custom error message to be displayed when the validation fails by creating a new entry in the resources-general.properties file of the Profiles feature. Create the property file entry with the key specified in the key attribute of the msg element.

errors.requiredfield=Mentor value is missing.

As a result, the message "Mentor value is missing." is displayed when a user does not enter a manager name when he or she saves his or her profile.


Sample JSP files and their functions

Table 3 shows the locations and names of various JSP files and their functions.

NOTE: Custom changes made to JSP files are not supported. These are some of the most commonly customized files, and they should help you determine where to make necessary changes. Changes to these files should be done by an experienced user.

Table 3. Table of JSP files and their function
Path to JSPContent
<was_profile_root>/installedApps/<cell_name>/profiles.ear/ peoplepages.war/WEB-INF/jsps/html/scenes/profile/businessCard.jspThe center content region of the My Profile tab.
<was_profile_root>/installedApps/<cell_name>/profiles.ear/ peoplepages.war/WEB-INF/jsps/html/scenes/profile/editProfile.jspThe contents of the Edit My Profile tab.
<was_profile_root>/installedApps/<cell_name>/Communities.ear/ tango.web.ui.war/WEB-INF/jsps/html/scenes/allcommunities.jspThe contents of the All Communities tab of the Communities component.
<was_profile_root>/installedApps/<cell_name>/Communities.ear/ tango.web.ui.war/WEB-INF/jsps/html/scenes/mycommunities.jspThe contents of the My Communities tab of the Communities component.
<was_profile_root>/installedApps/<cell_name>/Communities.ear/ tango.web.ui.war/WEB-INF/tags/addcommunityform.tag Rendered as part of the All Communities or My Communities tab when you start a community. To see the results of changes in this file, refresh either allcommunities.jsp or mycommunities.jsp.*
<was_profile_root>/installedApps/<cell_name>/profiles.ear/ peoplepages.war/WEB-INF/jsps/html/scenes/login/login.jspThe login page for the profiles component. It works in tandem with loginform.tag to render the Profiles login page.
<was_profile_root>/installedApps/localhostNode01Cell/profiles.ear/ peoplepages.war/WEB-INF/tags/loginform.tagThe login page for the profiles component. It works in tandem with login.jsp to render the Profiles login page. To see the results of changes in this file, refresh login.jsp.*

*Refresh the file by making a small edit, such as adding white space to a tag, and saving the changes.


Conclusion

This article serves as an introduction to branding and customizing your Lotus Connections deployment. To illustrate, this article provides several examples of customizing Lotus Connections. You changed the style and added new content to the navigation bar. You also added a required field to the Edit My Profile tab using one of the custom extensions, and you learned how to effect changes to field labels and error messages by modifying property files.

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=251203
ArticleTitle=Deploying IBM Lotus Connections: Branding and customization
publish-date=09112007