Customizing the user interface 

---

The steps that you must perform to customize IBM® Connections are the same no matter what part of the product you are customizing.

Before you begin

Start IBM Connections and review the product user interface to determine which areas of the product you want to customize.

About this task

The IBM Connections 3.0.x user interface style is based on the IBM Lotus User Interface Toolkit 2.1.

Procedure

1. In the web application source directories for the applications, find the file that serves as the source of the area of the product that you want to edit.
   
The default location for the web application directory for each application is: <WAS_home>/profiles/<profile_name>/installedApps/<cell_name>/<application_name.ear>/<application_name.war> where:

• <WAS_home> is the directory to which you installed IBM WebSphere® Application Server
• <profile_name> is the profile to which you installed one of the IBM Connections applications
• <cell_name> is the cell to which you installed the application
• <application_name.ear> is the EAR file name for the application
• <application_name.war> is one of the following file names:
  
  
Table 1. Application WAR files

Application	File name
Activities	oawebui.war
Blogs	blogs.war
Bookmarks	dogear.webui.war
Communities	comm.web.war
Files	qkr.share.files.war
Forums	forums.web.war
Home page	homepage.war
Profiles	lc.profiles.app.war
Search	search.war
Wikis	qkr.share.wiki.war



2. Turn on the customization debugging capability by adding a WebSphere Application Server environment variable named CONNECTIONS_CUSTOMIZATION_DEBUG and setting it to true. To do so, complete the following steps:
1. Open the Integrated Solutions Console, expand Environment, and then click WebSphere variables.
2. In the Scope section, select cell 1 from the list, and then click New.
3. Type the following values into the fields:
   
Name
CONNECTIONS_CUSTOMIZATION_DEBUG
Value
true

4. Click Apply, and then OK to return to the previous page.
   
3. Copy the file that you want to edit from one of the web application directories listed in Step 1.
   
The following list identifies the files that serve as the source of the user interface areas that are popular targets for customization:

• Colors and fonts: /nav/common/styles/defaultTheme/custom.css and /nav/common/styles/defaultTheme/defaultTheme.css.
Note: If your users view the product in Arabic, Hebrew, or another right-to-left language, also copy the defaultTheme_rtl.css file.

• Error page: /nav/templates/error.jsp
• Footer: /nav/templates/footer.jsp
• Login page: /nav/templates/login.jsp
• Navigation bar: /nav/templates/header.jsp
  
  
And then paste the file into the appropriate directory. For example:

• To edit the footer and have the same footer be displayed in all of the applications, store the updated footer file in the following directory:

<installdir>\data\shared\customization\common\nav\templates\footer.jsp



• To change the login page of a single application, store the updated login page file in the directory where customizations that are specific to that application are stored. For example, to change the login page of the Files application only, you would store the login.jsp file in the files subdirectory instead of the common subdirectory:

<installdir>\data\shared\customization\files\nav\templates\login.jsp



To determine the appropriate directory to paste the file to, complete the following steps:

1. Figure out the base directory where your customizations should go. The base directory is defined during the installation; it is saved as a WebSphere Application Server variable named CONNECTIONS_CUSTOMIZATION_PATH. By default, the variable is set to <installdir>\data\shared\customization.
   
Do one of the following things:
• To make changes to all of the applications, copy the file into the common subdirectory.
• To make changes to a single application only, copy the file into the subdirectory for that application.
  
The customization directory contains the following subdirectories:

<customizationDir> \common
Stores files to be applied to all of the applications. You most often copy edited files to this directory.

<customizationDir> \activities
Stores files to be applied to the Activities user interface only.
<customizationDir> \blogs
Stores files to be applied to the Blogs user interface only.
<customizationDir> \bookmarks
Stores files to be applied to the Bookmarks user interface only.
<customizationDir> \communities
Stores files to be applied to the Communities user interface only.
<customizationDir> \files
Stores files to be applied to the Files user interface only.
<customizationDir> \forums
Stores files to be applied to the Forums user interface only.
<customizationDir> \homepage
Stores files to be applied to the Home page user interface only.
<customizationDir> \news
Stores files to be applied to the News user interface only.
<customizationDir> \profiles
Stores files to be applied to the Profiles user interface only.
<customizationDir> \search
Stores files to be applied to the Advanced Search user interface only.
<customizationDir> \wikis
Stores files to be applied to the Wikis user interface only.

where <customizationDir> is the customization directory specified in the CONNECTIONS_CUSTOMIZATION_PATH environment variable, which by default is set to <installdir>\data\shared\customization.

2. Add your file to the appropriate subdirectory within the common directory or within a specific application directory.
   
Cascading stylesheets
• To add custom styles to the product, edit the custom.css or custom_rtl.css files.
Note: You only need the custom_rtl.css if your users view the product in Arabic, Hebrew, or another right-to-left language.

