Developer

Detail Screen Fields

Define different types of detail screen fields.

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.

You can select several different edit types for a field definition. This edit type significantly impacts the field’s behavior on the Agentry Client. Several attributes are common among most fields regardless of edit type. Some field edit types include additional attributes specific to the edit type selected for the field definition.

A field definition can target a property within the definition it displays. The value of that property is displayed to the user and, for transaction and fetch screens, the user may be able to edit that value. The value of the field is assigned to the property when the user advances the wizard past that screen, for example, when clicking a Next button or Finish button.

The field may also target other definitions within the application. If the target of a field is not a property definition, the value of the field is not copied to that definition. It uses it as a data source for the value to display. You can select these targets using the target browser, and can include other fields on the current screen or other screens within the same screen set.

When the target is another screen field that is one of the edit types for displaying complex tables, you can select a complex table record field from the currently selected record in that target screen field. The target for a screen field can also include a field on screens in other screen sets, provided those screen sets currently exist on the Agentry Client, but are hidden from view due to the focus being on the current screen.

A field on a wizard screen displaying a property value enforces the data limits of that property. This means minimum and maximum values or string lengths defined for the target property are enforced by the field definition. For strings, user cannot enter more than the maximum number of characters. For numeric values, the target property’s attributes related to precision and maximum values are enforced. If a user's entry does not meet the minimum values requirement, the user receives an error message when trying to advance the wizard.

You can define the labels for a field as static text or as a hyperlink. You can define hyperlink labels for a field displayed on a detail screen that displays an object instance. When a label is defined as a hyperlink, an action executes when the user clicks that label.

Fields can have their displayed value set through an update rule. These fields can still target a property, normally for transactions and fetches, in which the value of the field as set by the update rule is the value assigned to the property when the user advances the wizard. Normally, you would not use this method when displaying an object.

Fields may also be hidden and/or disabled via rule evaluation. A hidden field is not displayed on the detail screen. An optional behavior related to a hidden field is disabling that field when it is hidden. A field may also be disabled via a separate rule independent or in lieu of a hidden rule. A disabled field on a wizard screen does not enforce any required values as defined by the target property.

Fields are positioned and sized on the detail screen using columns and rows. The position of a field is set based on the upper-left corner of the field and is specified using the row and column position. The width of the field is specified in columns, and the height is specified in rows, counting from the position in the field in which it is placed.

Common Field Definitions

The following field definitions are common to most or all field edit types and result in the same behaviors for most of the different types of fields.
Attribute Description
Object/Transaction Property Sets the property definition or other definition whose value is displayed by the field and/or that is updated with the field’s value. This definition is “targeted” by the field. This attribute can be set to “-- None --”, in which case the value displayed by the field must come from some another source.
Name The unique internal name of the field definition, and must be unique among all fields within the same detail screen. This is commonly set to match the name of the property that the field targets.
Label (Optional) Sets the label for the field. This text is displayed on the left side of the field. This label text is rendered as a hyperlink if that behavior is also defined. If not set, no label nor the space for one appears on the screen.
Placeholder This attribute references a rule definition that returns a string value used as the placeholder for the field definition.
Edit Type Sets the edit type for the field, selected from a list. You can set it to “-- Default --”, in which case the edit type of the field matches the data type of the property being displayed.
Read-only Sets the field to be read-only or read/write. Fields targeting an object property are always read-only and are not affected by this attribute.
Shortcut Key Sets a key or key combination that, when entered by the user, sets the focus to the field on the detail screen. This can include both keyboard keys and hardware keys on the client device.
Format Sets any format text for the value displayed in the field. If using a format string, set the Object/Transaction Property attribute to “-- None --.”
Label Width Sets the number of characters that can be displayed for the label on the screen. Character size varies depending on the font used for the label text. The total size of a field on the screen does not change based on the Label Width. The amount of space within the specified size that is given to display the field is decreased as the Label Width is increased. Label text longer than the space provided based on the Label Width is wrapped on the screen
Position - Column & Row Sets where the upper-left corner of the field is displayed. The column and row specified determines how many columns and rows the detail screen contains.
Size - Width & Height The Size attributes specify the Width and Height of the field. The Width is set to the number of columns the field should span and the Height is set to the number of rows.

Field Styles

These attributes define field styles for the parent control.

Attribute

Description

Field

The style definition for the field.

Focused Field

The field is focused for input.

Read-Only Field

The field is read-only.

Label

The field label text.

Hyperlink

The field is a hyperlink.

In Progress Edit

The field can be edited.

Rules/Hyperlink/Special Value Attributes

