Select List Control
Add either a checkbox- or multi-select drop-down menu-style control from which the Request participant selects one or more options.
Control Description
The Select List control provides either a checkbox- or multi-select drop-down menu-style control from which the Request participant selects one or more options.
Set options that display in this control in one of the following ways:
Provide each option: For each option, enter a unique value that represents the option, and then enter the text that displays as the option. After your options are configured, sort the order in which they are to display in the control. Alternatively, provide options in the control in JSON format.
Reference data in a Request Variable: Reference data from the in-progress Request as options in this control. This data object must be part of the Request's JSON data model.
Reference a data source in the JSON data model: Reference data from a Data Connector that displays in this control as its options. Specify the data name, value, and content from the Data Connector. See a design example. Optionally, use a PMQL expression to limit which data to use as options based on the PMQL expression's criteria. The order that data objects present in the data object determines the order these options display in the control; options cannot be manually reordered.
Reference data in a Collection: Reference data from a Collection and display it as options in this control. Optionally, use a PMQL expression to filter the displayed options in real-time.
This control is only available for the following Screen types:
Conversational-type
Form-type
See Screen Types.
For documented examples of using this control, see:
Checkbox Functional Description
When using the Select List control with checkboxes, the control functions similarly to multiple Checkbox controls whereby multiple options may be selected. Unlike using multiple Checkbox controls, the Select List control includes all selected options as an array in the order that options are selected. This array becomes part of the JSON data model as shown in the example below in Preview mode.
Drop-Down Menu Functional Description
When using the Select List control as the drop-down menu, multiple options may be selected one at a time. Selected options have the following attributes:
Each selected option displays in the control.
Each selected option displays in bold-style text in the drop-down menu. Furthermore, a red-colored highlight displays when hovering over a selected option, rather than the default green-colored highlight for deselected options.
Follow these guidelines to deselect an item from the Select List control when using the drop-down menu style:
Select the option again from the drop-down menu.
The Select List control includes all selected options as an array in the order that options are selected. This array becomes part of the JSON data model as shown in the example below in Preview mode.
Add the Control to a Screen
Follow these steps to add this control to the Screen:
Configure the Select List control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a Select List control where you can select a method to receive notifications.
Settings
The Select List control has the following configurable settings in the Properties Panel:
Variable Panel Settings
Expand the Variable panel from the Properties Panel on the right to configure the following properties:
Configuration Panel Settings
Expand the Configuration panel from the Properties Panel on the right to configure the following properties:
Data Source Panel Settings
Expand the Data Source panel from the Properties Panel on the right to configure the following properties:
From the Data Source panel, select one of the following methods to specify options that display in the Select List control:
Provide options: Enter a unique value that represents each option, and then enter the text that displays as the option. After your options are configured, sort the order in which they are to display in this control. Alternatively, provide options in this control in JSON format.
Request data: Reference data from the in-progress Request as options in this control. This data object must be part of the Request's JSON data model. During the in-progress Request, the Select List control references a specified data array and object in the Request's JSON data model to display its values as options in that control. The order that data objects are in the Request's JSON data model determines the order these options display in the control; options cannot be manually reordered. See the following related topics:
Data Connector: Reference the data from a Data Connector's Endpoint as options in this control. These Endpoints a Data Connector references may be Application Program Interface (API) endpoints, Collection records, or other data source endpoints. During the in-progress Request, when the Select List control references data from the Data Connector, the control maps the Data Connector data to a specified JSON data array, variable or key name, or data object to become part of that Request's data. Data maps to the JSON data array in the same order it is retrieved from the Data Connector. Optionally, use a PMQL expression to limit which data to use as options based on the PMQL expression's criteria. The order that data objects return from the Data Connector determines the order these options display in the control; options cannot be manually reordered.
See Example: Dependent Select List Controls Display Countries and Regions.
Collection: Reference data saved in a Collection and display records from a Collection column. Optionally, use a PMQL expression to limit which data to use as options based on the PMQL expression's criteria. For an example, see Example: Dependent Select List Controls Display Countries and Regions from a Collection.
Provide Options
See the following procedures how to provide options for a Select List control.
Add an Option to This Select List Control
Follow these steps to add an option that displays in this control using Screen Builder:
Access the Data Source panel for this control while in Design mode, and then locate the Data Source setting.
In the Value setting, enter a value to represent the option in the Request data. This value must be unique from other values in this control. If the value is not unique to other Value settings in this control, the following message displays: An item with the same key already exists.
In the Content setting, enter the option that displays in this control.
Edit an Option for This Select List Control
Follow these steps to edit an option that displays in this control using Screen Builder:
In the Value setting, edit the value to represent the option in the JSON data model during in-progress Requests for Processes that use this Screen as necessary. This value must be unique from other values in this control. If the value is not unique to other Value settings in this control, the following message displays: An item with the same key already exists.
In the Content setting, edit the option that displays in this control as necessary.
Click Update. The edited option displays below the Options list label.
Delete an Option from This Select List Control
Follow these steps to delete an option from in this control using Screen Builder:
Click Delete.
Sort the Order of the Options
Follow these steps to sort the order of the options that display in this control using Screen Builder:
Set to Allow Multiple Selections and How Options Display
Follow these steps to set whether multiple selections can be selected from this control and how the options display:
From the Render Options As drop-down menu, select one of the following options:
Dropdown/Multiselect: Select the Dropdown/Multiselect option to display the control as a drop-down menu.
Best Practice When Configuring a Select List Control Within a Loop Control
Make note of best practices when configuring a Select List control's options when that control is within a Loop control. When referencing a JSON array from a data source, configure the Select List control to reference the JSON object containing the JSON array and not its values. Then duplicate the JSON array in the Loop control. See Duplicate the JSON Array in a Select List Control Used in a Loop Control.
Best Practice When Editing a Collection Using a Select List Control in a Loop Control
Make note of best practices when editing a Collection record using a Select List control in a Loop control, configure the Select List control's Type of Value Returned setting with the Single Value option. See Use Single Value instead Object in a Select List.
Make note of practices to avoid when referencing Request data for the options in a Select List control.
Design Panel Settings
Expand the Design panel from the Properties Panel on the right to configure the following properties:
Advanced Panel Settings
Expand the Advanced panel from the Properties Panel on the right to configure the following properties:
When the Select List control is configured with Provide Options, the Default Value setting compares numerical values as a string.
If the Select List is configured with Provide Options Using a JSON Schema, take care to enclose the numerical values in quotation marks (such as "1"
) because this can cause errors when comparing against the Default Value setting value.
If you need to compare default values other than a String-type value, enter the default value using JavaScript.