Guide to create custom widgets

1. Rational Host Access Transformation Services
Tutorial: Custom Widget
Abstract
Transformation is the core function of HATS. Components and Widgets provide important functions in
transformation process. Once components are recognized in specified regions of the host screen, widgets
render these regions. HATS offers settings for the provided components and widgets to handle most
conditions. You can also modify settings at the project level, in the rendering sets, or in a specific
transformation.
If you would like to render host components in a special way (such as combining two lines of data to one
line) and the provided HATS widgets cannot be configured to meet your requirement, writing your own
custom widget could be a way to resolve this condition. This tutorial is designed for a web developer who
would like to know how to create a custom widget.
Topics covered in this tutorial
This tutorial will cover how to create a screen customization that sets global variables, and give instruction
on how to construct a custom widget. In this tutorial, the scenario we will use is creating a HTML custom
widget containing an input field and a button. The widget we will create in this tutorial can be used when a
host screen contains the host component that would be recognized as an Input field or an Input field with
hints and a web developer wants to use an additional button to send mnemonic keyword for a specific
purpose:
Example:
A Help button, to send the mnemonic keyword [pf1]
A Prompt button, to send the mnemonic keyword [pf4]
The button name and mnemonic keyword can be:
 Inputted from the widget settings
 Imported from specified global variables
Assumptions
This tutorial assumes:
 You have already installed HATS Toolkit v7.1.
 You are already familiar with basic HATS skills to customize HATS applications, to use global
variables and to perform running on server.
 The HATS toolkit is open, and a HATS project exists in your workspace.
Create your custom widget
The widget java file is a Java class which determines how this widget will behave. In this tutorial, we

2. describe widget creation steps with a HATS Web project. To create the widget in HATS RCP project, the
steps are almost the same.
For more information about required elements of a widget, refer to the section Creating custom
components and widgets in Web Application Programmer’s Guide or Rich Client Platform Programmer’s
Guide.
The scenario that we are going to use in this demo is:
A web developer would like to create a custom widget to transform Input field and Input field with hints
components. By using this widget, the web developer offers users an additional button beside the input field
so that users could use this button for specific purpose. Additionally, the web developer prefers the user uses
those buttons instead of function keys.
Now we will look at steps to create and use this widget:
1. To create the widget, go to your HATS Web project and launch the Create a Widget wizard by right
clicking your HATS project -> New -> Widget. In the Create a Widget wizard, enter a name for the
widget (we use MyCustomWidget as the widget’s name in this tutorial), ensure the checkbox Include
methods to allow settings to be modified in the HATS Toolkit checked, and associate this widget
with the component Input field and Input field with hints. The screen will look like:
When Include methods to allow settings to be modified in the HATS Toolkit option is enabled,
additional methods getPropertyPageCount(),getCustomProperties() and getDefaultValues() will be
appended to the new Java source file for further implementation.
2. After the wizard is finished, the Java source file MyCustomWidget.java in your HATS Web project
should be created in the directory widgets as shown below:

3. 3. Open MyCustomWidget.java with the Java Editor. You will see that some of the elements have been
constructed in this source file. We are now ready to implement the code for the widget:

4. 4. According to our design, the widget settings should have the following capabilities:
 To retrieve the button name and mnemonic keyword from global variables if the checkbox Fill
from global variables is checked
 To retrieve the button name and mnemonic keyword from an input string if the checkbox Input
directly is checked.
 To treat the button name and mnemonic keyword as an empty string if there is a conflict.
Note: The following screen shot shows the widget settings that will be created after the widget
implementation completed.
4.1 To achieve this goal, we use the public method getCustomProperties() to implement the GUI for
widget settings.
Add this method to MyCustomWidget.java and append appropriate GUI components into it. The
code blocks includes declarations for the properties and statements to create GUI components as
shown below:
 Declarations for the properties:

5.  Statements to create GUI components:
For detailed information about how to customize widget settings, refer to the HATS Information
Center and HATS API References.
4.2 Once the code block in section 4.1 is created, you can verify the widget settings. Go to Navigator
view -> Web Content -> and open the component and widget list file, ComponentWidget.xml.
You will find that the new widget MyCustomWidget is registered to the component and widget
list:
And the widget is associated to components Input field and Input field with hints as shown
below:
Go to your project settings and verify the new GUI. Ensure all GUI elements behave properly.

