Select List Control

Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during Requests. Ensure that the Variable Name setting value is a unique name from other controls in this Screen and contains at least one letter. This is a required setting.

Use the Variable Name setting value in the following ways:

• View the selection made in this control by its Variable Name setting's value. The Data Preview panel in Preview mode corresponds the option(s) the Request participant selects in the Select List control with that Select List control's Variable Name value. The Variable Name setting contains the selected option(s) as an array. In the example below, form_select_list_1 is the Variable Name setting's value.

  

• Reference this value in Visibility Rule setting expressions.

• Reference a property from the selected value when the Select List control is of type object in the current Screen or with a Nested Screen control. To do so, first reference this control's Variable Name value in a Calculated Property, then use this Calculated Property in the target control. As a best practice, do not directly reference the Variable Name setting of a Select List control.

Example

Consider the following example. A Select List control with Variable Name setting value account displays a list of accounts available at your bank.

When a user makes a selection, you want to display the selected account in a Line Input control on this Screen. Use the following best practice to reference the value of the Select List control.

1. Insert a Line Input control and set its Variable Name value. This example uses the Variable Name value AccountName.

   

2. Create a Calculated Property and set the Property Name setting to accountName.

3. In the JavaScript setting, enter the following JavaScript code:

   if (!this.account) {
       // if no account was selected return null
       return null;
   }
   return this.account.name;

   

See best practices when editing a Request variable name.

Edit the default label that displays for this control if necessary. New Select List is the default value.

Ensure that all Select List controls implemented in a Conversational-type Screen contain Label setting values. See Controls in Conversational-Type Screens Require Labels.

Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: No validation rule(s). See Validation Rules for "Validation" Control Settings.

Follow these steps to add a validation rule to this control:

1. Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.

2. Click the Add Rule button. The Select drop-down menu displays.

   

3. Select the rule that this control validates against.

4. Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.

5. Enter the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.

Follow these steps to edit a validation rule for this control:

1. Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.

2. Click the Edit icon for the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays.

3. Edit the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.

Follow these steps to delete a validation rule for this control:

1. Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.

2. Click the Delete icon for the validation rule to delete. A message displays to confirm deletion of the validation rule.

3. Click Delete.

Select to indicate that this control is required. This option is not selected by default. This is a quick way to add the Required validation rule.

In the Screen preview or during a Request, the control displays with a red-colored asterisk. If you submit the Screen without selecting this required Checkbox, this control displays Field is required in red-colored text.

Select to indicate that this control cannot be edited. This option is not selected by default.

Enter the placeholder text that displays in this control when no value has been provided. This setting has no default value.

Enter text that provides additional guidance on this control's use. This setting has no default value.

Follow these steps to reference data from the in-progress Request as options in this control:

1. Access the Data Source panel for this control while in Design mode.

2. From the Data Source drop-down menu, select Request Data.

   

3. In the Options Variable setting, enter from which Request variable, based on its Variable Name setting value, to use as options for this control. The Request variable from which to use as options must be an array. The options in the Select List control display in the same order as the Request variable lists items in its array. Optionally, use mustache syntax to indicate the Request variable name, especially if each option in this control derives from combining multiple properties within an array where each of its items contains one or more objects. response is the default setting. See Dependent Field Design Example Using Select List Controls.

   

4. In the Option Label Shown setting, enter the JSON object key name from within the JSON array containing the Request variable from which to display as each option in this control. To use all JSON object key names in the JSON object, do not enter a value into the Option Label Shown setting. Use JSON dot notation as necessary.

   For example, consider the following JSON array within Request data named accountTypes that contains two JSON objects, both of which their key names are type:

      "accountTypes": [

        {"type": "Life"},

        {"type": "Medical"}

      ]

   To reference both values from the key name type as options in the Select List control, use the following JSON dot notation in the Option Label Shown setting: data.accountTypes. The JSON array must contain JSON objects composed of key names and corresponding values, not just values like the following:

      "accountTypes": [

        "Life", "Medical"

      ]

   Optionally, use mustache syntax to indicate the JSON object key name from within the JSON array. content is the default value.

   

5. From the Show Control 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.

   • Radio/Checkbox Group: Select the Radio/Checkbox Group option to display the control as a group of checkboxes.

     

6. Select the Allow multiple selections option to allow multiple options to be selected from this control. Otherwise, only one option can be selected.

   

7. From the Type of Value Returned drop-down menu, select one of the following options:

   • Single Value: Select the Single Value option to indicate that only a part of the JSON object specified from the Option Label Shown displays as each option in this control. As a best and general practice, use single-value JSON objects.

   • Object: Select the Object option to indicate that the entire JSON object within each item of the array displays as each option in this control.

     

8. If the Single Value option from the Type of Value Returned setting is selected, the Variable Data Property setting displays. In the Variable Data Property setting, enter the JSON object key name from within the JSON array containing the JSON response that this control stores in that Request's data when this Screen submits. To use all items in the JSON array, do not enter a value into the Variable Data Property setting. Use JSON dot notation as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. Optionally, use mustache syntax to indicate the JSON key name from within the JSON array. value is the default value. See Dependent Field Design Example Using Select List Controls.

   

Follow these steps to reference data from a Data Connector as options in this control:

1. Access the Data Source panel for this control while in Design mode.

2. From the Data Source drop-down menu, select Data Connector.

   

3. In the Options Variable setting, enter the name of the JSON array containing the API's JSON response from which to reference its objects as options that display in this control after the Data Connector's Resource interacts with the API endpoint. The name of the JSON array is called response by default. Use JSON dot notation as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. response is the default value.

   

4. From the Show Control 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.

   • Radio/Checkbox Group: Select the Radio/Checkbox Group option to display the control as a group of checkboxes.

     

