You can extend the JavaScript files
used by IBM® Connections when
you want to add new functionality, widgets, or scripts to the product.
Before you begin
IBM Connections uses
the shared resources WAR file, connections.web.resources.war,
to aggregate and serve all JavaScript files.
This WAR file is based on the OSGi extension model, which allows new
capabilities to be added to a system via a plug-in mechanism. IBM Connections leverages this mechanism
to provide the following capabilities: - Expose custom JavaScript in
a new Dojo module package
- Ensure that custom JavaScript loads
when another module is loaded
To extend the JavaScript used
in IBM Connections, first you
must put your JavaScript files
into an OSGi bundle (a JAR file with a special MANIFEST.MF file
and some directories), and deploy the bundle into IBM Connections. Then, you need to link your JavaScript to ensure that
it is loaded at the same time as the rest of the JavaScript in IBM Connections.
The easiest way to extend
the JavaScript used in IBM Connections is to start with
a sample bundle, add files to it, and deploy it in your IBM Connections environment.
If you want
to change a file in the JAR file, stop the Common.ear file,
update the JAR file, and then restart the EAR file. You can also unzip
the JAR file into a new directory with the same name as the JAR file
minus the .jar extension and make changes there,
but you might have to restart the EAR file to see new versions of
files appear.
Procedure
Complete the following steps to extend the JavaScript used in IBM Connections using a sample bundle.
- Download the following sample bundle:
com.mycompany.example_1.0.0.jar
- Deploy the sample bundle.
- Locate your web resources provisioning directory for IBM Connections. The installer creates
this directory at the following location:
CONNECTIONS_HOME/data/shared/provision/webresources This directory contains many different JAR files, including
at least one for each application, and utility bundles.
- Copy the sample bundle into the webresources directory.
- Restart the Common.ear file.
- Enter the following URL in your web browser:
http://server/connections/resources/web/com.mycompany.example/readme.txt
You
should see the readme.txt file from the JAR in
the resources/ folder display in the browser
window.
- Add files to the sample bundle.
You can update
the JAR file by adding new files. Put the files in the
resources/ directory
and view the contents by entering the following URL in your web browser:
http://server/connections/resources/web/com.mycompany.example/
- Stop Common.ear.
- Add your new JavaScript,
HTML, image, or CSS files into the JAR file in the resources/ directory.
- Restart Common.ear.
- Clear your browser cache and access the new file directly
by viewing it on your server.
For example:http://server/connections/resources/web/com.mycompany.example/newfile
- Ensure that the JavaScript is
loaded when an IBM Connections
module is loaded by updating the plugin.xml file
to add a new <dojoModuleBinding> element. Set the "to" attribute
in the binding to the name of the class that you want to load your
custom files after.
Most customizations need to be loaded
at a certain time, along with other IBM Connections JavaScript. To ensure that
your module is loaded, you must update plugin.xml to
add a new <dojoModuleBinding> element.
In the example, "com.mycompany.example.demonstration"
(demonstration.js) is bound to a file that all IBM Connections applications load, bundle_common.js.
Whenever any application loads bundle_common.js, demonstration.js will
also be loaded. The demonstration module prints a line to the Firebug
console, which you can see in IBM Connections.
- Restart Common.ear to pick up the
changes in the plugin.xml file.
- Change the name of the bundle.
- In the META-INF/MANIFEST.MF file,
change Bundle-SymbolicName and, optionally, Bundle-Name.
Note: Do
not remove the ;singleton:=true text at the end of
the line. This text is necessary for the plugin.xml file
to get parsed and your JavaScript to
be loaded.
- Change each Dojo JavaScript module
in the resources/ folder to have a different
base package. Alternatively, you can change the <alias> in plugin.xml to
define an arbitrary base package.
When IBM Connections tries to look up your modules,
it will first look for the base package (the name of the bundle, or
the <alias value="" /> defined in plugin.xml)
and then look inside the resources/ folder. However,
the dojo.provide(...) statement inside each JavaScript file must match
the expected name or IBM Connections
cannot load your JavaScript.
- Change the name of the JAR file to new-name_version.jar.
Important: When you rename the JAR file, ensure
that the version that is described by Bundle-Version in MANIFEST.MF matches
the version at the end of the JAR name. If they do not match, IBM Connections will not be able
to load your JAR file.
- Remove the old JAR file from the webresources directory,
and copy your new JAR file into the directory.
Optional: You can also reference custom bundles
that are saved to another location outside your customization directory
by using a
customresources.link file that is
saved in your
webresources directory. The
customresources.link is
a text file that specifies a list of additional directories to search.
You can specify as many directories as you like in the file, for example:
/local/opt/myCustomBundles
C:\customBundles
- Restart Common.ear.
- Check your changes by accessing the following URL from
your browser. You should see the same file that is in the
JAR file.
http://server/connections/resources/web/new name/readme.txt