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

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

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.

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:

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:

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.

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:

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.

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.