Creating custom components and widgets

HATS provides a set of host components that recognize elements of the host screen and widgets that render the recognized elements. The components and widgets have settings that you can modify if the default settings do not recognize components or render widgets as you want them. If the components, widgets, and the settings that are provided by HATS do not meet your needs, you can create your own custom components or widgets or modify existing host components or widgets. You might want to create your own host component in order to recognize elements of your host screen that the HATS components do not recognize. You might want to create your own widget in order to change the way elements are presented on the page. The following sections describe how to create custom host components and widgets. For further information, see Appendix A. HATS Toolkit files.

Note:
If you are using a bidirectional code page, you can control the direction of widgets and other presentation aspects. See Using the HATS bidirectional API.

Components and widgets properties for RCP applications

In RCP projects, transformations are SWT (Standard Widget Toolkit) composites. RCP transformations have a .java file extension. Transformations can be found in the HATS Projects view under Rich Client Content > Transformations. Transformations are made up of ComponentRendering composites (a specialized composite or panel that transforms a given region using the specified component, widget, and settings). The following code example illustrates the concept:

ComponentRendering rendering1 = new ComponentRendering(this, 0);
	  	rendering1.setComponent("<fully qualified component class name>");
	  	rendering1.setWidget("<fully qualified widget class name>");
  		rendering1.setRegion(new BlockScreenRegion(start_row, start_col, end_row, end_col));
  		rendering1.setComponentSettings(new StringableProperties("<component settings>"));
  		rendering1.setWidgetSettings(new StringableProperties("<widget settings>"));
  		rendering1.setHostScreen(getHostScreen());
  		rendering1.setTransformInfo(getTransformInfo());
  		rendering1.setAutoRender(false);
  		rendering1.setTextReplacement("<text replacement string>");
  		rendering1.render();

In the above example, component settings means a string of component settings and widget settings means a string of widget settings.

These composites are usually constructed and rendered within the render() method of the transformation.

SWT widgets must implement the com.ibm.hats.rcp.transform.renderers.SwtRenderer interface for RCP projects, and SWT widgets have a drawSwt method.

The following SWT widget code sample shows the constructor and drawSwt method:

public MyCustomWidget extends Widget implements SwtRenderer {

    public MyCustomWidget (ComponentElement[] componentElements, Properties settings) {
        super(componentElements, settings);
    }

    public Control[] drawSwt(Composite parent) {
        SwtElementFactory elementFactory = SwtElementFactory.newInstance(getContextAttributes(), 
        getSettings(), parent.getDisplay());

        // Add code here to generate SWT Control objects here

         return controls;  // returns controls added to the specified parent
    }
}

Creating a custom host component

HATS provides a Create Component wizard to help you create custom components. You can start the wizard in several ways:

There are two panels of the Create Component wizard. On the first panel, you provide the name of the project, the name of the new component, and the name of the Java™ package for the component. Optionally, you can select a check box to include stub methods that allow you to define a GUI panel for configuring the settings used by the new component (see HATS Toolkit support for custom component and widget settings for more information). On the second panel, you enter the name you want displayed for the new component in the HATS Toolkit and select the widgets to associate with the component. Widget association is not necessary to complete the wizard. You can define the association of components and widgets later. Refer to Registering your component or widget for more information about associating components and widgets.

The following sections explain the required elements of a custom component that the wizard provides:

If you selected the check box to include HATS Toolkit graphical user interface support methods, enabling you to modify the settings of the component, the Create Component wizard adds the following methods:

See HATS Toolkit support for custom component and widget settings for more information about the methods necessary to support your custom component.

Note:
If you want your component to work properly within Default Rendering, you must set the consumed region (that is, the area of the host screen that has been processed) on each component element that your component returns, before returning the component element. This tells the Default Rendering that this region of the screen has been consumed, or processed, by a host component and should not be processed again. To set the consumed region, use this method:
public void setConsumedRegion(BlockScreenRegion region)
See the HATS API documentation for the ComponentElement class for more information.

Extending component classes

HATS provides a number of host component classes. You can extend any of the host component classes that are found in the ComponentWidget.xml file by replacing the statement public class MyCustomComponent extends Component in the created .java file for the new component with the class name of an existing component. For example:

public class MyCustomComponent 
             extends com.ibm.hats.transform.components.CommandLineComponent
