The GUI class is used to collect and display the configuration data required for the agent to operate. The user interface will be implemented in a JPanel that the Workflow Editor will put in a dialog. The Workflow Template automatically adds the OK and Cancel buttons.

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.

It is important that all components in the user interface are cleared in this method before they get populated with the supplied data. If not, old data may reside in the Java components if they were previously filled and Cancel was pressed.

A hint is to populate, for instance, combo boxes with data in this method, if they contain environmental data such as database names or route names. This will ensure that these will get updated each time the user interface dialog is displayed. If they are only populated in the constructor, the workflow would have to be reloaded, or a new agent would have to be dropped in order to refresh these components.

If the agent supports update of running configurations, it should be considered which fields should be possible to update. Making fields available or not for update is done in the following way. First check if the inherited method isDynamicUpdate returns true. If that is the case the fields that should not be available for update should be disabled. The fields that should be available for update should be enabled or disabled depending on their field instance types. If a field has a field instance type other than final, it should be enabled. If the field instance type of the field is final it should be disabled.

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.

All methods defined in the User Interface for Commands must be implemented in the same way as the corresponding methods in the DRAgentUI class.