Working with transformations

A transformation is either a JSP file (for Web projects) that defines how to customize specific host screens. When you create a transformation, you have the option of selecting the host screen on which the transformation will be based. The host screen can be based on a host terminal screen, or from a screen capture. A screen capture can be obtained from an imported BMS map (3270 only) or directly from the host terminal.

Applying a transformation is one of the possible actions of a screen event. Some common uses of transformations are:

Create a Transformation wizard

Use the Create a Transformation wizard to define screen transformations. You can access the wizard a number of ways, such as:

The Create a Transformation wizard appears and enables you to select the target project, name the transformation, give it a description, and see where the transformation definition is saved. Click Next when you have specified these items.

On the Select Screen panel you have the option of selecting the host screen on which the transformation will be based. From the Select a screen section, you can select Use the host terminal screen or Use a previously captured screen from the pull-down menu. You can highlight certain fields on your host screen by selecting the different options beside Highlight fields. If you want to see where the input fields are defined on the screen, select the Input check box. If you want to see what fields are protected, select the Protected check box. If you want to highlight any hidden fields, select the Hidden check box. To modify the colors of the input, protected or hidden fields highlighting, see Using ZIETrans preferences. When your selections have been made, click Next.

There are four rendering patterns from which you can select, Blank, Default Rendering, Prepopulated using Default Rendering, and Prepopulated using Fields.

Blank
Creates a new blank transformation. You can later add individual components using the Insert Default Rendering or Insert Host Components wizards.
Default Rendering
Creates a new transformation that displays with default rendering at runtime. Use this pattern if you want to use a rendering set different from the default, change the region of the screen to be rendered, or add additional components using the Insert Host Components wizard. Click Options to configure the following setting on the Rendering Options panel:
Use the default rendering set
Select this box to use the default rendering set of the application when the transformation is rendered at runtime. Clear this box to select a specific rendering set to always use.
Prepopulated using Default Rendering
Creates a new transformation prefilled with component tags, generated using default rendering, which can be customized using the Edit Host Component wizard. Click Options to configure the following settings on the Rendering Options panel:
Use the default rendering set
Select this box to use the default rendering set of the application when the transformation is rendered at runtime. Clear this box to select a specific rendering set to always use.
Include empty, protected fields
Select this box to generate tags (for Web transformations) for empty, protected fields. In most cases, the default (not generating tags or composites for these fields) is sufficient, and provides more flexibility for moving other controls around the transformation.
Note:
In general, when creating a prefilled transformation, you should capture a screen that has as much information displayed as possible. For example, if you are creating a transformation for a screen containing a table, you should capture a screen that has the entire table of data filled in. This will cause tags (for Web transformations) to be generated for all fields in the table.
Prepopulated using Fields
Creates a new transformation prefilled with labels and input fields which can be customized using the Edit Host Component wizard.Click Options to configure the following setting on the Rendering Options panel:
Include empty, protected fields
Select this box to generate tags (for Web transformations) for empty, protected fields. In most cases, the default (not generating tags or composites for these fields) is sufficient, and provides more flexibility for moving other controls around the transformation.
Note:
In general, when creating a prefilled transformation, you should capture a screen that has as much information displayed as possible. For example, if you are creating a transformation for a screen containing a table, you should capture a screen that has the entire table of data filled in. This will cause tags (for Web transformations) to be generated for all fields in the table.

Use the Preview button to display the transformation using the selected pattern.

After the patterns are laid out you can arrange the components inside your transformation. If you want to launch the screen customization wizard, select the Start the Create Screen Customization wizard when done check box, then click Finish. For more information, see: Default rendering.

Editing transformations

Transformations in ZIETrans Web projects are JSP files and by default are edited using the Rich Page Editor.

Editing transformations for Web projects

You can see the transformations you have created by expanding the Web Content/Transformations folder in the ZIETrans Projects view. To edit a transformation using the Rich Page Editor that is built into Rational® SDP, double-click on the name of the transformation. To see other available editors, right-click on the name of the transformation and select Open With. See Rational SDP documentation for the Rich Page Editor by selecting Help > Help Contents from the menu bar and then search on Rich Page Editor.

The following limitations apply to editing transformations:

