Rational Host Access Transformation Services
Tutorial: Custom Widget
Abstract
Transformation is the core function of HATS. Components and Widgetsprovide important functionsin transformation process. Once components are recognizedin specifiedregions of the host screen, widgets render these regions. HATSoffers settings for the provided components and widgets to handle most conditions. You canalso modify settingsat 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) andthe provided HATSwidgetscannot be configured to meet your requirement, writingyour own custom widget could be a way to resolve this condition.This tutorial is designed fora 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 acustom 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 Inputfieldor anInputfieldwithhintsand 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]
Thebutton name and mnemonic keywordcan be:
Inputtedfromthe widget settings
Imported from specified global variables
Assumptions
This tutorial assumes:
You have already installed HATS Toolkit v7.1.
You are already familiar withbasic HATSskills to customizeHATS applications, to useglobalvariables 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 determineshow this widget will behave.In this tutorial, we describewidget 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 widgetsin 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 buttonbesidethe 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 thiswidget:
- To create the widget, go to your HATS Web project and launchthe Create a Widgetwizard by right clicking your HATS project -> New -> Widget. In the Create a Widgetwizard, enter a name for the widget (we use MyCustomWidgetas 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 Inputfield 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.
- After the wizard is finished, the Java source file MyCustomWidget.javain your HATS Web project should be created in the directory widgets as shown below:
- Open MyCustomWidget.javawiththe Java Editor. You will seethat someof the elementshave been constructed in this source file. We are now ready to implement the code for the widget:
- According to our design, the widget settingsshouldhave the following capabilities:
To retrievethe button name and mnemonic keywordfrom global variables if the checkbox Fill from global variables is checked
Toretrievethe button name and mnemonic keyword from an input string if the checkbox Inputdirectly is checked.
To treat the button name and mnemonic keyword as an empty stringif there is a conflict.
Note: The following screen shot shows the widget settings that will be created after the widget implementation completed.
4.1To achievethis goal, we use the public method getCustomProperties() to implementthe GUI for widget settings.
Add this method to MyCustomWidget.javaand append appropriateGUI componentsinto it. The code blocksincludes declarations for the properties and statements to create GUI components as shown below:
Declarations for the properties:
Statements to create GUI components:
For detailedinformation about how to customize widget settings, refer to the HATS Information Center and HATS API References.
4.2Once the code block in section 4.1 is created, you can verify the widget settings. Go toNavigatorview -> WebContent -> andopen the component and widget list file,ComponentWidget.xml. You will find that the new widget MyCustomWidgetis registered to the component and widget list:
And the widget is associated to components Inputfield and Inputfieldwithhints as shown below:
Go to your project settings and verify the new GUI. Ensure all GUI elements behaveproperly.
- 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 methodsof a Web widget. drawHTML()is used to generate HTML output in JSP files in a HATS Web project. Fora 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.1Examine 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.2Declare variables to store settings:
In this step, you might experience compile errors for missing imports. You can use Source -> OrganizeImports to resolve the missing imports. .
5.3In 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 widgetsin Web Application Programmer’s Guide or Rich Client Platform Programmer’s Guide.
Add the code block below:
5.4Add 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:
- If only Fillfromglobalvariables is checked and global variables are available, extract values from global variables.
- If only Inputdirectly is checked, extract values from widget settings.
- If the GUI configuration is incorrect, set button name and mnemonic keyword to empty string.
5.5Get button name and mnemonic keyword from global variables or widget settings:
5.51Scenario 1: Get from global variables:
5.52Scenario 2: Get from widget settings:
5.6The last step is to set button name, mnemonic keyword and action for this button:
- 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 toinitialize those two global variables by creating a screen customizationwith 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.1Create a HATS Customizationwith the name CustomSignOn.evnt. Apply the transformationdefault.jsp to the customization CustomSignOn.evnt. Add two Actions to set these two global variables to the customization CustomSignOn. The page ActionsinCustomSignOn.evntlookslike :
With this design, the customization CustomSignOn.evntwill 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 tableand The HATS-supported 5250mnemonickeywordtablein Enabling keyboard support.
6.2In this tutorial, the custom widget is associated with Inputfield and Input field with hints, which are used to transform un-protected field like the input field Positiontotype in Systemi screen WorkwithObjectsUsingPDM. You can navigate to the screenWorkwithObjectsUsingPDM by: signing on to yourSystemi 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 Positiontotype and use fieldcomponents and widgets for the other regions of this screen:
Edit this host component of this input field. Configure widget settings as shown below:
- Save all changes in your HATS web project.
It’s time to test functionalities for this new widget. Perform Run on Server or DebugonServer to test it, ensuring thatthe widgetbehaves properly in eachcondition.
Conclusion
This tutorial has demonstrated how to use HATSToolkit to create and test a custom widget. The option to create your own custom widgetsis very helpful whenthe 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 GuideandRich Client Platform Programmer’s Guidefor more information.