By Michael Song, Senior Systems Engineer
IBM Case Manager (ICM) provides an excellent framework for custom widget development. Users can use the widgets alone or alongside out-of-the-box (OOTB) widgets. Custom widgets provide greater functionality including, but not limited to:
- Fully replace OOTB widgets
- Extend OOTB widgets
- Creatively manipulate payload
- Interoperable with both OOTB and custom widgets
No matter what a user’s intent is for widgets, how they are packaged can make a big difference in performance. Packaging includes compressing, consolidating and obfuscating the widget code. Product packaging massively increases performance over development builds and obfuscates any proprietary code.
There are four important processes to understand in product packaging: the Dojo Build, creating a deployment profile, integrating a Navigator plugin package and creating an ANT build script.
Understanding the Dojo Build Process
Dojo includes a build system that applies a set of deployment optimizations on a ready-to-deploy IBM Case Manager widget package. These deployment optimizations usually involve combining client-side assets, removing white space and unnecessary code, removing comments, and obfuscating the code. Here is a comparison between the amount of network requests a user needs to load a widget package before and after the user applies a deployment optimization.
The before and after both represent the same widget code, except that one is for production and the other is for development.
Before: Notice the scrollbar
After: Notice the lack of a scrollbar
As you can see, the number of requests related to the widget package went from 81 requests to five. Load times were six times faster, decreasing from 10 seconds to less than two seconds. These eight seconds could determine whether a customer accepts or rejects the application.
Creating a Deployment Profile
These are the components of a Dojo Build profile (the file called pyramidclient.profile.js in the folder hierarchy above). The following is everything you need in the profile file:
As you can see, the only thing this file needs to contain is a variable named profile. This variable contains a reference to all of the files that will eventually make up your production package.
The basePath property of the profile variable is the root of the build folder. This is usually a temporary folder because it will house all of the build assets in the same place. The releaseDir is where the output of the build goes. Usually, a single file with the combined code from all of the widgets’ JavaScript assets will be the only thing in the release folder. The packages property represents the base JavaScript packages that the widget package requires. My widget package depends on the dojo, dijit, dojox and pyramid packages. The next property of the profile variable defines these packages —the layers property. Each layer holds references to the files that compose that layer. The dojo/dojo layer references all of the dojo, dijit, and dojox properties that my widget packages uses. The pyramid/pyramid layer represent all of my widget assets. The Navigator plugin JavaScript defines the name of the layer.
Setting Up IBM Content Navigator Plugin for Production Build Support
Every IBM Case Manager widget package includes an IBM Content Navigator plugin. This plugin can immediately run JavaScript code with a Navigator desktop. The production build process, discussed in this blog, takes advantage of this fact to load our widget assets when the desktop loads. This loads one compressed file, instead of tens or hundreds of files that a normal widget package has.
In my example project, PyramidCatalogWidgets, I have a Navigator plugin named PyramidCatalogPlugin. The JavaScript that executes on load is called PyramidCatalogWidgetsPlugin.js (defined in the plugin definition as described in a previous blog post, IBM Content Navigator: Plugin Development Basics). Here is everything related to production building from our plugin JavaScript:
The icmContentRoot variable is the name of the folder in the WebContent folder of the Navigator plugin where the production-ready code resides. The paths variable is the location of the plugin resources as seen by IBM Content Navigator’s resource loader. The layer described in the previous section derives from the information here. Finally, the require function loads the compressed JavaScript into the current desktop. That’s all the plugin needs to load your compressed widget files.
Creating an ANT Build
Now that our widget package includes all the necessary files to support a production build, the only thing missing is to actually run the build! This build.xml file runs the Dojo production build described by the profile we defined earlier. There are a lot of steps in the build.xml, so instead of going through the file line by line, here are some important pieces of it.
My build file depends on a copy of Dojo’s source code and access to the installation directories of both IBM Content Navigator and IBM Case Manager client.
The build.xml file begins by defining properties it will need later in the build; think of these like variables in code. After that, it defines targets; think of these like functions in code.
The copy-dependencies target copies all of the necessary assets from all of my dependencies into my temporary folder. This is how the profile we defined earlier actually sees the files that will eventually combine into our production build. I also have an unzip-dojo target that extracts the dojo source code and places it into my temporary folder as well. This is not required as you can just copy an already extracted dojo source into your temporary folder. The copy-source target copies all of the assets associated with my widget package. Finally, clean-before-compress makes sure that the temporary folder is empty before starting any copy operations.
The compress-source target is where the magic happens. Once we copy all of our dependencies, we run a dojo custom build that combines and compresses all of the code. In the build.xml provided, I use the Dojo ShrinkSafe compiler, which Dojo’s source includes. Here is a list of compiler arguments.
The rest of the build.xml is the standard IBM Case Manager Widget build process. The widget packages uncompressed web contents into a WAR, and builds the Navigator plugin. This lets us run our production code (located in the plugin) and our development code if desired (located on the WAR). By simply adding the &debug=true parameter to any IBM Content Navigator URL, we can access development code, allowing for the use of console.log (which the compiler removes) and other development tools.
Users can run the build.xml ANT script anywhere a Java runtime exists, which allows for a variety of automation options. I like to run it in Eclipse.
If everything goes well, you should have a single file in your release folder that contains all of your JavaScript assets. Now your IBM Case Manager widget is ready for deployment!