Creating a custom host component

ZIETrans provides a Create Component wizard to help you create custom components. You can start the wizard in several ways:
  • From the File > New > ZIETrans Component menu in ZIETrans Toolkit
  • From the ZIETrans > New > Component menu in ZIETrans Toolkit
  • From the context (right-click) menu of a ZIETrans project, select New ZIETrans > Component

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 ZIETrans 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 ZIETrans 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:
  • Extends the host component abstract class, com.ibm.hats.transform.components.Component.

    If one of the ZIETrans host components is very similar to what you need, it will be easier to extend that component. See Extending component classes for more information.

  • Adds the constructor method. This method, named for your component, 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.
  • Adds the recognize() method.
    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 ZIETrans 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 ZIETrans API References (Javadoc) for the recognize() method of the Component class. See Using the API documentation (Javadoc).

  • Adds the source code for the component into the Source folder of your project
  • Compiles the new component .java file, if you have Build Automatically checked in the Eclipse workbench preferences (Window > Preferences > General > Workspace or Project > Build Automatically). If the component is not compiled into a .class file, it is not available for use in the ZIETrans Toolkit.
  • Registers the new component in the ComponentWidget.xml file. See Registering your component or widget for more information about registering components.
If you selected the check box to include ZIETrans Toolkit graphical user interface support methods, enabling you to modify the settings of the component, the Create Component wizard adds the following methods:
  • Method to return the number of pages in the property settings:
    public int getPropertyPageCount() {
    		return (1);
    }
  • Method to return the settings that can be customized:
    public Vector getCustomProperties(int iPageNumber, Properties properties,
    			ResourceBundle bundle) {
    		return (null);
    }
  • Method to return the default values of the settings that can be customized:
    public Properties getDefaultValues(int iPageNumber) {
    		return (super.getDefaultValues(iPageNumber));
    	}

See ZIETrans Toolkit support for custom component and widget settings for more information about the methods necessary to support your custom component.

Note: If you want your component to work properly within Default Rendering, you must 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 ZIETrans API References (Javadoc) for the ComponentElement class for more information. See Using the API documentation (Javadoc).