Extending Cumulus Web Client
Shortly after we released the new Cumulus Web Client, we introduced the possibility to brand it . You can upload your own logo and change the name of the Web Client so that it matches your corporate identity.
You could also define a custom footer, e.g. to include links to your internal help desk or intranet. You are also able to set a message of the day, e.g. to inform your users about a scheduled maintenance or an upcoming Cumulus training.
With the Cumulus 9.2 release, we provide a Web Client SDK allowing you to extend the functionality by implementing a Web Client plugin. In its first version, a plugin can define a custom toolbox action. The toolbox is a central element in Web Client’s UI, providing access to the different functions you can invoke on a set of files, containers or collections. In the future, a plugin will be able to hook into additional parts of the Cumulus Web Client.
Anatomy of a toolbox action
Before you can implement your own toolbox action, you must understand the anatomy of toolbox actions. A toolbox action has a localized title, an icon, and a localized description shown as a tooltip when hovering over it.
However, before a toolbox action shows up, you need to define in which context it should be visible. For example, you might require the user to have certain permissions. Or you might want to show your action only if at least one file is selected, but not if files and containers are selected.
When a toolbox action is clicked, you might want to ask the user for additional input. Therefore, you can optionally define a form with input fields and selection boxes, which will be shown to the user in a modal dialog when the user invokes your action. We call this the preparation dialog.
The list of selected items (files, containers, collections) plus any optional additional input from the user is forwarded to the execution logic of your toolbox action. That’s the place where you implement the business logic and process the input provided. This function is executed asynchronously, meaning the Web Client UI is not blocking till execution was finished. Instead, the user can continue with his work while your logic gets executed. You can inform the user about the progress by displaying progress information in the notifications area of Web Client. When your execution logic completes, you can show a notification, too.
Compiling the sample project
After downloading the Web Client SDK, extract it and take a look at what’s included:
- doc/ – contains the JavaDocs of the Web Client Plugin API
- import/ – libraries with Cumulus Java Classes and Web Client Plugin API
- src/ – sample plugin implementing two toolbox actions
- pom.xml – Maven project file to compile sample plugin
In my view, the most important file is pom.xml. If you have installed latest stable release of Apache Maven, you can directly switch to a command line to compile the sample plugin by issuing the following command:
On first run, this might trigger a download of some Maven plugins and dependencies. After Maven run completes, take a look at the newly created target/ folder. It contains two JAR files. You always want to use the larger one, which includes all required dependencies. In case of the sample plugin, this file is called:
To get a better understanding of what happened, extract the generated JAR file and compare the content also against what was defined in the pom.xml project file:
- bundles/ – contains the property file used for localizing all user visible strings
- com/ – contains all compiled classes of your plugin and toolbox actions
- images/ – contains SVG icons for both toolbox actions
- javax/ & org/ – contains class files of Xerces XML parser (a dependency defined in pom.xml)
- license/ – license files of all dependencies
- META-INF/ – contains MANIFEST.MF file defining main class of your plugin as defined in pom.xml
When reviewing pom.xml, you will notice that Cumulus Java Classes, Web Client Plugin API, Servlet API, and Log4J are required dependencies during compilation, but those libraries should not be included in the plugin JAR itself.
Deploying the sample plugins
To deploy the newly packaged plugin, browse to your Web Client web app deployed in a Java servlet container. Within the web app, find the folder WEB-INF/ and create a new sub-folder plugins/. Copy the larger JAR file to this folder and restart the web app.
During startup, Web Client is scanning the plugins/ folder and instantiates the entry classes according to the main class entry in MANIFEST.MF files. To see your plugin in action, login to Web Client, go to the “Content” page and select at least one file. You should now see two new toolbox actions as shown in the screenshot below:
The move to catalog sample shows how to work with Cumulus Java Classes in the execution logic of your custom action. It moves the selected files to another catalog. The user selects the target catalog after clicking on the action in the preparation dialog. This only works if the user has access to a second catalog and can move files.
The hello example demonstrates all possibilities of the Cumulus Web Client Plugin API. The shown preparation dialog demos the different form elements.
As you can see from the screenshot above, besides various form elements, you can also have additional buttons to close the dialog.
The hello action doesn’t do anything useful besides waiting some time. It regularly updates a progress bar to demonstrate this interface, too.
While the hello action is executed, you can continue your work in Web Client and for example open another page. When execution was completed, the hello action will add a notification to the notification area.
What can I do in a toolbox action?
Everything! The execution logic of a toolbox action can do whatever you implement. You are not limited to Cumulus functionality, but you can make use of any kind of Java library you need. Just declare a dependency to your favorite library in the pom.xml file and recompile your plugin. Maven will download the library and include it in the generated JAR file.
For example, you could query an external SQL database in your execution logic and store the results in the metadata of the selected files using Cumulus Java Classes.
Using an IDE and debugging your code
Even though hardcore hackers only work with command line tools and edit their files with VIM or Emacs, some of us prefer the comfort of modern IDEs such as Eclipse, IntelliJ Idea, and Netbeans. You can easily import the sample code into those IDEs by simply opening the provided pom.xml file. All modern Java IDEs provide strong Maven support and can discover all dependencies automatically.
Remote debugging is possible, too. You need to add the necessary debug parameters to the startup scripts of your servlet container so that it listens to debugging sessions. In case of Apache Tomcat, simply start it with the following command:
catalina jpda start
Take note of the remote debugging port printed during startup (port 8000 in my case). After Web Client was started, you should be able to connect a debugging session from within your IDE using the remote debugging port. If you configured everything correctly, you are now able to set breakpoints and inspect variables while stepping through the code of your plugin.
Now it’s your turn!
You now have all the tools you need to get started. I suggest you start with one of our sample toolbox actions and change it to your needs. Use the refactoring tools of modern IDEs to quickly rename the package and artefact structure so that it matches your naming conventions.
Make sure to give us feedback on the Web Client Plugin API via our customer community. We would be very much interested to learn what kind of toolbox actions you implemented and if there were any obstacles. Also let us know into which other parts of the Cumulus Web Client besides toolbox you would like to hook into so that we can consider it in future extensions to the Web Client Plugin API.