...

You must extend the DRAgentUI class, that in turn extends the JPanel class. The Workflow Template will create an instance of this class when an agent is dropped or loaded into the workflow. The instance will be kept until the agent is deleted or the workflow is re/unloaded.

Defining the User Interface

The first method to call is the constructor. Here it may be suitable to create all the user interface components to be used in the dialog. However, when the GUI class is constructed, all variables that may be useful are not yet available. These include, the agent name and the Workflow Template environment. If this information is required the initialize method must be used.

Initialization and Deinitialization

The initialize method will be called once after the class is constructed. In this method the agent's name and the Workflow Template environment is available.

The deinitialize method is called once prior to the destruction of the class.

Displaying Configuration Data

The displayConfig method is called every time the agent is double-clicked prior to the dialog display. The method is handed a DRStorable configuration object that is either null, if the agent has not yet been configured, or contains data if it has. The data has to be type casted to the appropriate type before usage.

...

boolean enablePort = !data.getPortFieldInstanceType()
                                     .equals(DRFieldInstanceType.FINAL);
            _portFld.setEnabled( enablePort );

Collecting Data

The collectConfig method collects the configuration from the user interface when OK is clicked.

Validation of User Data

Data entered in the user interface is validated when OK is clicked. The data gets validated against the validation rules specified in the configuration contract. If a validation error occurs a dialog will be displayed containing the message specified in the contract.

It is important that references to Workflow Template environment entities, such as route names and MIM resources, are also validated. The recommended way of designing, for instance route names selection, is to populate a user interface component in the displayConfig method. That way, the user cannot select one that is invalid. However, when the user interface dialog has been validated and confirmed, the user may change names on routes and on agents invalidating the previous validation. To prevent this, such external entities must be validated again in the Inspectable class.

Online Help

DRAgentUI provides support for documentation in JavaHelp format. The JavaHelp *.jar file must be installed with the package. There are many vendors that support generating JavaHelp for different source formats. DTK does not provide a documentation framework but just the ability to show the online help. Please see the official JavaHelp documentation for further information.

Once the JavaHelp *.jar file has been installed, the getHelpIdentifier method should be implemented and return a String array where the first element points out the name of the helpset, e g myagent.hs, and the second element, which is optional, points to an identifier within the help package. The files in the help package must be unique within the system. Therefore it is recommended to put the *.html and image files in a directory named after the agent. It is also recommended that the helpset itself is named after the agent.

The provided APIs to add a DTK developed package to the online-help is described in one of the DTK examples. The result will be that the package appears in the list of help packages that is displayed by selecting the About... option in the Desktop Help menu. See the DTK example: com.digitalroute.devkit.examples.diskcollection.DiskCollectionUserDoc.

See Documentation for Agent Plugins[hide]10.6[/hide] for information about how to create the online help content.

User Interface for Commands

To create a command to interact with an active workflow, the DRCommandUI class should be extended. The Inspectable class must return the class name in the getCommandUIClassName method.

...