Customization overview for IBM Connections 3.0.1

Branding IBM Connections

IBM Connections is social software for business. IBM Connections includes several social applications, including Profiles, Communities, Blogs, Files, Wikis, Activities, and Bookmarks. Learn how to brand and customize the IBM Connections user experience to meet your business needs.

Share:

Brian Ochs (bochs@thinksis.com), Solution Architect, Software Information Systems

Brian Ochs photoBrian Ochs is a solution architect at Software Information Systems, an IBM Premier Business Partner. He specializes in customer implementations of IBM Connections and IBM WebSphere Portal. He has been working with Connections since the initial release and is the coauthor of the IBM Connections 3.0.1 Customization Redbook.



28 August 2012

Also available in Chinese Russian Portuguese

IBM Connections provides a social software platform based on collaboration tools such as Profiles, Blog, and Wikis, and you can customize any of these applications to meet your business needs. Typically, you change colors to match corporate branding or add information to the Profile pages. In previous versions of IBM Connections, such customizations could require a significant development effort. However, IBM Connection version 3.0.1 has greatly streamlined the customization process, allowing you to make changes more easily and safely.

This article provides a high-level overview of the basic process and describes examples of some typical customizations. In addition, useful tools and best practices are offered. For more detailed step-by-step instructions on implementing customization, be sure to see Resources.

Overview

IBM Connections 3.0.1 supports changing many aspects of its appearance without altering the source code of the installed web applications. You customize the user interface (UI) by overriding the installed files in a special customization directory. Updated files in the customization directory override the corresponding installed files in the application source directories automatically. This customization process uses the IBM WebSphere® extended document root facility to allow IBM Connections applications access to files outside of the application web archive directory. Separating the customized files from the installed files helps you identify what you have customized, allows you to easily revert to the default files, and means that updates or fix packs applied to default files do not overwrite your customizations.


Planning

A successful customization project requires good coordination among various teams with different skill sets. All participants must understand the types of changes that can be made and which change types are not feasible.

Necessary skills

Customizing IBM Connections is generally a simple process of saving files to a customization directory and modifying them. However, knowing which file to change and understanding what to modify is easier if you have the appropriate skills. These skills break down into the following three roles:

  • Administrators:
    • Configure IBM Connections to match your organizational objectives.
    • Maintain the product installation, and publish the customization.
    • Work with developers to update customization files when fix packs are deployed.
  • Designers:
    • Determine how IBM Connections should be branded within an organization.
    • Produce image files and branding guidance.
  • Web developers:
    • Implement branding and customization with HTML through JavaServer Pages™ (JSP), cascading style sheets (CSS), and JavaScript.
    • Update customized files when fix packs or iFixes are applied.
    • Implement deeper customization or integration of Profiles, Communities, or other applications requiring Java™ coding.

Before you get started

The customization process requires changing files that can possibly be cached on the server or at the client. So, to avoid any unnecessary frustration, take a couple of first steps to get started in the right direction.

Two WebSphere variables play an important role when customizing IBM Connections. You can review and update these variables from the IBM WebSphere Application Server Integrated Solutions Console.

Enabling customization debugging

Unless you enable the customization debugging capability, new versions of customized files are loaded only when the IBM Connections applications are restarted. After you enable the debugging capability, you can usually test your changes immediately by refreshing the page in the browser. Because the debugging capability is resource intensive, enable it only while developing customizations for IBM Connections. Also, do not enable the capability on a production server. The debugging variable is CONNECTIONS_CUSTOMIZATION_DEBUG.

Customization directory path

The directory path declared in the WebSphere environment variable CONNECTIONS_CUSTOMIZATION_PATH identifies the base location of the customization directory that IBM Connections uses. This variable is set during installation of IBM Connections. IBM Connections processes the files under this path to override the installed files. If you accepted the defaults during installation, the customization path is Connections_install_directory\data\shared\customization.

You can verify this customization path using the WebSphere Application Server Integrated System Console. You must place all of the customized files under this directory in the appropriate subdirectory.


The customization process

