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.
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:
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.
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.
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.
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.
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.
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.
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:
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).
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:
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).
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.
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.
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.
The return value for this method is as follows:
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.
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.