Developer

Agentry User Interface Definitions Overview

The client-side user interface definitions architecture enables Agentry to support multiple client device platforms from a single application.

To achieve this, the architecture separates the application’s business logic from the user interface. This separation then requires the specific structure of the user interface definitions within the Agentry application project.

The primary interface definition is the Screen Set. The screen set is a module-level definition. A screen set definition defines the Agentry Client's user interface. The screen set defines the definition type to be displayed, which can be an object, transaction, or fetch within the same module. The screen definitions within the screen set can display properties of this definition type. Screen sets contain the child definitions screen and platform. The screen set is the definition referenced by other definitions for display and are universal to all supported platforms within the application project.

The platform definition is one of two child definitions to the screen set. A platform definition defines how a screen set’s screens appear on a specific device type. A platform is defined to use one or more screens within the same parent screen set. There are different platform types, each corresponding to a different type of client device. The platform affects the placement of buttons and the form factor of the screens it uses.

The screen definition is the second child definition to the screen set. A screen definition defines how the property values in the definition being displayed are presented to the user on the Agentry Client. This includes which values are displayed. A screen also defines, via its child control definitions, how a user can interact with the Client. There are two types of screen definitions: list screens, to display object collections; and detail screens, to display a single instance of an object, transaction, or fetch definition.

Screen Sets, Platforms, and Screens at Run Time

The overall structure of the screen set definition is intended to support multiple client device platforms from a single application project. Within the screen set there exists one or more platform definitions. Each platform definition matches a client device type within the implementation environment. A given platform is defined to use one or more screens within the same screen set. Depending on the types of client devices, there may or may not be overlap in the list of used screens among the platforms; so it is possible for the same screen to be used by more than one platform. Alternately, a given screen or screens may be used by only one platform within the screen set.

When new or edited screen sets are published to the server, they are then downloaded to the clients at run time. When this occurs, the client provides the server with information about the client device upon which it is running. The server then interrogates the screen set definition, looking for the platform definition within it for that client device. When found, the screens used by that platform are then those downloaded by the client for that screen set. No other screens within the screen set are received by that client. A second client running on a different device type will receive the same screen set, but with different screens. These screens would be the ones used by the platform definition for this second device type.

The screen set, then, is the definition referenced by other definitions for display. Typically this is an action step, such as a navigation or transaction step. Actions and their steps are platform independent, meaning all clients receive the same action definitions regardless of the client device type. The action steps then dictate the screen set to be displayed. When a screen set is displayed on the client, the screens it contains are always the ones matching the device type, as the screen set on a given client will contain only those screens for that client device.

How the screens of a screen set are displayed depends on the definition type the screen set is defined to display. When a screen set displays an object, its screens are displayed in a tab control. Each screen definition is represented by a tab. Selecting a tab displays the corresponding screen.

When the screen set is displaying a transaction or fetch, the screens are displayed in a wizard format. This results in each screen being displayed one at a time, with wizard buttons (such as back, next, cancel, and finish) displayed at the bottom. The user navigates through the wizard using these buttons, entering data in each screens fields.

Screen Types: List Screen

There are two types of screen definitions that can be added to a screen set: list screens and detail screens. A list screen definition displays an object collection property on the Agentry Client. Object instances from the collection are displayed as rows in the list. A list screen contains the child definitions column and button. A column is defined to display the property value for each object instance in the collection. Buttons are defined to execute actions related to the object instances. List screens include definable behaviors related to filtering, scanning, and sorting, as well as other screen enhancements for displaying data stored in the object instances of the target collection property.

The list screen definition is typically used for a basic presentation of an object collection property. Each object instance is displayed in a list control, which is the main feature of the list screen. This screen type can only be used to display object collection properties. The columns of a list screen are defined for the properties of the object type in the collection being displayed in the list control.

The list screen can be defined to allow or prevent users from resorting the list of objects by clicking a column header within the list control. The default is to allow resorting. Disabling this functionality will prevent the user from resorting the list of objects. This is often used when the objects represent some prescribed order, such as safety plan procedures. In this case it is generally considered good form to select a fixed sort property from the object collection being displayed. This is also defined in the list screen.

The columns themselves are defined to either be included or excluded from those values upon which the list can be filtered. The default for a column is to be included. If it is desired to prevent the user from filtering the list screen on certain object values, the columns for those values can be defined to be excluded from the filter values. As a separate attribute in the column is whether or not the column values should be included in scan filtering. Scan filtering is the behavior where a user can scan a barcode value and the currently displayed list is then automatically filtered to only those items that match the scanned value. The column definition includes the Scanner Filter attribute that specifies whether or not the column value should be used to filter the list based on a scanned value. This behavior only applies when the parent list screen is used by a platform for scanning, and only when the client device is equipped with a barcode scanner.

List columns can also display the values for each object as a hyperlink. When this feature is enabled, each cell in the column is displayed as a hyperlink. When the hyperlink is selected an action is executed. Part of the hyperlink functionality is to define the action to execute and the object instance to be targeted.

In addition, each list column definition can be enabled or disabled based on a rule, with disabled columns hidden from the user. Columns can also be formatted using the Format attribute. Finally, the default width of the column can be specified. Related to this is a behavior defined in the parent list screen. It is possible to prevent users from resizing the columns by defining the list screen to disable this featured.

Screen Types: Detail Screens