For most UI customizations, you copy a file that contains default information from a source directory to a corresponding subdirectory in the customization directory. You change content in the file you copied, and then save the file. When rendering the page, IBM Connections uses the information from the file in this customization directory.

Undoing the customization is simply a reverse of this process. When you want to remove a customization, delete the customized file, and restart the affected applications. Files in the common subdirectory affect all IBM Connections applications. Files in application-specific customization directories affect only those applications and override the common customization directory.

For example, to change the footer in all of the applications except Activities, change the footer in the common customization directory, and make additional changes in the Activities customization directory. To change the footer only in the Activities application, make changes only in the Activities customization directory. Figure 1 illustrates this processing order for the header and footer in all applications or only in the Profiles application.

Figure 1. Customization order of precedence
Image showing the customization order of precedence

You can see that files in the Profiles customization directory override changes in the common customization directory. Files in either customization directory override the installed files.


Typical customizations

With IBM Connections 3.0.1, the most commonly requested customizations can be made with minimal effort. You can change the colors to match corporate standards or create a login page that suits your requirements. This section discusses how to make some of the more common customizations.

Typically, the first customization efforts involve updating the header and footer with the company logo, applying corporate colors, or adding extra links to the menus (see Figure 2). Updating the header across all of the application is a straightforward process of copying the default header.jsp file—a version of which resides in each application source directory—to the customization directory. You can add standard JSP or HTML code to customize the layout or functionality of this file. For instance, you can add hyperlinks or new drop-down menus that link to other applications. Simply save the customized file to the appropriate subdirectory in the customization directory path.

Figure 2. Sample header customization
Image showing a sample header customization

Themes

In addition to creating a custom, branded look for an entire IBM Connections site, you can create sets of files called themes to be used in the Blogs and Communities applications. As a Blog or Community owner, you can select from a set of available themes to provide a most appropriate design to your part of the site. Although some default themes are provided during the installation process, you can create additional themes and make them available to the other site owners.

The easiest way to create a new theme is to copy an existing theme and simply update the JSP and CSS files to implement the new look and feel. Figure 3 provides an example.

Figure 3. Community theme selection
Image showing community theme selection

Product string customizations

The base installation of IBM Connections supports many languages and selects the appropriate language automatically based on the language used by the visitor to the site. This language support is made possible through the use of resource bundles—collections of files that contain the translation for the text displayed on the page. Each language is stored in its own specific file. You can override these files to change the text displayed on almost any page.

Some aspects of customizing product strings are similar to other UI customizations, but there are notable differences. For example, as with other UI customization, you change specific files and save them to a customization directory. As you would expect, changes made to the strings stored in the customization directories override the default strings.

However, unlike other UI customizations, for strings stored in property files, you always save files to the customization_path/strings directory. There are no subdirectories under the strings directory. A single directory works, because the file name of the customized properties file incorporates the entire directory path of the default property file it overrides. The slashes that represent directory separators are replaced by periods in the customized file name. For example, if you want to override a product string found in the templates.properties file stored in the lc.util.web-3.0.jar at /com/ibm/lconn/core/strings, save the customized properties file with the file name com.ibm.lconn.core.strings.templates.properties. The period separators in the customized file name represent the directory separators in the default file.

In addition, IBM Connections uses the web browser locale to automatically determine the language to display in the UI. Strings are stored in language-specific and language-independent files. Strings for the default locale (language-independent files) are stored in a file without a language code in the file name. Language-specific files have file names with a language code as a suffix. For example, the com.ibm.lconn.core.strings.templates.properties file is the language-independent file that contains strings used for the default locale. When there is no specific property file for the web browser locale, the strings in this default properties file are displayed. To include a Brazilian Portuguese translation of the strings in this properties file, for example, create a separate file named com.ibm.lconn.core.strings.templates_pt-BR.properties. The strings in this file are shown to users in the Brazilian Portuguese locale.


Advanced customizations

Most customizations are made by copying files to the customization directory, as already described. However, you can customize IBM Connections in other ways, as well. Profile extension attributes and widgets are two examples that use other methods but provide further customization options to the IBM Connections platform.

Profile extension attributes