Note:
Bidirectional components are stored in the com.ibm.hats.transform.components.BIDI package. The names of bidirectional classes for components are the same as regular components, but they are followed by "BIDI"; for example, com.ibm.hats.transform.components.BIDI.CommandLineComponentBIDI.

Each HATS component performs recognition of elements of the host screen in the recognize() method. To extend a host component and accomplish the specific recognition task you need, you can use either of these approaches:

To edit the ComponentWidget.xml file, click the Navigator tab of the HATS Toolkit. The ComponentWidget.xml file is shown at the bottom of the Navigator view of your project. See Registering your component or widget for more information about the ComponentWidget.xml file.

Creating a custom widget

HATS provides a Create Widget wizard to help you create custom widgets. You can start the wizard in several ways:

There are two panels in the Create Widget wizard. On the first panel, you provide the name of the project, the name of the new widget, and the name of the Java package for the widget. Optionally, you can select a check box to include stub methods that allow you to define a GUI panel for configuring the settings used by the new widget (see HATS Toolkit support for custom component and widget settings for more information). On the second panel, enter the name you want displayed for the new widget in the HATS Toolkit and select the components to associate with the widget.

The wizard provides the following required elements of a custom widget:

If you selected the check box to include HATS Toolkit graphical user interface support methods, enabling you to modify the settings of the widget, the Create Widget wizard adds the following methods:

See HATS Toolkit support for custom component and widget settings for more information about the methods necessary to support your custom widget.

Extending widget classes

HATS provides a number of widget classes. You can extend any of the widget classes found in the ComponentWidget.xml file by replacing the

public class MyCustomWidget extends Widget implements SwtRenderer

in the created .java file for the new widget with the class name of an existing widget, such as

public class MyCustomWidget extends 
  com.ibm.hats.rcp.transform.widgets.SwtFieldWidget           
Note:
Bidirectional widgets are stored in the com.ibm.hats.transform.widgets.BIDI package. The names of bidirectional classes for widgets are the same as regular widgets, but they are followed by "BIDI"; for example,
public class newBIDIField extends 
  com.ibm.hats.rcp.transform.widgets.BIDI.SwtFieldWidgetBIDI implements SwtRenderer

If you want to modify an existing widget, you must extend one of the existing widget classes and override its drawSwt method. Refer to the HATS API documentation for details about widget interfaces and methods.

Widgets and global rules

Widgets that present input fields should check whether the input field has already been processed by a HATS global rule. When a host screen is received, HATS searches it for host components that match global rules that are defined for that HATS application. When your widget checks whether the input field has already been processed by a HATS global rule, the call returns null if the input field has not been processed. If the input field has already been processed according to a global rule, the call returns the transformation fragment to which the input field has been transformed by the global rule. Your widget should output the fragment rather than processing the component element.

Control control = RcpRenderingRulesEngine.processMatchingElement(parent, fce, 
                  contextAttributes); 
                     if (control == null) {
                          ... 
                      }

Add the above example to the drawSwt() method for the widget.

Registering your component or widget

Registering your custom components and widgets in the ComponentWidget.xml file makes them available for use in the HATS Toolkit, such as in the Insert Host Component wizard.

Host components must map to specific widgets. Custom host components can map to any existing widget or to a custom widget. The Create a custom component or widget wizards register your custom components and widgets in the ComponentWidget.xml file, and associates components and widgets. When using the wizards, if you did not associate your custom component or widget, you need to edit the ComponentWidget.xml file and add the associations. To edit the ComponentWidget.xml file, click the Navigator tab of the HATS Toolkit. The ComponentWidget.xml file is shown at the bottom of the Navigator view of your project.

Note:
If you decide to delete a custom component or widget after it has been registered, simply deleting the source code for the component or widget from the Source folder of your project is not enough to completely remove it. It is still referenced in the registry and there is no programmatic way to remove it. You should remove it from the registry by editing the ComponentWidget.xml file and deleting the references to the component or widget.

Following is an example of the ComponentWidget.xml file that shows the HATS-supplied Field Table component and one of the associated widgets, the vertical bar graph widget.

<ComponentWidgetList>
  <components>
    <component className="com.ibm.hats.transform.components.FieldTableComponent" 
							displayName="Field table" image="table.gif"> 
      <associatedWidgets> 
        <widget className="com.ibm.hats.rcp.transform.widgets.SwtVerticalBarGraphWidget"/> 
      </associatedWidgets> 
    </component>
  </components>


  <widgets>
    <widget className="com.ibm.hats.rcp.transform.widgets.SwtVerticalBarGraphWidget" 
							displayName="Vertical graph" image="verticalBarGraph.gif" />
  </widgets>