6. 5. After coding the widget settings, it is time to define how this widget will render the associated
components. The public method, drawHTML(), is one of required methods of a Web widget.
drawHTML() is used to generate HTML output in JSP files in a HATS Web project. For a HATS RCP
project, you can use another public method drawSWT() to generate RCP output.
In drawHTML(), you need to complete following steps from 5.1 to 5.7:
5.1 Examine the following code that generated by the wizard. In the code block, the buffer is used to
store generated HTML, and the HTML element factory will create HTML elements:
5.2 Declare variables to store settings:
In this step, you might experience compile errors for missing imports. You can use Source ->
Organize Imports to resolve the missing imports. .
5.3 In the next step, we will use the public class
com.ibm.hats.transform.elements.InputComponentElement to generate HTML input
elements. The code block will iterate through each componentElements object. Please note that
the widget should not process components that have already been processed by a HATS global
rule. The method RenderingRulesEngine.processMatchingElement() will return the
transformation fragment if this input field has been processed, or return NULL if it is not
processed yet. For more information about widgets and global rules, refer to the section Creating
custom components and widgets in Web Application Programmer’s Guide or Rich Client
Platform Programmer’s Guide.
Add the code block below:

7. 5.4 Add the button element next to the input field and use getContextAttribute() to extract the hash
table for global variables:
These statements above are to determine how to set the button name and mnemonic keyword. We
use the following three methodologies here:
1. If only Fill from global variables is checked and global variables are available,
extract values from global variables.
2. If only Input directly is checked, extract values from widget settings.
3. If the GUI configuration is incorrect, set button name and mnemonic keyword to
empty string.
5.5 Get button name and mnemonic keyword from global variables or widget settings:
5.51 Scenario 1: Get from global variables:

8. 5.52 Scenario 2: Get from widget settings:
5.6 The last step is to set button name, mnemonic keyword and action for this button:
6. At this point, we have completed the implementation of this widget. To test obtaining the button label
and host key mnemonic from global variables, we need to initialize those two global variables by
creating a screen customization with set global variable actions. This step is only for demonstration
purpose in this tutorial. You need to consider when to set these two global variables and how to set
them to match your business needs.
6.1 Create a HATS Customization with the name CustomSignOn.evnt. Apply the transformation
default.jsp to the customization CustomSignOn.evnt. Add two Actions to set these two global
variables to the customization CustomSignOn. The page Actions in CustomSignOn.evnt looks
like :
With this design, the customization CustomSignOn.evnt will initialize values for button name and
mnemonic keyword when host connection established.
For more information about the available mnemonic keywords, refer to The HATS-supported
3270 mnemonic keyword table and The HATS-supported 5250 mnemonic keyword table in
Enabling keyboard support.

9. 6.2 In this tutorial, the custom widget is associated with Input field and Input field with hints,
which are used to transform un-protected field like the input field Position to type in System i
screen Work with Objects Using PDM. You can navigate to the screen Work with Objects
Using PDM by: signing on to your System i and issuing the command STRPDM in the
command line. It will look like:
In the green screen, end users need to know that if they position their cursor in the Position to type
field, they can press PF1 to receive help information for that field. See the help dialog below:

10. To achieve this goal, create a HATS Transformation, WorkWithObjectsUsingPDM. Use
MyCustomWidget widget for the input field Position to type and use field components and
widgets for the other regions of this screen:
Edit this host component of this input field. Configure widget settings as shown below:
7. Save all changes in your HATS web project.
It’s time to test functionalities for this new widget. Perform Run on Server or Debug on Server to test
it, ensuring that the widget behaves properly in each condition.

11. Conclusion
This tutorial has demonstrated how to use HATS Toolkit to create and test a custom widget. The option
to create your own custom widgets is very helpful when the settings that are provided by HATS do not
meet your needs. Using this powerful capability could help you to reduce the effort when customizing a
large number of host screens.
Related References
See Web Application Programmer’s Guide and Rich Client Platform Programmer’s Guide for more
information.