Note:
When you copy a transformation from one ZIETrans project to another, the screen capture file associated with the transformation is not copied. The copied transformation will work at runtime without the associated screen capture file. However, you cannot preview the copied transformation in the ZIETrans Toolkit without the associated screen capture file.

In order to preview the copied transformation, you must copy the associated screen capture file by selecting it in the Screen Captures folder. Once you have copied the screen capture file, go back and select the copied transformation from the Transformations folder and open the transformation. Go to the Design tab and right-click anywhere in the window. Select ZIETrans Tools > Edit Host Component. Once the wizard comes up, select the screen from the drop-down menu and click Finish.

When editing a transformation, you can change the properties of ZIETrans components, or other controls (such as buttons, images, and links), by using the Properties view. The Properties view is located at the bottom area of the transformation editor. You can also access the Properties view by selecting Window > Show View > Properties from the ZIETrans menu.

The Palette view can also be used to add ZIETrans components to your transformation. You can select the component from the drop-down menu and drag it to your transformation. The Palette also contains different tags (such as HTML, form tags, JSP) for easy editing. This view can also be launched by selecting Window > Show View > Palette from the menu bar.

Note:
Custom components, ENPTUI, and light pen components do not appear in the ZIETrans Components section in the Palette view of the Rich Page Editor. When enabled they are accessible from the Rational SDP menu bar by clicking ZIETrans Tools > Insert Host Component.

The following sections describe each tab of the Rich Page Editor.

Design

The Design tab of the Rich Page Editor displays the current WYSIWYG view of the transformation as you make changes to it.

When viewing your JSP file on the Design tab, JSP symbols appear in the top left of the file. To hide these symbols, go to Window > Preferences and find the Web preference. Go to Web > Page Design > Appearance > Editing Symbols and clear the JSP check box.

Note:
For considerations when using GB18030 national language characters, see Using code page 1388 (GB18030).

While on the Design tab, you can insert or edit items on the transformation using either the ZIETrans Tools menu on the ZIETrans Toolkit menu bar or the Palette.

The ZIETrans Tools menu contains the following items, each of which launches a transformation wizard. For information about each wizard see Transformation wizards.

The last two menu items (Insert Integration Object Properties, and Insert Forward to ZIETrans Application) are described in Using Integration Objects.

The ZIETrans Components drawer in the Palette contains the following components:

Note:
If you edit a transformation and attempt to insert a ZIETrans component between two consecutive text characters, sometimes the tag is not inserted directly at the cursor location.

If you want to add images to your project, it is recommended that you import them into the Web Content/Common/Images directory of your project. To import images, click File > Import > General > File System to open the Import wizard. Select the location of the image source files you want to import in the From directory field. Select the project_name/Web Content/Common/Images directory as the Into folder. When your image source files are imported, right-click the on the Images folder, and select Show Thumbnails on the Thumbnail tab in the lower right window to see the images. You can use the drag-and-drop method to copy images into the Design tab view of your transformation.

Source

The Source tab displays the HTML and JSP tags in the transformation_name.jsp file necessary for extracting host components from the host screen, the widgets you selected to present those host components, and any other items you added to the transformation. As you make changes on other tabs in the Rich Page Editor, the tags and attributes displayed in the tags of the source file change to match.

You can also make changes directly to the tags and attributes in the source file, or you can insert items using the ZIETrans Tools in the context menu by right click on source. The items you can insert on the Source tab are the same items listed on the Design tab. Place your cursor in the source file at the point you want to insert one of the menu items and then select an option from the ZIETrans Tools drop-down menu.

When a host component and its rendering widget have been inserted, you can use the Edit Host Component option in the ZIETrans Tools to modify the host component and widget. Before you click Edit Host Component, make sure your cursor is inside the <ZIETrans:Component> tag.

When you make changes to the file displayed on the Source tab, they are reflected on the other tabs of the Rich Page Editor.

Transformation wizards

Insert Host Component

With the Insert Host Component wizard, you select the screen from which you want to extract a host component. You also select a region on the screen from which to extract a host component by drawing a rectangle around the text. Place your cursor at any point on the screen, click and hold the left mouse button, and move the cursor to another location on the screen to draw the rectangle. The fields at the bottom of the wizard show the starting and ending row and column numbers of the rectangle. You can also enter the row and column numbers by typing the numbers in the fields.