</ComponentWidgetList> 

As you can see, there are two sections to this file: components and widgets.

The components section contains the list of all registered components. To register a custom component and make it available to the HATS Toolkit, add a <component> tag and the associated <widget> tags to the ComponentWidget.xml file. You must supply a className, displayName, and the associated widgets.

className
Identifies the Java class that contains the code to recognize elements of the host screen. The class name is usually in the form com.myCompany.myOrg.ClassName.
displayName
Identifies the name by which your custom component is known and how it appears in the list of components in the HATS Toolkit. This name must be unique among the registered components. The form of the displayName for a custom component is simply a string. Spaces are allowed in the displayName.
image
The image attribute identifies the image to use for your component when it appears in the HATS Toolkit.
widget
Identifies the widgets that are associated with this component. There must be a separate <widget> tag for each associated widget. All of the <widget> tags for the component must be defined within the <associatedWidgets> tag and its </associatedWidgets> ending tag. The <widget> tag within the <associatedWidgets> tag contains only the className attribute, which identifies the Java class that contains the code to link the widget to the component. The class name is usually in the form com.myCompany.myOrg.ClassName.

The widgets section contains the list of all registered widgets. To register a widget, link it to a component, make it available for use in the HATS Toolkit, and add a <widget> tag to the ComponentWidget.xml file. You must supply a className and a displayName.

className
Identifies the Java class that contains the code to render the widget. The class name is usually in the form com.myCompany.myOrg.ClassName.
displayName
Identifies the name by which your custom widget is known and how it appears in the list of widgets in the HATS Toolkit. This name must be unique among the registered widgets. The form of the displayName for a custom widget is simply a string. Spaces are not allowed in the displayName. However, you can use an underscore ( _ ) in place of a space.

HATS Toolkit support for custom component and widget settings

You can provide GUI support for modifying the settings of your custom component and widget. This is useful if other developers will be using your custom component or widget or you want to easily test different combinations of settings using the preview features available in the HATS Toolkit. The base component and widget classes implement the ICustomPropertySupplier interface. This interface allows a component or widget to contribute setting information to the HATS Toolkit. This information is used to render a panel by which the settings of the component or widget can be modified. Not all settings need to be exposed in the GUI.

The getCustomProperties() method returns a vector of HCustomProperty customizable property objects. Each HCustomProperty object represents a setting of the component or widget. The HATS Toolkit renders each HCustomProperty objects based on its type. For example, an object of type HCustomProperty.TYPE_BOOLEAN is rendered as a GUI checkbox.

The following sample code demonstrates how a widget can provide GUI support for three of its settings (mySetting1, mySetting2, and mySetting3):

// Returns the number of settings panels (property pages) to be contributed 
//by this widget.  The returned value must be greater than or equal to 1 if 
//custom properties will be supplied via the getCustomProperties() method.  
public int getPropertyPageCount() {
         return 1;     
}

// Returns a Vector (list) of custom properties to be displayed in the GUI 
//panel for this component or widget.     
public Vector getCustomProperties(int iPageNumber, Properties properties, 
         ResourceBundle bundle) {
         Vector props = new Vector();          

// Constructs a boolean property that will be rendered as a checkbox         
HCustomProperty prop1 = HCustomProperty.new_Boolean("mySetting1", 
                "Enable some boolean setting", false, null, null);         
props.add(prop1); 

// Constructs a string property that will be rendered as a text field         
HCustomProperty prop2 = HCustomProperty.new_String("mySetting2", 
                "Some string value setting", false, null,
                 null, null, null);         
props.add(prop2);          

// Constructs an enumeration property that will be rendered as a drop-down         
HCustomProperty prop3 = HCustomProperty.new_Enumeration("mySetting3", 
                 "Some enumerated value setting", false,
                 new String[] { "A", "B", "C" }, new String[] 
                 { "Option A", "Option B", "Option C" }, null, null, null);
props.add(prop3);          

return props;     }
Widget GUI

The values supplied by the user of the custom component or widget will be available in the componentSettings Properties object passed into the recognize() method of the component or the widgetSettingsProperties object passed into the constructor of the widget. The getCustomProperties() method may be called during runtime to collect default values for settings.

For a description of the arguments and usage of these methods, see the HATS API documentation for the HCustomProperty class.