A detail screen definition displays a single instance of an object, transaction, or fetch on the Agentry Client. The properties of the definition instance are displayed in fields, a child definition to the detail screen. Definable behaviors of a detail screen are predominantly controlled by the screen’s child field and button definitions, which can include read-only or read-write values within the fields, as well as numerous field type behaviors. Detail screens for transactions and fetches do not have the child definition button.

The overall behavior of a detail screen is dependent in large part on the fields it contains. A detail screen field defines a field control for display on the parent screen. The field displays data to the user and, when displaying a transaction or a fetch, can capture data from the user. A field can have one of several edit types that affect both the appearance and behavior of the field on the screen, especially when capturing data.

The field edit types vary from basic string fields to more robust fields including several different list types, a calendar control, date and time pickers, and several others. The proper field edit type depends on, first, the data type of the value the field is displaying, and, second, the desired method in which users should enter data. When fields are displayed on detail screens displaying object instances, data entry is typically not a part of the design as the fields are read-only when displaying object properties. In this case, the field’s edit can be changed, but typically it is left set to default. When the field’s edit type is set to default, the field’s edit type at run time matches the data type of the property being displayed.

For detail screens displaying transactions or fetches, also known as wizard screens, the field edit type should always be considered carefully as these fields will be used to capture data from the users. The method of data entry provided to the user can have a significant impact on the applications usability, as well as the accuracy and validity of the data captured.

Fields for a detail screen can be hidden or displayed based on conditions checked by rules. Likewise fields can be enabled or disabled conditionally. the label for fields can be a simply text value, a hyperlink that executes a defined action, or can be committed entirely, leaving just the field itself with no label. Fields can be defined as read-only. This attribute affects fields on wizard screens (for transactions or fetches) or on fields for object screens when those fields do not target any object property.

The field includes several attributes related to its positioning on the screen, the viewable size of the field, and the amount of space within this size dedicated to the field’s label. Fields can also have a shortcut key associated with them, which will set the focus to the field when selected.

Detail screens are defined with a certain number of columns and rows. These are for the purpose of layout. A given fields position on the screen is defined by specifying the column and row in which the field’s upper-left corner should reside. Likewise, the fields width and height are also defined in terms of the number of columns wide and number of rows high. A detail screen is created with a default number of rows and columns which can be edited by the developer. Note that changing the number of columns or rows for a detail screen does not change the size of the screen. Rather, it results in a larger or smaller number of “pieces” to that detail screen for the purposes of field layout.

When changing the number of columns and rows for a detail screen, it is recommended this be done before fields are added to the screen. If these values are changed after fields have been added, the layout of those fields will be affected. If fields are positioned on rows 1-10, and the detail screen is then edited to contain only 8 rows, the fields on rows 9 and 10 will no longer be displayed and must be repositioned some where in the first eight rows.

Button Definition for All Screens

The button definition is common to both list and detail screens. A screen button defines a button control that appears on a Client screen. The button may be a standard button control, a tool bar button, a menu or menu item, or as a separator. A button is defined to execute an action when clicked or tapped, unless defined as a menu or separator. When executing an action, the button also defines the target object instance provided to the action for processing.

When developing mobile applications screen space is at a premium for many of the client device types in common use. For this reason, the button definition has multiple types. The type action button creates a traditional button control that when clicked executes a defined action. The exception to this is when the selected “action” is Popup Menu, which is one of the available options in the Action attribute of a button. When this is selected, the button will not execute an action. Rather, it is displayed with the defined label, plus an arrow pointing up. When selected on the client, a popup menu is displayed. Additional action buttons on the same screen can be defined to be displayed on this popup menu.

Application Menu is a button type that adds a menu item to the client’s menu bar, in the menu Actions. This menu is hidden unless at least one Application Menu button has been defined for the current screen. This type of button creates a menu item within this menu that, when selected, executes the defined action. This button type does not support image icons or the style attributes.

Toolbar Button is a button type normally used on Pocket PC devices, or devices with this form factor. It creates a button with no label and only an icon. The button resides below the screen in the toolbar of the client. When clicked it executes the defined action.

Separator is a button type that does not create any button or menu control. Rather, it is used to help organize buttons on the screen. When a separator is defined and the button is not defined to be displayed in a popup menu, additional space is placed at the position of the Separator button definition. When the separator button is placed in a popup menu, a menu separator is drawn at the position of the Separator button.

Buttons for List Screens

The button definition for list screens is defined to target, by default, the currently selected object or objects in the screen’s list control. Depending on the action being executed this may or may not be the proper selection. The type of object targeted by the object must match the object type for which the action has been defined. The exception to this is when the action is not defined for any object type (attribute For Object: -- None --).

Typically either the selected object or the parent to the collection being displayed by the list screen are the two items selected for the button target. Buttons that execute actions to navigate to another screen set, and that execute actions to instantiate an Edit or delete transaction are normally defined to target the currently selected object. Buttons that execute actions to instantiate Add transactions, or actions such as Transmit or CloseThisScreenSet should be defined to target the parent object of the collection being display in the list screen.

Buttons for Detail Screens

The button definition for detail screens is defined to target, by default, the object currently being displayed in the detail screen. In traditional development work within Agentry this was not often changed. However, in more contemporary applications developed using later versions of Agentry, the selection of a different button target has increased in frequency. this is due to many of the newer field edit types added to Agentry. Many of these fields display lists of objects, or a selection from a list. These fields then support the selection of a target for a button from that field’s current selection. This can be selected using the target browser within the Agentry Editor.