You can highlight certain fields on your host screen by selecting the different options beside Highlight fields. If you want to see where the input fields are defined on the screen, select the Input check box. If you want to see what fields are protected, select the Protected check box. If you want to highlight any hidden fields, select the Hidden check box. To modify the colors of the input, protected or hidden fields highlighting, see Using ZIETrans preferences. When you have selected the starting and ending row and column numbers of the screen, click Next to display the rendering options for the host components found in the selected region.

ZIETrans provides host components and widgets. You can select one of the host components and widgets provided or you can create your own custom host components and widgets. For more information about host components and widgets see Component and widget descriptions and settings.

Click one of the components in the Components list. The Component Preview window displays the component if it is found in the screen region. If you want to use text replacement for the component, click the Text Replacement icon to the right of the component list to open and edit the settings. For more information about text replacement, see Text Replacement.

You select the widget to use to render the host component from the widgets in the corresponding Widgets list. When you select a widget, the Widget Preview window displays how the widget is displayed in the final Web page. A larger widget preview is available if you click the Widget preview in large window icon (the magnifying glass).

You can override the default project-level settings for individual instances of components and widgets by clicking the Component Settings and Widget Settings icons to the right of the Components and Widgets lists. The default project-level settings for components and widgets are configured using the Rendering tab of the project editor. See Rendering for more information.

Click the Advanced settings for rendering icon to the right of the Widgets list to specify advanced rendering options. The project-level default advanced rendering settings are configured using the Rendering tab of the project editor. See Rendering for more information.

For ZIETrans Web projects, clicking Full page preview shows all the components on the page along with the associated template. This preview shows the page as it will appear to the user.

Note:
When you insert a ZIETrans component into a free layout table of a transformation, the Full page preview function in the Insert Host Component wizard always shows the new component at the top of the free layout table. The preview can be misleading, the component will be inserted at the right location inside the table once you click Finish in the wizard.

To see a full page preview, use the preview functions located in one of the following areas of the ZIETrans Toolkit:

For information about the settings that can be customized with the Insert Host Component wizard, see Component and widget settings. The widgets that are available depend on the selected host components. Table 2 lists the existing ZIETrans host components and their corresponding widgets.

If ZIETrans does not find the component in the screen region, the Component Preview window displays the message No component_name components where found in the specified region, where component_name is the component selected in the Components list. If this message is displayed, you might have selected a region that does not contain the complete component, or you might need to use the Component Settings dialog to modify the settings of the component to match the way your host application displays the component. For example, you might have a Command Line component in the region, but your command line uses the token >>> instead of ==>. You can change the token attribute of the Command Line component to look for a command line with the correct token.

Click Finish when you have made your component and widget selections.

Edit Host Component  Web-only 

With the Edit Host Component wizard, you may select a different screen to look for components from the Select a screen drop-down list. You may also select a different region on the screen from which to extract a host component by drawing a rectangle around the text.

Edit Host Component has the same features as Insert Host Component. It allows you to edit a tag that you have already inserted such as an already placed <ZIETrans:Component> tag. For more information, see Insert Host Component.

Insert Default Rendering

With the Insert Default Rendering wizard you can select the screen you want to use from the Screen drop-down list and the rendering set from the Select a rendering set drop-down list. When inserting a default rendering, the area defined will render the items in the order of the rendering sets. For more information, see Default rendering.

The fields at the bottom of the wizard show the starting and ending row and column numbers of the rectangle. You can also enter the row and column numbers by typing the numbers in the fields. You can highlight certain fields on your host screen by selecting the different options beside Highlight fields. If you want to see where the input fields are defined on the screen, select the Input check box. If you want to see what fields are protected, select the Protected check box. If you want to highlight any hidden fields, select the Hidden check box. To modify the colors of the input, protected or hidden fields highlighting, see Using ZIETrans preferences. When you have selected the starting and ending row and column numbers of the screen, click Finish and the section will be inserted in your screen on the Design tab.

Edit Default Rendering  Web-only 

To edit the default rendering, click the section you want to edit on the Design tab, then select Edit Default Rendering from the ZIETrans Tools menu. This will launch the Edit Default Rendering wizard where you can select the screen you want to edit from the Screen drop-down list and the rendering set from the Select a rendering set drop-down list. When editing a default rendering, the area defined will render the items in the order of the rendering sets. For more information, see Default rendering.

