We've been working on this article. Please let us know how useful this new version is by voting.
Allows the user to select one or more values from a list of possible values.
Consider the following alternatives if your users need to select only one value from a list:
The Source Record List property defines the source of the list of possible values. You can get the list of values from an Aggregate or SQL element, or you can build your own list of Records.
The text for each value displayed in the List Box comes from the attribute set in the Source Attribute property.
The List Box widget allows users to select multiple values by default. You can configure the List Box widget to only allow users select one value from the list. Configure this behavior by setting the Selection Mode property to
Users can select multiple values from the list by pressing the
Ctrl key while simultaneously selecting the values.
Obtaining the values that the user selected
The Record definition must include a Boolean attribute to hold the user selection. One way of achieving this when you're using an Aggregate as the record source list is to an extra calculated attribute to the Aggregate with Boolean data type.
For example, the following Aggregate from a screen Preparation contains a calculated attribute named IsSelected. The List Box widget uses this attribute to store the information about the selected records. In the Aggregate definition, the value of this calculated attribute is
False, meaning that every row in the result list has this value, and that the List Box selection is empty by default.
After defining the source Aggregate with an additional calculated attribute for keeping the selection status of each Record, set the properties of the List Box widget.
In the example above, the List Box displays the names of users as selectable values. It uses the IsSelected attribute to store the information about the current selection. At runtime, each selected value from the list has the IsSelected attribute set to
When there's a Submit operation, you can access the list of Records through the List runtime property of the widget. This property includes updated values in the IsSelected attribute according to the items the user selected.
In the following example, the user selects the second value from a list (item
 from the List runtime property has its IsSelected attribute set to
Keeping the selection when refreshing the widget
You must take care when using Ajax refresh operations to refresh the List Box widget. Doing a refresh clears the currently selected values.
Executing any action that performs a Submit operation (for example, clicking on a button or link with the Method property set to
Submit) also clears the current selection of the List Box widget.
To maintain the selection when there's an Ajax refresh, you can follow an approach similar to the following:
Instead of using Aggregate results directly, define a local variable to use as the source list. For example, if your original Aggregate had the User entity as a source, define a local variable with data type "IsSelected, User Record List", where IsSelected is a Boolean attribute.
This allows each record to hold both the attributes of a User record and also the selection state.
In the Preparation, set this local variable to the List runtime property of the Aggregate.
In the List Box widget properties, set the Source Record List property to your local variable.
Create a new action that handles the On Change event of the List Box. To maintain the selection information, in the action flow, assign the value of the List runtime property of the List Box to the local variable, so that you keep the selection information.
Combining with other widgets and UI Patterns
If you're allowing users to select multiple values in a List Box widget, consider using the Dropdown Select UI Pattern together with the List Box. The Dropdown Select UI Pattern makes it easier for an end user to check the list items he already selected.
|Name||Identifies an element in the scope where it is defined, like a screen, action, or module.||Yes|
|Validation Parent||Specifies an Edit Record widget. Widgets with the same Validation Parent are validated as a group.|
|Source Record List||Current list of records displayed by the widget.||Yes|
|Source Attribute||Specifies the attribute of the records in the list to populate the widget.||Yes|
|Selection Mode||Specifies if the user can select only a single item or multiple items from the list.||Yes||Multiple||The possible values are: Multiple and Single.|
|Selection Attribute||Boolean attribute of the records in the list that holds if a value is selected or not. If using a list from an Aggregate, you can add a new Boolean attribute in the Aggregate.||Yes|
|Style Classes||Specifies one or more style classes to apply to the widget. Separate multiple values with spaces.|
|Visible||Boolean literal or expression that defines if the widget is displayed.||Yes|
|Enabled||Boolean literal or expression that defines if the widget is editable.||Yes|
|Property||Name of an attribute to add to the HTML translation for this element.||You can pick a property from the drop-down list or type a free text. The name of the property will not be validated by the platform.
Duplicated properties are not allowed. Spaces, " or ' are also not allowed.
|Value||Value of the attribute.||You can type the value directly or write expressions using the Expression Editor.
If the Value is empty, the corresponding HTML tag is created as property="property". For example, the nowrap property does not require a value, therefore nowrap="nowrap" is added.
|Destination||Screen action to be executed or a screen to navigate to when the value of the element changes.||It might be necessary to specify additional input arguments.|
|List||Collection of records returned by the performed query.||Record List|
|Valid||Always True for List Boxes. You can override this property value when performing custom validation.||Boolean|
|ValidationMessage||Message describing the built-in validation constraints not satisfied when 'Valid' is False. You can override this property value when performing custom validations.||Text|