Extend JavaScript in Connections

Overview

To aggregate and serve JavaScript files, Connections uses the shared resources WAR file...

connections.web.resources.war

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. 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 Connections...

• Put the JavaScript files into an OSGi bundle

  A JAR file with a special MANIFEST.MF file and some directories

• Deploy the bundle into Connections

• Link the JavaScript to ensure it is loaded at the same time as the rest of the JavaScript in Connections.

The easiest way to extend the JavaScript used in Connections is to start with a sample bundle, add files to it, and deploy it in the Connections environment.

To change a file in the JAR file, stop the Common.ear file, update the JAR file, and then restart the EAR file. We 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.

Complete the following steps to extend the JavaScript used in Connections using a sample bundle.

1. Download the following sample bundle:
   com.mycompany.example_1.0.0.jar

2. Deploy the sample bundle.

   1. Locate the web resources provisioning directory for Connections. The installer creates this directory at the following location:
      CONNECTIONS_HOME/data/shared/provision/webresources

      Contains many different JAR files, including at least one for each application, and utility bundles.

   2. Copy the sample bundle into the webresources directory.

   3. Restart the Common.ear file.

   4. Enter the following URL in the 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.

3. Add files to the sample bundle.

   We 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 the web browser:

   http://server/connections/resources/web/com.mycompany.example/

   1. Stop Common.ear.

   2. Add the new JavaScript, HTML, image, or CSS files into the JAR file in the resources/ directory.

   3. Restart Common.ear.

   4. Clear the browser cache and access the new file directly by viewing it on the server.
      For example:
      http://server/connections/resources/web/com.mycompany.example/newfile

4. Ensure the JavaScript is loaded when an 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 to load your custom files after.

   Most customizations need to be loaded at a certain time, along with other Connections JavaScript. To ensure that your module is loaded, 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 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 we can see in Connections.

5. Restart Common.ear to pick up the changes in the plugin.xml file.

6. Change the name of the bundle.

   1. In the META-INF/MANIFEST.MF file, change Bundle-SymbolicName and, optionally, Bundle-Name.

      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 the JavaScript to be loaded.

   2. Change each Dojo JavaScript module in the resources/ folder to have a different base package. Alternatively, we can change the <alias> in plugin.xml to define an arbitrary base package.

      When Connections tries to look up the 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 Connections cannot load the JavaScript.

   3. Change the name of the JAR file to new-name_version.jar.

      When you rename the JAR file, ensure 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, Connections will not be able to load the JAR file.

   4. Remove the old JAR file from the webresources directory, and copy the new JAR file into the directory.

      We can also reference custom bundles that are saved to another location outside the customization directory by using a customresources.link file that is saved in the webresources directory. The customresources.link is a text file that specifies a list of additional directories to search. We can specify as many directories as you like in the file, for example:

      /local/opt/myCustomBundles
      C:\customBundles

   5. Restart Common.ear.

   6. Check the 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

Parent topic:
Overriding and extending JavaScript in Connections

Related:

Overriding JavaScript in Connections