The fields at the bottom of the wizard show the starting and ending row and column numbers of the rectangle. You can also enter the row and column numbers by typing the numbers in the fields. You can highlight certain fields on your host screen by selecting the different options beside Highlight fields. If you want to see where the input fields are defined on the screen, select the Input check box. If you want to see what fields are protected, select the Protected check box. If you want to highlight any hidden fields, select the Hidden check box. To modify the colors of the input, protected or hidden fields highlighting, see Using ZIETrans preferences. When you have selected the starting and ending row and column numbers of the screen, click Finish and the section will be inserted in your screen on the Design tab.

Insert Tabbed Folder  Web-only 

Note:
ZIETrans tabbed folder support is deprecated in ZIETrans V1.0. While support for tabbed folders continues for now, it may be deprecated in the future. Some alternatives are:

Use Insert Tabbed Folder to insert a folder with tabs into your Web page. Tabbed folders are helpful in organizing your widgets and information to display on the Web page. With Insert Tabbed Folder, you specify how many tabs you want for your folder. Combining the tabbed folder and the stored screen function enables you to have a folder with a different host screen on each tab. For each tab in the folder, you also specify the following settings:

Under Tab advanced options, if you clear the Use default values check box, you can specify the following settings:

Under Folder advanced options, if you clear Use default values check box, you can specify the following settings:

The Preview window shows how the tabbed folder will appear, based on the selections you make. This preview does not show the components that have been inserted into the tabbed folder. It only displays changes to the folder such as size and color.

You can click Full page preview to show all the components on the page along with the associated template. This preview shows the page as it will appear to the user.

Click OK when you have defined all of the tabbed folder options for each tab in the folder.

Once you have created a tabbed folder, you can not come back to the Insert Tabbed Folder wizard to make changes. You need to edit the source because the output is in HTML (and ZIETrans component tags).

Notes:
  1. Because a tabbed folder is made up of several HTML tags, it is not recommended to try to move the individual sections. If you want to change the location of your tabbed folder, select the cell that surrounds it and move the cell to the location you want.

Insert Macro Key

With Insert Macro Key, the user can run the macro on a transformation by clicking on a button or a link, or by selecting the macro from a drop-down list. For example, your transformation can present a logon screen that also has a button for a logon macro. When the user clicks the button, the macro plays to supply a user ID and a password, and navigates to the next screen that the user needs to see.

To add a macro to your transformation, select the macro you want to add. For Web projects you can select multiple macros within the same instance of the wizard. You must also define how to display and initiate the macro from the transformation. Choose from one of the following options:

Note:
ZIETrans uses the description of the macro as the text inserted into the transformation for any of the rendering options but you can still change the name by editing the text in the Source view.

Insert Global Variable

Insert Global Variable allows one of the following options:

You select a defined global variable whose value you want to display from the drop-down Name list.

You then select how you want the global variable displayed at runtime. If you select Display global variable value as static text, you can click the Advanced button and the Variable is indexed check box. Then use the radio buttons to specify whether all indexes or only a single index is inserted. If you click the Show all indices radio button, then select the Separator from the drop-down list. If you click the Show a single index radio button, then specify the number of the index to insert. Selecting the Shared check box will take the global variable from the shared list.

If you want to prompt the user using an input box, select Prompt for global variable with input box. Select Set initial value from global variable to insert an initial value in the input field. Selecting Mask as password field will mask what the user inserts in the input field.

Insert Operator Information Area  Web-only 

Select Insert Operator Information Area to display any available information you specified on the Rendering tab of your Project Settings. For more information, see Operator information area.

Insert Host Keypad

Host keypads can be inserted in a number of ways. You can insert default or custom host keypads, or select an individual key for your transformations.

Default Keypad  Web-only 

Select Insert Host Keypad > Default Keypad to add a default host keypad into a transformation. An inserted host keypad is only visible in the Preview and Design views if your project settings are configured to display the default host keypad in your ZIETrans application. To configure your project to show the default host keypad and define which keys to include, go to the ZIETrans Projects view, double click the Project Settings of your ZIETrans project, select the Rendering tab and click Host Keypad.

Custom Keypad  Web-only 

