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 Web page. The following sections describe how to create custom host components and widgets. For further information, see Appendix A. HATS Toolkit files.
HATS creates a JavaServer Pages (JSP) page (and writes information to a .jsp file) that reflects host component and widget selections that were made during transformation configuration in the HATS Toolkit. HATS writes this configuration as a set of attributes for the <HATS:Component> tag. The <HATS:Component> tag invokes the code to define host components and specify widget output. To view or edit the transformations in your HATS project, expand the project in the HATS Projects view and look under Web Content/Transformations.
This JSP code example shows the format of the <HATS:Component> tag.
<HATS:Component type="<fully qualified component class name>" widget="<fully qualified widget class name>" row="1" col="1" erow="24" ecol="80" componentSettings="" widgetSettings="" textReplacement="" />
The attribute data of the <HATS:Component> tag determine which host component and widget classes to call and how to present the widget in HTML output. The type attribute of the <HATS:Component> tag specifies which component recognition class to use when recognizing the selected host screen component. The widget attribute specifies which rendering class to use when generating the HTML output. The following list describes the other attributes:
You can use the componentSettings attribute for advanced customization of the component. Surround the entire list with quotation marks. For example, if your command line uses the token >>> instead of ==>, you can pass this component setting value here.
You can use the widgetSettings attribute for advanced customization of the widget. For example, if you want a table to have a certain number of columns, you can pass this widget setting here.
When defining text replacement, if you want to replace certain special characters, you must use the following in the settings:
For example, to replace the string ABC with the string "ABC", specify text replacement as follows:
textreplacement="ABC=@dq.ABC@dq."
HATS performs the following steps to process each <HATS:Component> tag that it encounters in the JSP page.
Each component has a different implementation of the recognize() method. The recognize() method performs pattern recognition logic and host screen data location. Component classes return an array of com.ibm.hats.transform.ComponentElement objects. This array is the logical representation of what was recognized by this component at the specified region with the specified settings.
The drawHTML() method renders the array of component elements as HTML output. The drawHTML() method does this by returning a StringBuffer object that contains its rendering of the supplied component element array. The widget used for the component determines how the component elements are rendered. Two widgets can take the same type of input. For example, the Link widget and the Button widget can both take the same type of input, but their drawHTML() methods generate different HTML content.
Figure 1 illustrates the flow of data from a region of the host screen, through the component and widget, to the Web page.
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:
HATS instantiates the custom component based on the setting of the type attribute of the <HATS:Component> tag.
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 StringBuffer drawHTML() {
StringBuffer buffer = new StringBuffer(256);
HTMLElementFactory factory = HTMLElementFactory.newInstance(
contextAttributes, settings);
return (buffer);
}
The HTMLElementFactory class automatically generates any JavaScript™ needed to present the widget. Refer to the HATS API documentation for detailed information about the HTMLElementFactory class and more examples of its use.
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 HTMLRendererin 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.transform.widgets.FieldWidget
com.ibm.hats.transform.widgets.BIDI.FieldWidgetBIDI
If you want to modify an existing widget, you must extend one of the existing widget classes and override its drawHTML method. Refer to the HATS API documentation for details about widget interfaces and methods.
HATS instantiates the custom widget based on the setting of the widget attribute of the <HATS:Component> tag.
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. Examples are shown below for Web applications:
String ruleReplacement =
RenderingRulesEngine.processMatchingElement(componentElement, contextAttributes);
if (ruleReplacement != null) {
buffer.append(ruleReplacement);
} else {
.
.
.
}
Add the above example to the drawHTML() 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.transform.widgets.VerticalBarGraphWidget"/>
</associatedWidgets>
</component>
</components>
<widgets>
<widget className="com.ibm.hats.transform.widgets.VerticalBarGraphWidget"
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.