1.1 Overview of customization

Abstract

ShowTable of Contents

HideTable of Contents

1 How customization works
2 General process when customizing
3 Roles and skills
- 3.1 Additional tools
4 Best practices when customizing

Previous | Next

IBM Connections 3.0.1 supports changing many aspects without altering the content of the installed web applications. You customize the user interface by overriding the installed files and saving the files under a directory named "customization" that exists outside the application source directories. Files in the customization directory override the corresponding installed files in the application source directories. This customization process uses the WebSphere extended document root facility to allow IBM Connections applications access to files outside of the application web archive (WAR) directory. Separating the customized files from the installed files helps you identify what you have customized, allows you do revert to the default data, and means that updates to default files do not overwrite your customizations.

How customization works

For most customizations, you copy a file that contains default information from a source directory in the WAR file to a specific subdirectory in the customization directory. You change content in the file you copied and save the file. When rendering the page, IBM Connections uses the information from the file in the customization directory. The location of the customization directory used by IBM Connections is defined by the value of the WebSphere environment variable CONNECTIONS_CUSTOMIZATION_PATH. Because of file caching, you must clear file caches by restarting the IBM Connections application in the application server and updating the version stamp in configuration files to view the changes. However, you can bypass this process when testing your changes by enabling a customization debugging capability and clearing your browser cache. For more information about identifying the customization directory and customization debugging, see 1.2 IBM Connections customization variables.

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 subdirectory named common affect all IBM Connections applications. Files in application-specific customization directories affect only those applications and override the common customization directory. In other words, IBM Connections processes files in this order:

The application-specific customization directory
The common customization directory
The original source file inside the WAR file

For example, to change the footer in all the applications except for the Activities application, 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 change only in the Activities customization directory.

This graphic illustrates this processing order for the header and footer in all applications or only in the Profiles application. 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.

General process when customizing

Follow this process when customizing IBM Connections to simplify testing your changes and make them available to your users when you are finished.

Enable the customization debugging capability so that you can view your changes without having to restart the IBM Connections server. Enabling this environment variable forces the application to reload files each time a request is made, therefore, you see your changes immediately. Because this process is resource intensive, consider the impact to your users when you enable debugging on production. For more information about customization debugging, see 1.2 IBM Connections customization variables.
Find the file you want to change in the source application files. For more information, see 1.3 Source application files.
Copy the file to the relevant customization directory and make your changes.
Test your changes by clearing your browser cache and refreshing the browser.
Publish your changes when you are ready to make the changes available to others:

Disable the customization debugging capability by setting the environment variable CONNECTIONS_CUSTOMIZATION_DEBUG to false.
Update the appropriate configuration properties file by checking out the file, updating the version stamp, and checking in the file.
For more information, see 1.4 Publishing customizations with the wsadmin tool.

Roles and skills

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

Administrators

Configure IBM Connections to match your organizational objectives.
Maintain the installation and publish the customization.
Work with developers to update customization when fix packs are deployed.

Designers

Determine how IBM Connections should be branded within an organization.
Produce images and branding guidance.

Web developers

Implement branding and customization with HTML through JavaServer pages, cascading style sheets (CSS), and JavaScript. Web developers have familiarity to make basic changes to JSP files.
Update customized files when fix packs or iFixes are applied.
Implement deeper customization or integration of Profiles, Communities, or other applications.

Additional tools

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

Disabling your browser cache
You often must clear your browser cache to test changes you have made to IBM Connections. Use a tool to temporarily disable your browser cache. An example of a tool to disable your browser cache is the Web Developer add-on for the Firefox and Chrome browsers.

Changing CSS rules and UI elements

Changing XML, JSP, and HTML files

Finding the property file for a string

On Microsoft Windows: add a PersistentHandler registry key to support searching .jar files. Or use Cygwin or Eclipse.
On AIX or Linux: use the included grep command.

Testing translated strings

Best practices when customizing

Back up frequently. For example, back up your customization directory in your development environment before making changes. If you use source control, add the customization directory to it. 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 files in the customization directory means that there are fewer files to manage, and it is easier for you to track what has changed.
Keep track of the changes you make by documenting the changes 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 simply the process.

Parent topic: 1.0 Introduction to customizing IBM Connections