Creating custom page widgets and actions

Before you begin

Case Client and the page widgets that are run in IBM® Content Navigator. Therefore, before you create custom widgets, you must set up your development environment to customize and extend IBM Content Navigator. For more information, see section 5.1, "Preparing for IBM Content Navigator customization," in the IBM Redbooks® publication Customizing and Extending IBM Content Navigator .

About this task

The following procedure provides an overview of the steps that are required to create a custom page widget. For instructions and samples, see Creating custom widgets in IBM Case Manager using Case Manager JavaScript API .

To create a custom page widget:

1. Create a web project that contains the following folders for your widget package:

   Folder	Content
   ProjectName/ProjectNamePlugin	Contains the files that are used to create the JAR file for the IBM Content Navigator plug-in.
   ProjectName/ProjectNamePlugin/src/PackageName	Contains the files that are used to create the JAR file for the IBM Content Navigator plug-in.
   ProjectName/ProjectNamePlugin/src/PackageName/WebContent	Contains the CSS files, the main JavaScript plug-in file and related files such as images. Note: In the JAR file, update the relative path with the absolute path for the custom widget application that is installed on the workflow server that corresponds to your custom widget EAR.
   ProjectName/ICMRegistry	Contains the JSON files that are used to register the widget package and the page widgets. Optionally, this folder can contain folders for: Images that are used in the widget package, such as icons or thumbnails. Translated resource files
   ProjectName/ProjectNameWidget	Contains the files that are used to define the user interface for a custom page widget.
   ProjectName/ProjectNameWidget.PackageName/pgwidget	Contains the files that are used to define the custom page widgets.
   ProjectName/ProjectNameWidget.PackageName/action	Contains the files that are used to define the custom actions that are used by the custom page widgets.

   For more information, see section 5.2.1, General structure of a plug-in project, in the IBM Redbooks publication Customizing and Extending IBM Content Navigator .

2. Create the registry files and place them in the ICMRegistry folder:
   1. Create a file called Catalog.JSON.
      This JSON-format file identifies the widget category and the page widgets that the package contains.
   2. For each page widget, create a definition file in JSON format that identifies the properties, toolbars, menus, and actions that can be configured for the widget.
3. Create a self-contained widget that is based on Dojo to represent the user interface component of the custom page widget.

   Do not include the business logic for the page widget in this file. Instead, use this file to define the visual representation of the widget that is displayed to users in Case Client. In addition, include a destroy method to be called to close the widget when the page that contains the widget is closed.

4. Create a wrapper file that defines a custom class to represent the page widget.

   You define the wrapper JS file in the Dojo Asynchronous Module Definition (AMD) format by calling the Dojo.declare() method.

   The class for the page widget must:

   • Extend the user interface component that you created.
   • Mix in the icm.base.BasePageWidget class. This class mixes in the icm.base._EventStub class that includes methods for publishing and broadcasting events.
   • If the page widget contains a toolbar or menu that uses the workflow action framework, mix in the icm/base/BaseActionContext class.
   • If the page widget must interact with other page widgets to perform tasks such as adding or saving cases, tasks, or work items, participate in coordination.
5. If your page widget uses custom actions, define a class for each action.

   A workflow action extends the ecm.model.Action class. To make a standard IBM Content Navigator action work in IBM Business Automation Workflow, the com.ibm.ecm.extension.PluginAction implementation must override the getAdditionalConfiguration method to provide the action definition.

   To define the class for a custom action, you extend the icm.action.Action class. Implement an execute method in the class to define the operation logic for the action. Optionally, you can implement an isEnabled method and an isVisible method to check the state.

   Tip: You can customize the dialog boxes that are used to display error messages and confirmation messages for your custom actions. To override the default dialog boxes, use the showConfirmationDialog method and showErrDialog method that are defined for the icm.action.Action JavaScript class.
6. Create the IBM Content Navigator plug-in for the widget package.
   The plug-in contains the web browser logic that enables users to call the page widget.

   For more information, see section 5.2.2, Create a plug-in project from the samplePlugin code, in the IBM Redbooks publication Customizing and Extending IBM Content Navigator .

7. Create a widget package that contains the custom page widgets and actions:
   1. Create a build.xml script that builds the following components:
      • An EAR file that contains the runtime code that implements the page widgets and actions.
      • The ICMRegistry folder that includes the page widget definitions.
      • A JAR file that contains the IBM Content Navigator plug-in, including the bootstrap file and the action definitions.
      • In the JAR file, update the relative path with the absolute path for the custom widget application that is installed on the workflow server that corresponds to your custom widget EAR.
   2. Create a compressed file that contains the files and folders from the previous step.
8. Create a MANIFEST.MF file that is in the ProjectNamePlugin/src/META-INF folder that contains the following reference to the Custom plug-in .js file:

   Plugin-Class: Custom plug-in

9. In Case Builder, use Page Designer to add the custom page widget to a page and configure the properties and actions for the page widget.
10. Deploy and test the solution.