In addition to customizations that change existing colors or text strings, you can add new data fields to the Profiles application. IBM Connections provides a base set of attributes for a profile, such as name, contact information, and background. In many cases, additional data may be necessary. In these situations, new data fields called extension attributes are used. These new fields can be automatically populated from databases outside of IBM Connections using the included IBM Tivoli® Directory Integrator software or updated by the profile owner.

Profile extension attributes have a different method of implementation, which is outside the scope of this article. For more information, see the Customizing IBM Connections 3.0.1 Redbooks Wiki (Resources provides a link).

Widgets

IBM Connections supports the iWidget specification for creating small applications that can be placed on the Home Page, Profiles, or Community pages. Widgets are lightweight JavaScript applications that pull data from external databases or web services. You can develop widgets using only JavaScript and CSS, or you can take advantage of server-side languages such as Java or PHP. Listing 1 shows the code for a basic widget.

Listing 1. A basic widget
<iw:iwidget name="helloWorld" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget">
<iw:content mode="view">
<div>
<div id="helloWorld">Hello World!</div>
</div>
</iw:content>
</iw:iwidget>

In addition to writing custom widget applications, the IBM Business Solutions Catalog has many widgets available for download.


Useful tools

It can be a challenge to figure out which files control which page elements. For example, it can be difficult to figure out which CSS rule controls a particular element of the UI. In addition, changes you make to XML configuration files must conform to the schema, while JSP and HTML files must be structured correctly. When customizing UI strings, you must search Java archive (JAR) files for where UI strings are stored. When testing changes to translated UI strings, you must change the locale of your web browser. You might find the following utilities useful in accomplishing these tasks.

Disabling your browser cache

You must often clear your browser cache to test changes you have made to IBM Connections. To do so, you can use a tool to temporarily disable your browser cache, such as the Web Developer add-on for the Mozilla Firefox and Google Chrome browsers (see Resources for a link).

Changing CSS rules and UI elements

Use a web inspector tool to locate the CSS rules you want to change. Examples of web inspector tools include Firebug for Firefox and Chrome and Web Inspector on Chrome or Apple Safari. See Resources for links.

Changing XML, JSP, and HTML files

Use a text editor that helps identify correct tagging. Examples of such text editors include gedit for Linux® and Notepad++ on Windows® (see Resources for links). You can use Eclipse, as well, which runs on many different platforms.

Testing translated strings

Use a locale switcher tool that changes the locale of the browser without having to install a locale-specific operating system or change settings in the operating system. An example of a locale switcher tool is the Quick Locale Switcher add-on for Firefox and Chrome (see Resources for a link).


Best practices

The following tips contribute to a smooth customization process and make your future maintenance tasks more manageable.

Back up frequently

Back up your customization directory in your development environment before making changes. If you use source control, add the customization directory to your tool. If you do not use source control, consider adopting it, or devise your own version-control process.

Minimize copying

Copy only those files that you need to modify to the customization directory. Minimizing the number of files in the customization directory means that there are fewer files to manage, making it easier for you to track what has changed.

Document changes

Keep track of the changes you make by documenting them and adding comments to the files. Comments help you to remember where and why a change was made. If you merge multiple changes, add comments directly to JSP and CSS files to simplify the process.

Check out configuration files properly

Sometimes, it is necessary to update XML configuration files in the WebSphere Application Server configuration directory. Although updating these XML files directly technically will work, using the proper wsadmin commands is a much better solution. Using wsadmin ensures that the XML files are well formed and valid before the changes are committed to the repository. See the product documentation for details on using the wsadmin command-line tool.

Update the timestamp value

IBM Connections pages and their various CSS and JavaScript components are usually cached by the browser to improve performance. After you make your customizations, override the cache to force browsers to download the latest copies of the changed files. You can use the WebSphere Application Server wsadmin tool to update the version stamp on the appropriate configuration file.


Conclusion

IBM Connections provides a social software platform that you can customize to meet your business needs. In versions prior to 3.0.1, a customization project could require a significant development effort. However, the process has been greatly simplified, allowing you to make changes more easily and safely.

Resources

Learn

Get products and technologies

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=827919
ArticleTitle=Customization overview for IBM Connections 3.0.1
publish-date=08282012