Technical Blog Post
Abstract
Creating Custom Widgets in ICM 5.2.1 using ICM Javascript API
Body
Introduction
You can customize Case Manager Client by creating your own page widgets. In addition, you can customize the page widgets that are provided by IBM Case Manager to tailor them to your needs.
Audience
This tutorial is intended for developers who create Case Manager Client applications and for business analysts who design case management solutions.
Prerequisites
Before you begin this tutorial, you should be familiar with the programming model for Case Manager Client. For an overview of this model, see the article Introduction to the IBM Case Manager JavaScript API (ICM52JavaScriptAPI.pdf).
You should also be familiar with the concepts and programming models that are used to build plug-ins for IBM Content Navigator. For more information, see Developing applications with IBM Content Navigator in the IBM FileNet P8 Version 5.2.1 Information Center.
To develop a widget, you must know how to use the following technologies:
- Dojo (Version 1.9.3 is packaged with IBM Content Navigator 2.0.3)
- Extensible Markup Language (XML)
- HyperText Markup Language (HTML)
- Java 2 Enterprise Edition (J2EE)
- JavaScript
- Eclipse
Downloading the sample widget package
The lessons in this tutorial are based on a custom widget package that is available in the customWidget.zip file provided with this article. The tutorial uses the sample widget package to illustrate how you build, package, and use custom page widgets and actions.
The sample package includes two actions and three widgets:
| Name | Description |
|---|---|
| CustomAddCaseAction | This action adds a case from an arbitrary solution and case type. It shows how you can build a custom action based on an existing IBM Case Manager action base class and action definition file. |
| CustomAddToAttachmentAction | This action adds a case document as an attachment. It shows how a custom action interacts with the action context to retrieve the context information and publish an event. |
| CustomPageWidget | This simple page widget shows the basic definition file format and the source code structure for defining a page widget. This widget also shows how to create a toolbar and a pop-up menu for a widget. |
| CustomSearchWidget | This page widget dynamically loads the case properties to search on using search API. It only searches on single value properties, not multi-value properties. It also does not search on date time fields. |
| CommentWidget | This page widget shows how to embed the Comment dialog box in a page widget. The widget coordinates with Case Toolbar page widget to save a case comment when the user saves a case. The widget also supports marking or clearing the dirty state of the page as case comments are added and saved. |
| CustomCaseInfo | This page widget provides a custom Case Information page widget that uses the CustomAddToAttachmentAction action. The widget shows how to specify a model object as part of the action context. |
| CustomViewer | This page widget shows how to customize an IBM Case Manager page widget. |
The sample package uses the following naming conventions:
| Name | Description |
| ICMCustomWidgets | The name of the package |
| ICMCustomPlugin | The name of the IBM Content Navigator plug-in |
| ICMCustomWidgets | The name of the web application |
| com.ibm.icm.extension.custom | The common package name of the Java class |
| icm/custom | The common package name for custom Dojo module |
IBM Case Manager 5.2.1 Custom Widget Best Practices
IBM Case Manager Page widgets are essentially Dojo based widgets also known as dijits that run inside of a Dojo based Page container framework. A normal Dojo dijit is a widget that is part of Dojo's User Interface (UI) library. In addition to the standard UI features, IBM Case Manager Page widgets offer two things:
- Events that can be used for wiring
- Widget settings
These two features allow the Business Analyst to dynamically adjust page and widget behavior with little to none programming skills.
The following guidelines should be kept in mind when creating a Page widget:
UI dijit
- First create a normal Dojo dijit which is responsible for rendering the user interface and handling user interaction to collect user input.
- Ideally, this dijit should be a designed as a reusable component that takes in a context and renders itself.
- The UI dijit should not access any IBM Case Manager Page Container related APIs, which will limit its usage to only the IBM Case Manager Case Client.
- Separating the UI dijit from the Page widget layer will allow you to reuse this dijit in a custom application or plug-in built on top of IBM Content Navigator.
- The dijit could also be reused in a non-ECM environment if it doesn’t use any ECM related API.
- The dijit should also expose necessary dojo methods/events to allow interested parties (the page widget wrapper or other custom widgets) to exchange data or get notified by user interaction.
Page widget
- After the dijit corresponding to the user interface is ready, you will need to create a Page widget wrapper that extends this UI dijit and converts it into an IBM Case Manager Page widget.
- The page widget wrapper should be the place where the page container related code resides.
- The page widget wrapper accepts widget settings from the page container and passes them to the underlying dijit.
- It should also connect to Dojo events exposed on the dijit to be notified of user actions.
Event Listener (Optional)
As an optional separation, you could separate the event handling logic from the page widget when the event handling gets too complex. For e.g. if you have complex logic to pre-process or post-process the event data, you can create a separate event listener object which holds the event handler implementations. The page widget could then delegate the event handling logic to the event listener object.
-----------------------------------------------------------------------
The above is the introduction section of the article. For the complete details of the article please download the complete pdf content of the article (ICM52CustomWidgets v2.pdf).
For the supporting zip file, please download the
UID
ibm11281064