ProcessMaker Platform
processmaker.com
Guides
Resources
Developer Corner

Select List Control Settings

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

This control is only available for the following Screen types:

See Screen Types.

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.

Permissions Required

Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:

  • Screens: Edit Screens

  • Screens: View Screens

See the Screens permissions or ask your Administrator for assistance.

Add the Control to a Screen

Permissions Required

Permissions are required to do this.

Design Best Practice

Avoid designing with more than 25 controls in one Screen.

Follow these steps to add this control to the Screen:

  2. View the Screen page to which to add the control.

  4. Drag the Select List icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.

  6. Configure the Select List control. See Settings.

  7. Validate that the control is configured correctly. See Validate Your Screen.

Below is a Select List control in Preview mode.

Move the Control on the Page

After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.

Permissions are required to do this.

Follow these steps to move a control to another location on that Screen page:

  3. Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.

Copy the Control with its Settings

Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.

Permissions are required to do this.

Follow these steps to copy a control:

  1. Select the control to be copied.

As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.

Delete the Control from a Screen

Permissions are required to do this.

Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.

Follow these steps to delete a control from a Screen page:

  1. Select the control to be deleted.

Settings

Permissions are required to do this.

The Select List control has the following panels that contain settings:

Variable Panel Settings

Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.

Below are settings for the Select List control in the Variable panel:

Variable Name

Use the Variable Name setting value in the following ways:

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

    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.

Label

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

Validation Rules

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.

  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.

  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.

  3. Click Delete.

Configuration Panel Settings

Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.

Below are settings for the Select List control in the Configuration panel:

Placeholder Text

Helper Text

Data Source Panel Settings

Click the control while in Design mode, and then click the Data Source panel that is on the right-side of the Screen Builder canvas.

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. Note that the Data Connector package must be installed for this option to be available.

    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.

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:

  1. Access the Data Source panel for this control while in Design mode, and then locate the Data Source setting.

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

  6. 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:

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

  5. In the Content setting, edit the option that displays in this control as necessary.

  6. 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:

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

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

Reference Request Data

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 Request data, 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.

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.

  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"

    ]

  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.

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

Reference a Data Connector

Package Required

Note that the Data Connector package must be installed for this option to be available. T

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.

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.

  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.

  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.

  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.

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"

Design Panel Settings

Click the control while in Design mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.

Below are settings for the Select List control in the Design panel:

Text Color

Background Color

Advanced Panel Settings

Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.

Below are settings for the Select List in the Advanced panel:

Default Value

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.

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. 

[
    {
        "value": "1",
        "content": "Joyce"
    },
    {
        "value": "2",
        "content": "Natty"
    },
    {
        "value": "3",
        "content": "Franny"
    },
    {
        "value": "4",
        "content": "Beatty"
    },
]

If you need to compare default values other than a String-type value, enter the default value using JavaScript.

Visibility Rule

Note the following regarding how to use visibility rules:

CSS Selector Name

See the following best practices regarding custom CSS in Screens:

Aria Label

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 button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.

Tab Order

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.

Related Topics

Screen TypesScreen Builder ModesValidate Your ScreenEdit Your ScreenCheckbox Control SettingsDate Picker Control SettingsFile Download Control SettingsFile Preview Control SettingsFile Upload Control SettingsGoogle Places Control SettingsImage Control SettingsLine Input Control SettingsLoop Control SettingsMulticolumn / Table Control SettingsNested Screen Control SettingsPage Navigation Control SettingsRecord List Control SettingsRich Text Control SettingsSaved Search Chart Control SettingsSignature Control SettingsSubmit Button Control SettingsTextarea Control SettingsExpression Syntax ComponentsValidation Rules for "Validation Rules" SettingsReference Magic Variables in ProcessMaker Platform Assets
PreviousSaved Search Chart Control SettingsNextSignature Control Settings

Last updated

Logo

© 2024 ProcessMaker, Inc. All Rights Reserved. Except as otherwise permitted by ProcessMaker, this publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose.