About this tutorial

Objectives

This tutorial teaches you how to customize 5250 screens by hiding screen elements and adding new screen elements using aXes eXtensions.

Prerequisites

Tutorial 1 - Screen and Field Identification

Before attempting this tutorial, please complete all of the steps in Tutorial 1.

Outline

Using aXes Developer

Simple customization

Adding value using customization

Adding value using scripting

Testing customizations as a user

Screen identifier/design concepts

Using aXes Developer

Use your desktop shortcut to open the aXes Projects Home Page.

Image

Sign on as an aXes developer and select your project from the list on the right.

On the next screen, click on the Work as TS2 Developer option. This will start an aXes developer session.

Sign on to a 5250 session and display the Main Menu.

The white background around the open padlock in the tool bar at the top right of the screen panel indicates that the screen is unlocked. The closed pad lock is greyed.

Image

Click on the eXtensions tab and then lock the screen by clicking the closed padlock icon on the top right of the screen.

Selecting objects to customize

Click the Screen object in the Extendable Objects list.

Click the eXtensions action button (in the eXtensions bar) and choose the Customize Screen option from the eXtensions Actions list.

The eXtensions panel shows the basic object properties.

Image

What is the thin red line?

If you look closely at your 5250 screen panel, you may see red, dotted lines around the screen. These lines represent the boundaries of this 5250 screen.

You can move the boundaries to create more space on your 5250 screen.

Tutorial 10 – 5250 Screen Styling explains how to move the screen boundaries.

Warning: Do not place any screen element outside the screen boundaries.

aXes Developer window

The aXes Developer window changes layout and content depending on the object selection. To understand how this works, it is worth looking at the layout of a typical aXes Developer window in a little more detail.

Image

The body of the aXes Developer window contains a list of screen objects and property sheets. If you have used almost any other visual development tools, you will have seen similar property sheets.

The following table explains the parts of the aXes Developer window.

Basic actions button

The button opens a list of actions available for the basic properties.

Extension List

The Extension List contains a list of extensions that can be dragged and dropped onto the screen panel.

Extendable objects

The Extendable Objects opens a list of objects already existing in the screen panel.

eXtensions

The eXtensions panel contains details of the selected object, properties and property values for extending the selected object. For example, the Visible property shows or hides the selected object.

eXtensions actions button

The button opens a list of actions available for an extension.

Property name / value

Each property has a name (on the left) and a value (on the right). Change the value (on the right) to change the behaviour of a screen or screen element.

Selected object details

The details describe the object type and placement on the screen.

Selected object properties

eXtensions Basic

The Basic panel contains properties defining how selected object behaves.

Selected object visualization

eXtensions Default Visualization

The Default Visualization panel contains properties defining the appearance of the selected object.

Tool bar

The tool bar contains buttons including save, cancel, undo, redo and reset.

Visualization actions button

The button opens a list of actions available for the visualization properties.

Extendable object actions button

The + button adds a user field onto the screen panel. The – button deletes the selected user field or element on the screen.

Simple customization

Hide screen elements

With the Main Menu 5250 screen and the aXes Developer window displayed, click on the text Select one of the following: to select it.

Your screen should now look like this:

Image

The aXes Developer window shows the selected element, i.e. the output text, "Select one of the following:" inside a selection box with sizing handles.

Click the extensions action button (in the eXtensions bar) and choose the Customize Field option from the eXtensions Actions List.

In the eXtensions area of the aXes Developer window, uncheck the Visible property.

Do not remove the default visualisation.

Click the Save button.

The 5250 screen no longer shows the text.

Image

In this example, aXes does not display the hidden text. Nevertheless, the text remains as a screen element.

Hiding a screen element does not delete the element from the screen.

You have now completed the simplest task of screen enhancement – hiding a screen element.

Screen enhancement techniques

In most cases, enhancing 5250 screens uses three main techniques:

1.

Change visualization

Causing 5250 screen elements be visualized in a different way, e.g. as a check box, drop-down list, hidden, etc.

Tutorial 3 deals with this area in depth.

2.

Add new capabilities

Add new capabilities to 5250 screen elements, e.g. transforming a date field into a date picker.

Tutorial 3 also deals with this topic.

3.

Introduce new elements

Add brand new elements to the 5250 screen to improve its appearance or allow it to perform new operations that add value to the underlying application, e.g. adding push buttons and scripts.

Adding value is the focus of the rest of this tutorial.

Add a group box

You are now going to add a group box to the MAIN screen. There are two ways to add a user field to the screen:

Select Group Box from the Extension Toolbox then drag and drop onto the screen panel.

Image

The sizing handles appear on the group box on the screen panel and include the text, Group Box.

Image

Click Add User Field (image009) button to add a user field.

