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.