• To make extensive changes to the color of the product, edit the defaultTheme.css file.
  
Both CSS files are stored in the following directory:


/nav/common/styles/defaultTheme/



Error page
/nav/templates/error.jsp
Footer
/nav/templates/footer.jsp
Login page
/nav/templates/login.jsp
Navigation bar
/nav/templates/header.jsp

For the menus available from the navigation bar:



/nav/templates/menu/people.jsp

/nav/templates/menu/communities.jsp

/nav/templates/menu/apps.jsp



4. Edit the file stored in the customization directory to make your changes.
5. Test your changes by refreshing the web browser. You might also need to clear your browser cache to see the changes.
6. When you are ready to publish your changes, turn off the customization debugging capability by setting the CONNECTIONS_CUSTOMIZATION_DEBUG WebSphere Application Server environment variable to false.
   
Important: Do not leave the product in debug mode when using it in a production environment. It has a major impact on product performance. Only use debug mode while you are making and testing changes to the user interface during the testing phase. If you forget to turn off debug mode, an error is written to the log to remind you.

7. Using the WebSphere Application Server Integrated Solutions Console, stop and restart each application EAR file.
8. Force all user web browsers to refresh all cached content and display your changes by running the command that updates the product version stamp.
1. Open a command prompt, and then change to the following directory of the system on which you installed the deployment manager:
   
app_server_root\profiles\<dm_profile_root>\bin

where <app_server_root> is the WebSphere Application Server installation directory and <dm_profile_root> is the Deployment Manager profile directory, typically dmgr01. For example, on Windows:



C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\bin



Attention: You must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.

2. Enter the following command to start the wsadmin client:
   
• AIX or Linux:

./wsadmin.sh -lang jython -user <admin_user_id> -password <admin_password> -port <SOAP_CONNECTOR_ADDRESS Port>



• Microsoft Windows:

wsadmin -lang jython -user <admin_user_id> -password <admin_password> -port <SOAP_CONNECTOR_ADDRESS Port>



where:

• <admin_user_id> is the user name of a person in the Administrator role on the IBM WebSphere Application Server.
• <admin_password> is the password of the WebSphere Application Server administrator.
• <SOAP_CONNECTOR_ADDRESS Port> is the SOAP port for the WebSphere Application Server. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
1. Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration -> Deployment Manager.
2. In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
   
For example:

• AIX or Linux:

./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879



• Microsoft Windows:

wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879



3. Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
   
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

4. Enter the following command to check out the IBM Connections configuration files:
   
LCConfigService.checkOutConfig("<working_directory>","<cell_name>")

where:

• <working_directory> is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.

• <cell_name> is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
  
For example:

• AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
• Microsoft Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
  
  
5. Enter the following command to increment the value of the versionStamp property:
   
LCConfigService.updateConfig("versionStamp","<gmt_timestamp>") where <gmt_timestamp> is the GMT time. You can specify an empty string for the time stamp or provide a GMT value string. When you specify an empty string, the client calculates the current GMT time and updates the version stamp with that value. If you choose to provide the time, specify it using the following format: yyyyMMdd.HHmmss and specify the time in GMT. It is best to provide an empty string and let the client format the time stamp. For example: LCConfigService.updateConfig("versionStamp","").

6. After making changes, you must check the configuration files back in and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
   

What to do next

See the following topics for more information about customizing specific areas of the product.

Customizing the navigation bar
You can edit the files that control the content of the IBM Connections navigation bar to add to the bar's functionality. This procedure describes how to add a link to the navigation bar and change the company logo.

Replacing images
Customize the product by replacing images specific to IBM Connections with your own company images.

Adding styles to the IBM Connections stylesheet
You can change the look of the IBM Connections pages to give them a custom look by adding new style definitions in the cascading stylesheet and applying that style to different parts of the product user interface.

Making extensive color and style changes
Edit the defaultTheme.css file to make extensive changes to the product user interface, such as changing the font style and background color.

Customizing the login page
Customize the login pages in IBM Connections to have the appropriate style and content for your organization.

Customizing the footer
You can edit the files that control the content of the IBM Connections footer to improve the footer's functionality.

Customizing the error page
Customize the text on the error pages in IBM Connections.

Customizing the Getting Started tab
Help your users get started with your implementation of IBM Connections by customizing the Getting Started tab that is displayed in the home page.

Customizing product strings
You can replace a word or phrase in the product user interface with terminology that better suits your environment.

Customizing file type icons
Add new file extensions to an existing file type icon, or add a new file extension with a new icon. Custom file type icons display in the Files and Communities applications.

Parent topic: Customizing

Related tasks
Applying common configuration property changes