Bottom of Page | Previous Page | Next Page | Contents

Creating custom components and widgets

Though basic project customization can be accomplished using the Studio, HATS provides a programming environment for further customization of host applications. You can program your HATS project to define new host components or widgets or modify existing host components or widgets.

For a detailed description of host components and widgets, see Understanding HATS key concepts and objects.

The following sections describe how to create custom host components and widgets.

Note:
If you are using a bi-directional (BIDI) code page, please refer to Bi-directional APIs.

Creating custom host components and widgets

HATS creates a JSP page (and writes information to a .jsp file) that reflects host component and widget selections made during transformation configuration in the HATS Studio. 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.

The following JSP code example shows the format of the HATS:Component tag.

<HATS:Component type='<HostComponentType>' 
   widget='<WidgetStyle>' 
   row='1' col='1' erow='24' ecol='80' 
   label='<Data on the screen in region (1,1) to (24,80)>' 
   componentSettings='' widgetSettings='' />

The attribute data of the HATS:Component tag determine what host component and widget classes to call and how to present the widget in HTML output. Refer to HATS:Component tag type and widget attributes for the values of the type and widget attributes. The rest of the attributes are described in the list that follows:

Attribute
Description
row
The starting row position for host component definition.
col
The starting column position for host component definition.
erow
The ending row position for host component definition.
ecol
The ending column position for host component definition.
label
The string to be rendered as HTML text coupled with this host component.
componentSettings
This is a set of key and value pairs that are sent to the component class. When you specify componentSettings values, specify them in the form key:value. If you specify more than one key:value pair, separate them with an "or bar" ( | ). For example, <.. componentSettings="key1:value1|key2:value2" ... >.

The componentSettings attribute can be used for advanced customization of the component. For example, if your command line uses the token ">>>" instead of "==>", you can pass this component setting value here.

Note:
The componentSettings and the widgetSettings need to be combined into a single properties object when they are passed to the recognize() method of the component, and the draw() method of the widget. This allows the component to update any widget settings necessary.
widgetSettings
This is a set of key-value pairs that are sent to the widget class. When you specify widgetSettings values, specify them in the form key:value. If you specify more than one key:value pairs, separate them with an "or bar" ( | ). For example, <.. widgetSettings="key1:value1|key2:value2" ... >.

The widgetSettings attribute can be used 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.

Following is a description of how HATS processes each HATS:Component tag that it encounters in the JSP page.

  1. HATS instantiates a component object based on the type attribute setting.

    If HATS recognizes the value of the type attribute as one of its components, HATS instantiates the appropriate component. If HATS does not recognize the value of the type as one of its components, HATS attempts to instantiate the custom component. You must specify the fully qualified path, like com.company.division.product.MyComponentExtract, and place the class file in either the WEB-INF/classes directory or in a jar file in the WEB-INF/lib directory. For example, if the type attribute is set to SelectionList, HATS instantiates the com.ibm.hats.component.SelectionListExtract class.

    For a list of valid values for the type attribute (and the corresponding host component), see type attribute.

  2. HATS instantiates a widget object based on the widget attribute setting.

    If HATS recognizes the value of the widget attribute as one of its widgets, HATS instantiates the appropriate widget. If HATS does not recognize the value of the widget as one of its widgets, HATS attempts to instantiate the custom widget. You must specify the fully qualified path, like com.company.division.product.MyWidget, and place the class file in either the WEB-INF/classes directory or in a jar file in the WEB-INF/lib directory. For example, if the widget attribute is set to Link, then the com.ibm.hats.widget.LinkWidget class is instantiated.

    For a list of valid values for the widget attribute (and the corresponding widget), see widget attribute.

  3. HATS invokes the component object's recognize() method.

    Each component has a different implementation of the recognize() method. HATS uses the method to initialize several parameters (such as HostScreen, start row, start col, end row, and end col). The recognize() method also performs pattern recognition logic and host screen data location. By default, a class named ComponentElementPool, which contains several ComponentElement objects, stores host screen data that the recognize() method locates.

  4. HATS performs text replacement on the ComponentElementPool returned by the component's recognize() method.
  5. HATS invokes the widget's draw() method.

    The draw() method renders the component as HTML output. The widget passes the writer object to write HTML to the browser. The draw() method passes the ComponentElementPool (from Step 3) to the widget. The HTML output is based on the host screen data stored in a ComponentElementPool object.

Creating a custom host component

You can customize host components by creating a new host component or modifying an existing host component. If you want to create a new host component, you must extend the host component abstract class, com.ibm.hats.component.ComponentExtract, and overwrite the recognize() method. If you want to modify an existing host component, you must extend an existing host component class and overwrite its recognize() method.

HATS provides the following host component classes of abstract class com.ibm.hats.component.ComponentExtract.

When HATS runs a project, it instantiates the custom host component based on the setting of the type attribute of the HATS:Component tag.

The host component class inherits the following methods from the parent class without implementation:

public ComponentElementPool recognize(HostScreen hostScreen, int startRow, int startCol, int endRow, int endCol, String label, Properties settings)
The recognize() method initializes many of the data members that are needed by this class to perform pattern recognition and gathers host screen data from the HostScreen object. This method has a different implementation in each host component class. You should overwrite this method to implement your own pattern recognition logic.