Select Insert Host Keypad > Custom Keypad to add a custom host keypad into a transformation. Custom host keypads use the same keys specified in the default host keypad settings, located in the Project Settings of your ZIETrans project. With a custom host keypad, you can edit the attributes of individual keypad buttons or links in the Design view by highlighting the button or link, right-clicking, and selecting Properties.

Individual Key

Use this option to add an individual host key to your transformation. From the Insert Host Key panel, select which host key to insert and whether you want it displayed as a button or link, then click OK. For Web projects you can select multiple host keys within the same instance of the wizard. After inserting, you can edit the button or link using the Properties tab.

Insert Application Keypad

Application keypads can be inserted in a number of ways. You can insert default or custom application keypads, or select an individual key for your transformations.

Default Keypad  Web-only 

Select Insert Application Keypad > Default Keypad to add a default application keypad into a template. To configure default application keypad and define which keys to display, go to the ZIETrans Projects view, double click the Project Settings of your ZIETrans project, select the Rendering tab and click Application Keypad.

Custom Keypad  Web-only 

Select Insert Application Keypad > Custom Keypad to add a custom application keypad into a template. Custom application keypads use the same keys specified in the default application keypad settings, located in the Project Settings of your ZIETrans project. With a custom application keypad, you can edit the attributes of individual keypad buttons or links in the Design view by highlighting the button or link, right-clicking, and selecting Properties.

Individual Key

Use this option to add an individual application key to your transformation. From the Insert Application Key panel, select which application key to insert and whether you want it displayed as a button or link, then click OK. For Web projects you can select multiple application keys within the same instance of the wizard. After inserting, you can edit the button or link using the Properties tab.

Insert All Host Components  Web-only 

Select Insert All Host Components when you want to add all possible host components from a particular screen capture or customization to a transformation. Choose the appropriate project screen from the Select Screen drop-down menu. You can highlight certain fields on your host screen by selecting the different options beside Highlight fields. If you want to see where the input fields are defined on the screen, select the Input check box. If you want to see what fields are protected, select the Protected check box. If you want to highlight any hidden fields, select the Hidden check box. To modify the colors of the input, protected or hidden fields highlighting, see Using ZIETrans preferences. Click OK after making your selections.

The host components added will use the default rendering set specified within Rendering Sets in the Rendering tab of your ZIETrans Project Settings.

Insert Stored Screen  Web-only 

Select Insert Stored Screen when you want to add a stored screen to your transformation. Select the stored screen name and then select All fields (non-protected and protected) or Shared. For example, stored screens can be combined in a transformation to create a screen consisting of all the screens' fields.

For information about combining multiple screens, see Combining screens.

Previewing transformations

As previously mentioned, you can preview a widget as it displays on a transformation in the Insert Host Component wizard or the Insert Tabbed Folder wizard.

Another way to preview your transformation is to use screen captures. For every transformation you create in your project, there is an associated screen capture. You can see the screen captures by expanding the Screen Captures folder in the ZIETrans Projects view. Double-clicking on the name of the screen capture displays a view of the screen capture with two tabs, Host Screen and Preview. The Host Screen tab displays the screen as it appears on the host. The Preview tab displays how the transformation is rendered, along with the template associated with the transformation.

The transformation and template used to generate the preview are based on screen customizations defined in your project. Preview scans the list of enabled screen customizations. When a screen customization is encountered that matches the screen capture, the first action that applies a transformation (along with the associated template) is used to render the preview. If no matching screen customization is found, the default template and transformation are used for the preview.

Notes:
  1. The Preview tab will not process the Next Screen defined in the screen recognition event. For more information, see Next Screen.

Host keypad

The host keypad includes buttons that represent host keys, such as F1, F2, and Clear, which are used to control functions on the host screen.

By default, ZIETrans does not display the host keypad. To display the keypad, go to the ZIETrans Projects view, double click the Project Settings of your ZIETrans project, select the Rendering tab, and click on Host Keypad. You then have the option of selecting the check box to display the keypad as well as selecting which keys to display.

Notes:
  1. Custom keypads and individual keys are defined using individual tags or composites, as a result they are displayed in the transformation's editor.
  2. Text on the host screen that describes function keys are transformed into buttons or links using the default transformation. They are displayed in the transformed host screen area, separately from the host keypad.

Refer to Modifying a ZIETrans project for more information about the settings for keyboard support and keypads.