You can override the JavaScript files
used by IBM® Connections when
you want to completely change the behavior of a Dojo module and you
need the change to take effect as soon as the module is loaded.
Before you begin
To override JavaScript files,
you must set up an IBM Connections
deployment with the customization directory configured. For information
about locating the customization directory, see Customizing
the user interface. After you have located your customization
directory, create the following subdirectory:
customizationDir/javascriptFiles
placed in this directory will override the JavaScript that is loaded for the main IBM Connections applications. This
directory is loaded first and takes precedence over the content that
is deployed as part of each application. Changes to this directory
take effect immediately except when the JavaScript is loaded and cached statically.
Important: Files in the customization directory are not updated
when interim fixes are installed. If you add an override file and
deploy an interim fix that also affects the file, you must copy that
new change into your override file to maintain your customization.
Procedure
To override JavaScript files,
complete the following steps.
- Identify the JavaScript file
that you want to override.
Most of the JavaScript used by IBM Connections is located inside one of the
web resources JAR files inside the provisioning directory (typically CONNECTIONS_HOME/data/shared/provision/webresources),
or inside the Common.ear file. Each JAR file
corresponds to a base package in Dojo. For example, com.ibm.lconn.core.web.resources
corresponds to the Dojo package lconn.core. Open the JAR file and
locate the JavaScript file
that you want to override.
For example:
- Find com.ibm.lconn.core.web.resources_*.jar inside
the deployed Common.ear file.
- Open the JAR file with a zip program.
- Extract the resources/SearchBar.js file to
a location on your hard disk drive.
- Copy the source file to the customization directory or
create an empty file in the correct location.
For IBM Connections to detect an override JavaScript file, the path
of the file in the customization directory must match the name of
the Dojo JavaScript module.
The name of a module is determined by its path and vice versa. You
can convert the name of a module to a path by replacing all the periods
in the module name with slashes.
For example:
- Using a text editor, open the SearchBar.js file
from the example in step 1.
- Look for a line similar to the following one at the start of the
file:
dojo.provide("lconn.core.SearchBar");
This
line indicates that the name of the module is lconn.core.SearchBar.
- Copy SearchBar.js to the following directory:
customizationDir/javascript/lconn/core/Note: Ensure
that you use the correct case in case-sensitive file systems.
- Make the required changes to the file.
Changes
saved to the file take effect immediately. It is recommended that
you never directly edit the files in your JavaScript customization directory on
a production system. Instead, copy them in with an automated task.
For example:
- Edit SearchBar.js to put an alert statement
at the start of the file:
alert("This file has been customized.");
- Clear your browser's cache and refresh your IBM Connections web application.
The SearchBar.js file
in the example is used by most of the applications, so when you refresh
the page after clearing your browser cache, the alert added in the
previous step should immediately pop up.
What to do next
To remove a JavaScript customization,
delete the file from the customization directory and refresh your
browser cache. Most applications have a very short cache (20 seconds)
before they check again for new JavaScript customizations.
For regular users who are not clearing their browser cache, your changes
are only guaranteed to be active after you update the version stamp
in LCC.xml and restart each affected application,
including Common.ear. For more information, see Required
post-customization step.