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.
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.
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.
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:
- 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.
- Determine how IBM Connections should be branded within an organization.
- Produce image files and branding guidance.
- Web developers:
- 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
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
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
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.
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.
Changing the header and footer
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
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
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
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
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.
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).
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.
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
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).
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.
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.
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
commands is a much better solution. Using
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
wsadmin command-line tool.
Update the timestamp value
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.
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.
- Check out the IBM Connections page.
- Visit the Customizing IBM Connections 3.0.1 RedWiki for more detailed information about customizing IBM Connections.
- Find technical information at the IBM Connections Product Documentation site.
- Try IBM Connections on the Lotus Greenhouse.
Get products and technologies
- Download Notepad++.
- Download Firebug.
- Download the Web Developer add-on for Firefox or Chrome.
- Download Web Inspector for Safari or Chrome.
- Download the Quick Locale Switcher Firefox add-on.
- Participate in the IBM Connections forum.
- Subscribe to the IBM Social Software blog.
- Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.