Skip to main content

 

 

 

 

Template:OutSystems/Documentation_KB/Breadcrumb_New_Layout

 

 

Template:OutSystems/OSLanguageSwitcher

 

Applies only to Traditional Web Apps

 

 

OutSystems

List Box Widget

Template:OutSystems/Documentation_KB/ContentCollaboration
  • Edit
    Collaborate with us
    Edit this page on GitHub
  • 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.

    Example of a List Box Widget

    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 Multiple or Single, respectively.

    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.

    Calculated attribute IsSelected added to the Aggregate

    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.

    Properties of a List Box widget in Service Studio

    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 True.

    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 [1] from the List runtime property has its IsSelected attribute set to True):

    List Box runtime properties

    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:

    1. 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.

      Local variable and its Record definition

      This allows each record to hold both the attributes of a User record and also the selection state.

    2. In the Preparation, set this local variable to the List runtime property of the Aggregate.

      Assign Aggregate results to local variable

    3. In the List Box widget properties, set the Source Record List property to your local variable.

    4. 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.

      Assign List runtime property to SelectedUsers local variable

    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.

    Properties

    Name Description Mandatory Default value Observations
    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
    Extended Properties
    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.
    On Change
    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.

    Runtime Properties

    Name Description Read Only Type Observations
    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
    Id Identifies the widget instance at runtime (HTML 'id' attribute). You can use it in JavaScript and Extended Properties. Yes Text
    • Was this article helpful?