The control can be used to:

• Display a list of values where single or multiple items can be selected

1. Create a View .
2. Drag the List Box control onto the canvas. The control can be found in the Input section of the Controls found in the View Designer, see the Properties section below.
3. Configure the Type under the Data Source of the Properties section.
4. Configure the rest of the properties as required.
5. Configure rules as required.
6. Run the View.
7. Select one or more records to be actioned.

• Cannot filter a List Box control according to another control.

The List Box control interacts with other controls through rules. Depending on the control properties, there are certain actions where the control surfaces. Following are a few examples:

• Populate a list control with data - The control can be populated if it has a SmartObject-based data source
• For-each looping conditions - The control can be used in a for-each loop condition
• Set a control’s properties - The control's settable properties can be configured using this action
• Execute a control’s method
• Show/Hide - The Visible property allows for the control to be shown or hidden through rules
• Enable/Disable - The Enabled property allows for the control to be enabled or disabled through rules 
• Data Transfer - Data can be transferred from items listed in the Context Browser to the List Box control
• Specify the edit state of View and Form Controls

The List Box control is available in the Input section of the Controls tab found in the View Designer.

When clicking on the ellipsis next to Data Source Type, the Configure Data Source screen opens. Configure the data source to be used to populate the List Box control.

A Boolean (Yes/No) property can be configured that will be used as the Default value in the Data Source Configuration popup. The value(s) set to true for the Boolean property will be returned to the control at runtime and be displayed according to the control used.

How to use the default value

• Create a SmartObject with a property of type Yes/No to be used to capture the default value.
• Generate an Item View and create some data for the SmartObject. We've used the Marital status SmartObject with the following data:
  • Single
  • Married
  • Divorced
  • Widowed
  Below is a List View displaying the values captured. Note the Single value has been configured as the default.
  
• Create another View that will be using the SmartObject containing the default value, for example an Employees Item View.
• Edit the View and drag a List Box control onto the canvas.
• Select the Marital status SmartObject as the data source of the control and the property used to identify the default in the Default Value field.
  
• Save the configuration.
• Run the View and note the default of the control.
  

When selecting to Use a static list of values in the control and clicking on the ellipsis, the Fixed List Configuration screen opens. The ability is provided to configure a Value-Display pair where the value of the Value field is stored in the SmartObject, while the value of the Display field is displayed to the user. The Value is then used to reference a Display value that will be displayed to the user during runtime.

Design time configuration

Runtime

Considerations

• Blank values are permitted.
• Values do not need to be unique which might cause some logical errors.
• The List Box control can have more than one default.
• When the View's Clear method is executed, the control will revert to the default value, not a blank value.

The ability to define the amount of rows/columns to be used as a display is provided. The Stacked by and No. of items properties of the control can be configured to achieve this. When stacking by Rows, the layout will be from left to right until the number of items per row has been reached, then a new row will be created. When stacking by Columns, the layout will be from top to bottom until the number of items per column has been reached, then a new column will be created. The properties are located in the Settings section as shown below:

See the following examples:

Stacked by Rows
Number of items = 4

Stacked by Columns
Number of items = 4

The option to cache the SmartObject data is available to allow for client side filtering. This is especially useful when using a SmartForm on a mobile device for example and data is required to be available offline. The control's dataset will be populated on initial load, any other changes to the underlying data source's data will not reflect in the current session until another server call is forced to update the dataset. To enable the caching of data, simply select the Cache the data option on the Configure Data Source screen.

How caching is applied

It is important to note that the user is not required to configure anything except selecting the Cache the data option on the Configure Data Source screen to affect caching. The rules are automatically configured by the server. Designers can however remove these rules and place them somewhere else depending on their need. This is just an explanation of how caching is applied by the system.

Following is a diagram with an explanation of how the caching is applied in the background to enable client side filtering.

 When selecting the Cache the data option on the Configure Data Source screen, the following two actions are automatically added to the View Initialize event:

• Load list control cache with data
• Populate list control with cached data

Example:

• A user accesses a SmartForm on a mobile device.
• When the View initializes, the action to Load list control cache with data is executed (1 in diagram)
• Then the action to populate list control with cached data is executed (2 in diagram)
• The user is able to select updated data from the List Box on the SmartForm.
• The device goes offline and the user is still able to access the information in the List Box.

How caching is applied with cascading data

If the option to filter according to another control was selected on the Configure Data Source screen together with the cache the data option, the following action is automatically added to the View Initialize event;

• load the list control (child control) cache with data
  

and to the change rule of the parent control:
• populate list control (parent control) with cached data
  

Considerations

• If the cached data is filtered, the filter can be removed to bring back all the data.
• Additional records added to the dataset will not reflect until cached data is loaded again.