Create custom components and widgets

HATS provides a set of host components that recognize elements of the host screen, and widgets that render the transformed elements on the Web page. If the components and widgets 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.

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

If you add custom components or widgets to your HATS application, modify the WAR classloader policy of your HATS application on WebSphere Application server when you deploy your HATS application. You must also modify the WAR classloader policy of your HATS application on the local server if you use Run on Server to test your custom components or widgets. Refer to HATS Getting Started for more information.

The components and widgets in HATS Version 5 have been redesigned to make them easier to extend. If you have created custom components or widgets based on HATS Version 4, you can continue to use them, but their use is deprecated. Consider extending HATS Version 5 components or widgets to achieve the same effect with greater reliability.

 

Component and widget properties in the HATS:Component tag

HATS creates a JavaServer Pages (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. To view or edit the transformations in your HATS project, expand the project in the HATS Project 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="" 
   applyGlobalRules="true|false" markup="html" textReplacement="" 
   applyTextReplacement="true|false" />

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. This list describes the other attributes:

Attribute
Description

row

The starting row position for host component recognition.

col

The starting column position for host component recognition.

erow

The ending row position for host component recognition. You can specify -1 to mean the last row on the host screen.

ecol

The ending column position for host component recognition. You can specify -1 to mean the last column on the host screen.

componentSettings

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" ... >.

Use the componentSettings attribute 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.

widgetSettings

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 ( | ). Surround the entire list with quotation marks. For example, <... widgetSettings="key1:value1|key2:value2" ... >.

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.

HATS follows these steps to process 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. For example, if type is set to SelectionList, HATS instantiates an object of type com.ibm.hats.transform.components.SelectionListComponent.

    If HATS does not recognize the value of 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.MyComponentComponent. If you want to be able to work with your custom component in HATS Studio, place the class file in either the WEB-INF/classes directory or in a jar file in the WEB-INF/lib directory. If you prefer, you can import the source (.java) file into the project's source directory. If you have tested your custom component and you do not wish to work with it in HATS Studio, make the jar file available to your HATS application when it is installed on WebSphere Application Server.

  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. For example, if widget is set to Link, HATS instantiates an object of type com.ibm.hats.transform.widgets.LinkWidget.

    If HATS does not recognize the value of 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. If you want to be able to work with your custom widget in HATS Studio, place the class file in either the WEB-INF/classes directory or in a jar file in the WEB-INF/lib directory. If you prefer, you can import the source (.java) file into the project's source directory. If you have tested your custom widget and you do not wish to work with it in HATS Studio, make the jar file available to your HATS application when it is installed on WebSphere Application Server.

  3. HATS invokes the recognize() method of the component object.

    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.

  4. HATS performs text replacement by calling the doTextReplacement() method on each ComponentElement object in the array returned by the recognize() method of the component object.
  5. HATS invokes the drawHTML() method of the widget. If an applicable drawHTML() method cannot be found, the widget's draw() method is called - this method simply returns (unless overridden by subclasses) the concatenation of the toString() calls on each component element in the component element array returned by the component.

    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 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.

Figure 1. Flow of data from host screen to Web page
Flow of data from host screen to Web page

 

Create a custom host component

You can customize host components by creating a new host component or extending an existing host component. To create a new host component, you can extend either the host component abstract class, com.ibm.hats.transform.components.Component, or one of the existing HATS host components. If one of the HATS host components is very similar to what you need, it will be easier to extend that component; otherwise, extend the abstract class.

HATS provides the following host component classes:

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 any of these approaches:

To extend the abstract parent class, com.ibm.hats.transform.components.Component, implement these methods:

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 want your component to work properly within Default Rendering, 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)

Refer to the HATS API documentation for the ComponentElement class for more information.

public ComponentElement[] recognize(LinearScreenRegion region, Properties settings)

This method is reserved for future use. It differs from the previous method only in that it accepts a LinearScreenRegion rather than a BlockScreenRegion. None of the HATS components implement this method; they all return null.

A constructor method, named for your component

This method must accept a com.ibm.hats.common.HostScreen object. For example: 
public MyComponent(HostScreen hostScreen) {
  super(hostScreen);
}
The constructor should initialize parameters that the recognize() method will require, based on the host screen object.

 

Create 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, extend the abstract widget parent class, com.ibm.hats.transform.widgets.Widget, and implement the com.ibm.hats.transform.rendererers.HTMLRenderer interface and the public StringBuffer drawHTML() method. Refer to the HATS API documentation for details about widget interfaces and methods. If you want to modify an existing widget, extend one of the following existing widget classes and overwrite one of its methods.

HATS instantiates the custom widget based on the setting of the widget attribute of the HATS:Component tag.

To generate HTML output, use the HTMLFactory class. This powerful class automatically generates any Javascript needed to present the widget. Here is a simple example of using this class to convert an array of component elements into input elements, which can be rendered directly:

StringBuffer buffer = new StringBuffer();
HTMLElementFactory htmlElementFactory = 
   HTMLElementFactory.newInstance(contextAttributes, settings); 
for (int i = 0; i < componentElements.length; i++) {
      InputComponentElement ice = (InputComponentElement)componentElements[i];
      InputElement ie = htmlFactory.createTextInput(ice);
      ie.render(buffer);
}

Refer to the HATS API documentation for detailed information about the HTMLFactory class and more examples of its use.

 

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 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 this fragment rather than processing the component element. For example:

String ruleReplacement = 
  RenderingRulesEngine.processMatchingElement(componentElement, contextAttributes);
if (ruleReplacement != null) {
  buffer.append(ruleReplacement);
} else {
    .
    .
    .
}

 

Registering your component or widget

After creating a custom component or widget, import the source code for the component or widget into the Source folder of your project. Click File > Import > File System to open the Import wizard. In the Import wizard, select the location of your source files in the From directory field. Select the Source folder (or a package in the Source folder) of your project in the destination Into folder entry field, and ensure that the Create complete folder structure radio button 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 Web Content/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 Source folder of your project, 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, associate the custom widget with a defined component.

Registering your custom components and widgets in the ComponentWidget.xml file makes them available for use in 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 example of the ComponentWidget.xml file that shows the HATS-supplied Field Tablecomponent 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 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 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 Studio. This name must be unique among the registered components. The form of the displayName for a custom component is simply a string, without the percent sign (%). Spaces are allowed in the displayName.

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 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, and make it available for use in 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 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 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, use the following methods.

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.

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 and usage of these methods, see the HATS API documentation for the HCustomProperty class.

 

Home