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.
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
}
}
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 one of the HATS host components is very similar to what you need, it will be easier to extend that component. See Extending component classes for more information.
public MyComponent(HostScreen hostScreen) {
super(hostScreen);
}The constructor should initialize parameters that the recognize() method
will require, based on the host screen object.public ComponentElement[] recognize(BlockScreenRegion region,
Properties settings)The recognize() method
has a different implementation in each host component class. It accepts
the region and settings passed to it and returns an array of component
element objects. You should implement this method to implement your
own pattern recognition logic.
The recognize() method must return an array of ComponentElement objects, as defined in com.ibm.hats.transform.elements.ComponentElement. Each HATS component returns a slightly different set of elements that extend ComponentElement. For example, the SelectionListComponent returns an array of SelectionComponentElement objects. This array of component elements is passed to the specified widget, so be sure to return an array of elements that can be accepted by the widget you want to use.
For a description of the arguments of this method, refer to the HATS API documentation for the recognize() method of the Component class.
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:
public int getPropertyPageCount() {
return (1);
}public Vector getCustomProperties(int iPageNumber, Properties properties,
ResourceBundle bundle) {
return (null);
}public Properties getDefaultValues(int iPageNumber) {
return (super.getDefaultValues(iPageNumber));
}See HATS Toolkit support for custom component and widget settings for more information about the methods necessary to support your custom component.
public void setConsumedRegion(BlockScreenRegion region)See the HATS API documentation for the ComponentElement class for more information.
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
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.
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:
See Extending widget classes for more information.
public MyCustomWidget(ComponentElement[] arg0, Properties arg1) {
super(arg0, arg1);
}
public Control[] drawSwt(Composite parent) {
SwtElementFactory elementFactory =
SwtElementFactory.newInstance(contextAttributes,
settings, parent.getDisplay());
// Construct controls using SwtElementFactory instance
return new Control[0];
}
The SwtElementFactory should be used to construct SWT controls since it handles associating new controls with the underlying data model and applying the styles of the associated template.
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:
public int getPropertyPageCount() {
return (1);
}public Vector getCustomProperties(int iPageNumber, Properties properties,
ResourceBundle bundle) {
return (null);
}public Properties getDefaultValues(int iPageNumber) {
return (super.getDefaultValues(iPageNumber));
}See HATS Toolkit support for custom component and widget settings for more information about the methods necessary to support your custom widget.
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 SwtRendererin 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
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 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 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.
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.
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.
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; }

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.