5. Select the Allow multiple selections option to allow multiple selections from this control. Otherwise, only one option can be selected.

   

6. From the Type of Value Returned drop-down menu, select one of the following options:

   • Single Value: Select the Single Value option to indicate that only a part of the JSON object specified from the Option Label Shown displays as each option in this control.

   • Object: Select the Object option to indicate that the entire JSON object within each item of the array displays as each option in this control.

     

7. If the Single Value option from the Type of Value Returned setting is selected, the Value setting displays. In the Value setting, enter the JSON object key name from within the JSON array containing the JSON response that this control stores in that Request's data when this Screen submits. To use all items in the JSON array, do not enter a value into the Value setting. Use JSON dot notation as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. Optionally, use mustache syntax to indicate the JSON key name from within the JSON array. value is the default setting. See Dependent Field Design Example Using Select List Controls.

   

8. In the Content setting, enter the JSON object key name from within the JSON array containing the JSON response to display as each option in this control. To use all JSON object key names in the JSON object, do not enter a value into the Content setting. Use JSON dot notation as necessary. Optionally, use mustache syntax to indicate the JSON object key name from within the JSON array.

   content is the default value.

   

9. From the Data Connector drop-down menu, select from which Data Connector to reference as a data source. If a Data Connector does not exist, this setting has no options.

   

10. From the End Point drop-down menu, select which Resource to reference from the selected Data Connector. A Resource is a Data Connector asset with which to interact with a data source, also called an End Point. These Resources are configured from the Data Connector itself. Depending on the Data Connector selected from the Data Connector Name drop-down menu, these Resources may reference Application Program Interface (API) endpoints, Collection records, or other data source endpoints.

    

11. In the PMQL setting, optionally enter a PMQL expression to filter which data in the JSON data array to display as options in this control based on which JSON objects in that array meet the PMQL expression's criteria.

    

Consider the following example of doctors who work in a clinic.

doctors = [
    {id: 1, name: 'Adam Ardin', gender: 'male'},
    {id: 2, name: 'Amanda Creek', gender: 'female'},
    {id: 3, name: 'Lucy Morales', gender: 'female'},
    {id: 4, name: 'Mindy Smith', gender: 'female'},
    {id: 5, name: 'Toby Tomlinson', gender: 'male'}
]

Use the following settings to reference this data array as options for this control:

• Element Name: doctors

• Value: id

• Content: name

Suppose that a new patient at the clinic indicates that she wants to see a female doctor. To filter doctors from this JSON data array who are female in the clinic so that only those objects display as options in a Select List control, use the following PMQL expression in the PMQL setting of that control:

gender = "female"

Follow these steps to reference data from a Collection as options in this control:

1. Access the Data Source panel for this control while in Design mode.

2. From the Data Source drop-down menu, select Collection.

   

3. From the Collection drop-down menu, select the name of the Collection from which to retrieve data.

   

4. From the Label drop-down menu, select the name of the Collection column that contains the data to be displayed as options in the Select List control.

   

5. From the Value drop-down menu, select the name of the Collection column that contains the data to be saved into Request data when a user makes a selection.

   

   The Label and Value drop-down menus can have the same or different Collection columns selected. Consider an example of a Collection with columns City Name and Zip Code. The Select List control can be configured in the following ways:

   1. Selecting City Name in Label and Value displays the name of all cities in the Select List control and save the name of the selected city in Request data.

   2. Selecting City Name in Label and Zip Code in Value, displays a list of cities, but saves the Zip Code of the selected city in Request data.

6. In the PMQL setting, optionally enter a PMQL expression to filter the data being retrieved from the Collection. If a filter criteria is specified here, the Select List control dynamically filters in real-time based on the specified PMQL expression.

   

7. Select the Ignore duplicates in list option to display repeating data only once in the Select List control.

   

See Example: Dependent Select List Controls Display Countries and Regions from a Collection.

Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.

Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.

Enter the default value this control displays. The default value can be assigned as a Request variable, text or JavaScript. When the Screen submits, the Request uses this control's default value unless the Request participant changes it. When using a Request variable in the Default Value setting, consider the following:

• If the Request variable is empty, the control does not display any value by default.

• When the Request variable is assigned a value for the first time, this value becomes the permanent default value of the control.

• Any further changes to the Request variable do not affect the default value of the control.

The Default Value setting supports using Request variables in mustache syntax. For example, if the Default Value setting is {{ FirstName }} {{ LastName }} from which a Request participant entered her first name and last name in separate controls (respectively) earlier in that Request, this control displays the contents of those controls by default during the Request.

There are two ways to enter the default value this control displays.

Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.

For example, this control displays if the variable value tip is 1. For a detailed example of the Visibility Rule setting, see Show or Hide Controls Based on Button Selection.

Note the following regarding how to use visibility rules:

• To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.

• Visibility rules override custom CSS settings.

Select on which device types this control displays:

• Desktop: The control displays only on desktop devices. Enable the Show for Desktop toggle key.

• Mobile: The control displays only on mobile devices. Enable the Show for Mobile toggle key.

• Both: The control displays on both desktop and mobile devices. Both toggle keys are enabled by default.

  

Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.

Then, use this name in the Custom CSS feature to apply CSS styling to this control as follows:

[selector='Submit Form'] {
    color: blueviolet;
}

Enter the string that provides a text alternative to this control for the following purposes:

• Assistive technology, such as screen readers, read the Aria Label setting value.

• This control has a visual indication of its purpose, such as a control that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.

The Aria Label setting value replaces the Label setting value. For example, if a control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.

Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.

See best practices for setting the tab order for a Screen's controls.

Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.