In addition to initializing variables, this method also instantiates an object named hostComponentData (data type com.ibm.hats.common.ComponentElementPool) used to store the host screen data gathered. ComponentElementPool is a container class carrying a vector of ComponentElement objects and other needed host screen information (such as cursor position). ComponentElement describes the general information of host components that widget classes can use to render in HTML.

For a description of the arguments of this method, see the Java documentation for the recognize() method of the ComponentExtract class at the product Web site (http://www.ibm.com/software/webservers/hats).

Creating a custom widget

You can customize widgets by creating a new widget or modifying an existing widget. If you want to create a new widget, you must extend the abstract widget parent class, com.ibm.hats.widget.Widget, and overwrite the abstract draw() method. If you want to modify an existing widget, you must extend one of the following existing widget classes and overwrite one of its methods.

When HATS runs a project, it instantiates the custom widget based on the setting of the widget attribute of the HATS:Component tag.

The widget class inherits the following methods from the parent class without implementation:

public void draw(java.io.Writer out, Object o, Properties widgetSettings)
The draw() method first initializes data members that will be needed to write the HTML code out. Each widget class has its own implementation of the draw() method. You should overwrite this method to create a custom widget.

For a description of the arguments of this method, see the Java documentation for the draw() method of the Widget class at the product Web site (http://www.ibm.com/software/webservers/hats).

Registering your component or widget

After creating a custom component or widget, you must import the source code for the component or widget into the Source folder of your project. Select File > Import > File System to open the Import wizard. In the Import wizard, select the location of your source files in the Directory field. Select the Source folder (or a package in the Source folder) of your project in the destination Folder entry field, and ensure that the Create complete folder structure checkbox is not checked. When your source .java files are imported, they are automatically compiled as .class files and packaged into your HATS project in the webApplication/WEB-INF/classes/ directory path of the Navigator tab of the HATS Studio.

Host components must map to specific widgets. Custom host components can map to any existing widget or to a custom widget. After you import your source code for a custom component or widget into the project's Source folder, you need to edit the ComponentWidget.xml file to add your custom component and associate defined widgets or to associate your custom widgets with components. If you are only adding a custom widget, you must associate the custom widget with a defined component.

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

To edit the ComponentWidget.xml file, click the Navigator tab of the HATS Studio. The ComponentWidget.xml file is shown at the bottom of the Navigator view of your project. The following is a sample of the ComponentWidget.xml file that shows the HATS-supplied visual table component and one of the associated widgets, the vertical bar graph widget.

<ComponentWidgetList>
    <components>
        <component className="com.ibm.hats.component.VisualTableExtract" 
                      displayName="%VISUAL_TABLE_COMPONENT"> 
            <associatedWidgets> 
                <widget className="com.ibm.hats.widget.VerticalBarGraphWidget"/> 
            </associatedWidgets> 
        </component>
    </components>


    <widgets>
        <widget className="com.ibm.hats.widget.VerticalBarGraphWidget" 
                   displayName="%VERTICAL_BAR_GRAPH_WIDGET"/>
    </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 Studio, 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 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 Studio. This name must be unique among the registered widgets. The form of the displayName for a custom widget is simply a string, without the percent sign (%). Spaces are not allowed in the displayName. However, you can use an underscore ( _ ) in place of a space.
widget
Identifies the widgets 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 only contains 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, and make it available to the HATS Studio, 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 recognize the component. 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 Studio. This name must be unique among the registered widgets. The form of the displayName for a custom widget is simply a string, without the percent sign (%). Spaces are not allowed in the displayName. However, you can use an underscore ( _ ) in place of a space.

HATS Studio support for custom components and widgets

HATS Studio can support custom components and widgets as well as existing components and widgets. The graphical user interface (GUI) for inserting or editing the components and widgets is built dynamically based on information provided by the component and widget classes. If you want the GUI to support your custom component or widget, you can override the getPropertyPageCount() method, and must override the registerProperties() method.

public int getPropertyPageCount()
The getPropertyPageCount() method determines how many wizard pages are needed in HATS Studio to customize all of the object's attributes. If you do not override this method, only one wizard page is used to customize all of the attributes. Overriding this method allows you more control over the GUI. For example, you might want to show customizable attributes on more than one page, or some of the attributes might depend on the values of other attributes.

The return value for this method is as follows:

int
The number of wizard pages needed in HATS Studio to fully customize all the attributes of this object.
public Vector getCustomProperties(int iPageNumber, Properties properties, ResourceBundle bundle)
The getCustomProperties() method returns a vector of HCustomProperty customizable property objects. A customizable property is any property of the object that can be edited by a HATS Studio project developer using this component or widget object in a transformation. The components and widgets use the customizable properties to determine what host information to look for, or to determine how data should be displayed.

For a description of the arguments of this method, see the Java documentation at the product Web site (http://www.ibm.com/software/webservers/hats) for the getCustomProperties() method of the Component or Widget class.

public HCustomProperty(String name, int type, String label, boolean isRequired, String[] prefilledValues, String[] prefilledCodes, String defaultValue, ICustomPropertyValidator validator, String helpID)
This is the constructor for a customizable property object.

For a description of the arguments of this constructor, see the Java documentation at the product Web site (http://www.ibm.com/software/webservers/hats) for the HCustomProperty class.

[ Top of Page | Previous Page | Next Page ]