A new user field will appear on the screen as a box with sizing handles.

Next, you define what type of user field you wish to use.

Double-click the user field and aXes will display a list of eXtensions.

Choose Group Box from the list and click the Add button.

Change its caption property value to Select an option:

You can click on and drag the sizing handles to resize the group box.

Enlarge the group box so that it surrounds the menu items.

When you finish, the screen will look similar to this:

Image

You have added a group box to customize the MAIN screen.

Using screen customization to add value

In the preceding section, you added a group box to the MAIN screen. This adds some value to the application from the visual perspective, but adds nothing from the usability perspective.

You are now going to add new buttons to the MAIN screen that add usability value to the 5250 screen.

Add a button

Select Push Button from the Extension Toolbox and drag and drop it onto the screen panel. Or click the Add User Field button.

Image

Move the new button to the right-hand side of the screen.

Change the button's caption to QPRINT Queue.

The caption property is in the lower panel of the aXes Developer window.

The screen should look like this:

Image

Click the Save button to save your MAIN screen customizations.

You have added a push button to customize the MAIN screen.

Using scripting to add value

Add buttons and scripts

This section explains how to add a script to a button.

Click on your new QPRINT Queue button to select it, and look at its property sheet:

Image

The caption, style, and sizeToField properties are static and are evaluated literally from what is displayed, i.e. the caption is taken literally from the text you typed in as QPRINT Queue. You can edit these by clicking the value field directly.

The onClick, onFocus and onBlur properties are action properties and perform a JavaScript operation. The onClick property tells aXes what to do when a user clicks the QPRINT Queue button, and in this example, the JavaScript code SENDKEY(ENV.defaultKey); will be executed.

Almost all properties can be evaluated as JavaScript code. This is a very powerful, flexible and dynamic feature that is dealt with in more detail in following tutorials.

Without going into the details right now, as the name suggests, the SENDKEY(ENV.defaultKey); JavaScript function call sends a key stroke corresponding to the Environment default key into the 5250 session. Typically, this is the Enter key, unless a different default key has been specified.

Clicking the QPRINT Queue button acts just like pressing the Enter key.

You are now going to change what happens when the QPRINT Queue button is clicked.

Click the Edit Script button adjacent to the onClick property.

A small editor window like this should appear:

Image

Select and delete the SENDKEY(ENV.defaultKey); code.

Copy and paste the following code into the edit window.

var F = FIELDS("CommandLine");

F.setValue("WRKOUTQ QPRINT");

SENDKEY(ENV.defaultKey);

The editor window should look like the next screen.

Image

Click OK in the editor window to apply your changes to the property value.

What does this code do? It locates a reference to the field you have named CommandLine on the current MAIN screen (remember, you assigned this name in Tutorial 1). It then sets the CommandLine screen field to the value "WRKOUTQ QPRINT", and finally presses the Enter key.

In short, pressing the QPRINT Queue button should now execute the IBM i WRKOUTQ QPRINT command.

This is a short cut way to display the IBM i output queue named QPRINT.

It adds value to the application because it makes displaying the output queue faster, especially when you display the output queue QPRINT frequently.

Next, to facilitate the following tutorials you need to add two more button eXtensions to the MAIN screen.

Follow the same steps you used when adding the QPRINT Queue button.

First, add a button with the caption Add aXesDemo to Library List that executes this code when clicked:

var F = FIELDS("CommandLine");

F.setValue("ADDLIBLE AXESDEMO");

SENDKEY(ENV.defaultKey);

Then, add another new button with the caption aXes Demo HR System that executes this code when clicked:

var F = FIELDS("CommandLine");

F.setValue("CALL XHRRPGTRN");

SENDKEY(ENV.defaultKey);

Save your screen customizations.

Your customized version of the MAIN screen should now look something like this:

Image

Testing customizations

Always test your customizations as a user.

You can test your screen customizations while logged on to aXes as a developer, but you must always also test your application while logged on as a user.

To test as a user, open the Projects Home Page.

Select your project, and then use the Work as a User (aXes-TS2) option to start aXes.

Log on and verify that the customizations on the MAIN screen display correctly and try out the new buttons.

Screen identifier/design concepts

When you use aXes eXtensions you need to understand the terms screen identifier and screen design.

Screen identifier

When you save customizations, screen identification information goes into a .scn file (for example 14.scn).

This file is referred to as a screen identifier file.

Screen design

The design customizations go into a file named: screen_<screenname>.js

This file is referred to as a screen design file.

A screen identifier uniquely identifies one variation of a screen. A variation can be, for example, a screen in display mode, and another variation can be the same screen in update mode. Both variations have their own screen identifiers.

Image

If a screen has been customized, the screen identifier points to the screen design. When there are variations of a screen, all screen identifiers point to the same screen design.