Form Element Items

Some form elements present a list of items that the user can select from. For example, a list box has options, a check group has checkboxes, and a button bar has buttons.

Examples of form element items

Providing the values for a form element's items is called populating the element. For example, in the screen capture, the list box is populated with the names of US states.

When you add a form element with items to a form, you must specify how to populate the element. There are two main ways to populate an element:

For information on configuring items, see:

Configure Auto Complete Suggestions

Configure the Buttons in a Button Bar

Configure the Checkboxes in a Check Group

Configure the Options in a Drop Down List

Configure the Items in an Item Picker

Configure the Options in a List Box

Configure the Radio Buttons in a Radio Group

Properties of Form Element Items

The following table describes the properties of form element items.

Because every type of form element is different, form elements do not have every property that is listed in the table. The table indicates which form elements each property applies to.

The table gives the names for each property: its name in the Properties panel and its name in expressions. Sometimes the names only differ in capitalization, for example, Visible (in the Properties panel) and visible (in expressions).

Properties of Form Element Items

Causes Validation

Applies to: Button Bar

Type: Boolean

Name in Properties Panel: Causes Validation

Name to Use in Expressions: validates

Indicates whether clicking the button causes the form to validate.

Checked

Applies to: Check Group, Item Picker

Type: Boolean

Name in Properties Panel: Checked

Name to Use in Expressions: checked

Indicates whether the item is currently selected.

Default

Applies to: Button Bar

Type: Boolean

Name in Properties Panel: Default

Name to Use in Expressions: default

Indicates whether the button is to be treated as clicked if the form is submitted automatically, for example, if the user presses Enter instead of clicking a button.

Enabled

Applies to: All form elements with items

Type: Boolean

This property does not appear in the Properties panel

Name to Use in Expressions: enabled

Indicates whether the item is enabled in the running workflow. When an item is enabled, the user can select the item. When an item is disabled, the user can see the item but cannot interact with it. Disabled items appear dimmed.

You may want to change the enabled property at run time depending on the user's input in a previous form element.

Label

Applies to: All form elements with items

Type: String

Name in Properties Panel: Label

Name to Use in Expressions: label

The item's text.

Selected

Applies to: List Box

Type: Boolean

Name in Properties Panel: Selected

Name to Use in Expressions: checked

Indicates whether the item is currently selected.

Tooltip

Applies to: Button Bar, Check Group, Drop Down List, List Box, Radio Group

Type: String

Name in Properties Panel: Tooltip

This property cannot be used in expressions

A message that displays when the user hovers the mouse pointer over the item.

Value

Applies to: All form elements with items

Type: Any

Name in Properties Panel: Value

Name to Use in Expressions: value

The value associated with the item.

In a button bar, configuring a value for a button causes the form to submit (exit) after the user clicks the button and the form passes validation. You can also use the value to determine which button was clicked.

Visible

Applies to: All form elements with items

Type: Boolean

Name in Properties Panel: Visible

Name to Use in Expressions: visible

Indicates whether the item is visible in the running workflow.

You may want to change the visible property at run time depending on the user's input in a previous form element.

Access Form Element Items in Expressions

Each item in a form element has a unique key that you can use to access the item.

Item keys are strings. If you configure the items manually in Workflow Designer or you create them using the Get Form Element Items From Features or Get Form Element Items From Collection activity, the topmost item has key "0", the second item has key "1", the third item has key "2", and so on. If you use some other method to create the items, they will have whatever string keys you give them.

For example, to access a list box's topmost item in an expression:

$form1.state.listBox1.items["0"]

If the items are objects, then you can access the item's properties, such as the item's value property, like this:

$form1.state.listBox1.items["0"].value

Do not confuse the items in a form element with the items in the form element's value. A form element's value has an items array that contains the element's selected item(s). The items in the array are indexed numerically: 0, 1, 2, and so on.

For example, compare the following:

  • Topmost item in a list box:
  • Value of the topmost item in a list box:
  • Topmost selected item in a list box:

$form1.state.listBox1.items["0"]
$form1.state.listBox1.items["0"].value
$form1.state.listBox1.value.items[0]

© 2018 Latitude Geographics Group Ltd. All Rights Reserved.

Documentation Version 5.9