These attributes define the rules, hyperlinks, and special value attributes for the parent control.
Attribute Description
Change Focus Determines if the field keeps the focus of the screen. If this attribute is selected, the focus is directed to the next field on the screen. If not selected, the field keeps the screen focus until the user selects another control.
Update Rule References a rule definition evaluated in the context of the definition being displayed and expected to return a string value. This rule is evaluated each time the user interacts with any part of the detail screen. The value returned by the rule is displayed in the field. This rule does not change the value of the field if it returns the same value for two or more consecutive evaluations. The external field-OpenUI control edit type is defined to call out from a field to an OpenUI control.
Hidden Rule The external field-OpenUI control edit type is defined to call out from a field to references a rule definition that is evaluated in the context of the definition being displayed, and expected to return a Boolean value. If the rule returns true, the field is hidden on the detail screen. If false, the field is displayed.
Disable When Hidden When selected, the field is disabled whenever the Hidden Rule returns true. The Enable Rule is not evaluated. If not selected, the Enable Rule determines whether the field is enabled independently or if the field is hidden.
Enable Rule References a rule definition evaluated in the context of the definition being displayed and expected to return a Boolean value. When the rule returns true the field is enabled; when false, the field is disabled. A disabled field is grayed out. A disabled field does not update its target property and no attributes related to the required property value is enforced.
Clear When Disabled When selected, disabled fields clears any value in the transaction property it targets. Disabled fields are those disabled by the Enable Rule, or those with the Disable When Hidden attribute is true and the field is hidden by its Hidden Rule. This attribute only affects fields with the following edit types:
  • Boolean
  • Date
  • Date and Time
  • Decimal Number
  • Duration
  • Identifier
  • Integral Number
  • String
  • Time
Pattern Recognizer This attribute enables or disables the behavior of recognizing certain patterns within text values of the field, for example, e-mail addresses or phone numbers. When set to true, the user can hold down the hyperlink text to invoke some OS-defined operation. Examples may include allowing the user to compose and send an e-mail message, send a text message, or place a call to a phone number.
Hyperlink - Action This attribute references an action that enables the hyperlink behavior for the field’s label. The label is displayed as hyperlink, and the user can click on the label to execute the defined action. This behavior is only valid for fields displayed on an object screen. If the field type is a Tile Display, the user can click in any part of the control as well as the field's label to execute the action.
Hyperlink - Target Sets the target object for the Hyperlink Action.
Hyperlink - Shortcut Key Sets a shortcut key for the hyperlink. When this key combination is entered on the Client, the defined Hyperlink Action is executed.
Special Value Sets a default value for the field. When a field has a Special Value defined, a radio button is displayed on the detail screen as a part of the field’s definition. It appears between the label for the field and the actual field control. A second radio button appears to the immediate left of the field control. When the first radio button is selected, the Special Value defined for the field is set as the field's actual value, which then updates the property targeted by the field. When the second radio button is selected, the field control becomes enabled, and the user can enter a value.
Display Value The value to display in the field when the property value is equal to the field’s special value. This only impacts fields on detail screens displaying an object instance.
Auto Label and Width This attribute can contain a label for the first radio button displayed for special value fields. This label is displayed to the right of the radio button and can indicate to the user that they are selecting the default value.
Edit Label and Width This attribute can contain a label for the second radio button that enables the field control on the Agentry Client. This label is displayed to the right of the second radio button and can indicate to users that its selection requires them to enter a value.

External Field

These attributes define external fields for the parent control. You also need to define OpenUI code to handle the data exchange.

Attribute

Description

Scan Settings

(Open Scan) Used to provide your own scanning interface to something like NFC, RFID or other input you want to treat as a scanned value. The value your Open Scan code passes to Agentry as a scan value which triggers the default controls.

External Values

Reference external values beside the property the control extends from your OpenUI control. For example, you can use it to pass specific values to your control.

Agentry Values

Reference other values beside the property the control extends from your OpenUI control. For example, you can use it to make your control more generic by passing in configuration values upon which your control reads and acts.

Actions

Defines the Agentry actions your OpenUI control can invoke and what their target is. From within your Open UI code you can then trigger these actions to execute. For example in the GIS control you can select a point on the map and call an Agentry Action to create a new work order which would then display the Agentry transaction wizard screens.

Scanner

These attributes define scanner styles for the parent control.

Attribute

Description

Label Types

The scanner label types.

Minimum Length

Minimum length of the barcode.

Maximum Length

Maximum length of the barcode.

Allow Typing

Whether to allow the user to type data in the field.

Show Scan Button

Whether to show the scan button.

Maintain Scan Focus

Whether to maintain scan focus during the scan.