Though the Checkboxes component offers similar functionality, some scenarios require a Multi-Select Dropdown component. For example, if you have more than six options or don't want your full list of options shown on the page at all times, you can use the Multi-Select Dropdown component.
Examples of when to use a Multi-Select Dropdown component are:
Which countries have you visited in the last five years? Select all that apply.
Which of these products are you interested in? Select all that apply.
To learn more about general component settings and those that display when a component is associated with Data Models, view our General Component Settings article.
Display Panel
Field Text
Setting
Description
Property ID
A Property ID is the unique field ID used by Unqork to track and link components in your module.
Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.
User-friendly labels make your module more accessible. Keep labels short and descriptive (a word or two) using title case. For longer entries, use sentence case.
Placeholder Text
A short prompt telling end-users the expected value of an input field. For example: Enter your Social Security Number. Placeholder Text displays inside the input field until the end-user begins an entry.
Contextual Help
Setting
Description
Tooltip
A short hint that displays when an end-user positions their cursor over the (Tooltip) icon. Tooltips can display across more than one line.
Default State Options
Setting
Description
Read Only View
When set to (ON), the component is display-only. If another component sends content to the field, the end-user can view that content. Otherwise, end-users see the word None.
By default, the Read Only View toggle is set to (OFF).
Disable User Input
When set to (ON), end-users cannot interact with or edit the Express View's input field or element. When end-users hover over the field, their cursor changes to alert them to the status change.
By default, Disable User Input is set to (OFF).
Hide Field
Displays or hides the component from view. Setting Hide Field to (ON) hides the component in Express View. Setting it to (OFF) displays the component. The component is always visible in the Module Builder.
By default, Hide Field is set to (OFF).
Formatting
Setting
Description
Allow Multiple Selections
Setting the Use Input Mask toggle to (ON) makes the Input Mask and Format Data With Mask options available. Setting the toggle to (OFF) hides these options from view.
By default, the Use Input Mask toggle is set to (OFF).
Show Clear Button
When set to (ON), a Clear button displays after an end-user selects one or more options. The Clear button removes whatever selection(s) your end-user made.
By default, the Show Clear Button toggle is set to (OFF).
Hide Chevron
When set to (ON), the arrow (chevron) to the right of the component is hidden.
By default, Hide Chevron is set to (OFF).
Set Dropdown Menu Height
Sets the number of search result rows the component displays when filtered by an end-user. If there are more options than the number entered, your end-user can scroll to view them all. Or, they can enter a value to navigate to relevant results.
Item Template
Lets you choose which column of data you want to display as the label for the drop-down options. Replace the word label with your chosen attribute in the following string format: <span>{{ item.label }}</span>.
Data Panel
Data Storage
Setting
Description
Store Data in Database
The Store Data in Database setting affects how data persists through your application. When set to (ON), Unqork stores values entered into the field to the database (server-side submission). This occurs in three scenarios:
Navigating between Panels in a Navigation component. On navigation between pages (Panels), the component’s value saves to the database.
Triggering a module save event using a Button component with an Action Type of Save.
Navigating between screens of a workflow. On navigation between screens, the component’s value saves to the database.
By default, workflows persist data from all fields in the client-side submission when navigating between screens. However, only values from fields with Store Data in Database enabled store in the server-side submission.
Set the toggle to (OFF) when you don’t want to store the values from this field in the database.
When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response.
Store Data in Database also affects what data is tracked using Unqork’s built-in tracker. When the Enable Tracker and Track Value toggles are set to (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.
Data Source Types
There are three methods you can use to populate a Multi-Select Dropdown component: Values, URL, and Data Reference Key.
Values
Selecting Values displays a table where you can enter each option and its value.
Setting
Description
Option Label
Each option needs an end-user-facing label describing the choice that it represents. Enter your Option Labels using this column.
After you create an option, another row displays for you to create the next option.
In Express View, the dropdown list searches and filters using the Option Label and Data Source values.
URL
To use data not stored in a specific component, select URL. Generally, this data lives in two places:
External to Unqork and pulled into the component using an external API call.
Internally and stored as a Data Collection.
To use an external API call, reference the provider's documentation. You'll find the API's URL address and the information you need to filter the data. To learn more, see our Using an External API in a Dropdown Component article.
To reference Data Collections in Unqork, use the Data Collections tab at the Application Level. Click Create Data Collection to create a new Data Collection. Or, explore the available Data Collections and use one of them.
Enter the information to display in the drop-down selections. These are your end-user's options. For external APIs, you'll find this information in the API documentation. To pull data from a Data Collection, enter the column header you want to use.
Select an external service configured through Unqork's Services Administration. This auto-populates the other required fields, including the Data Source URL.
Data Source URL
For an API to retrieve data, you need the API's URL information. In this field, enter the API information as obtained from the API documentation. Add additional filters at the end of the URL if you want to drill down to a specific type of data.
Value Property
If a data set includes a column for values, enter the column's name here.
If not specified, the application uses the option label.
Data Path
If using an API call to populate the component, enter a specific data property to reference here. This is useful if you want to show one piece of a larger data set in your Multi-Select Dropdown component.
Label Path
This field refers to the option labels you want to pull. Enter the option label's column header in this field.
Filter Query
Provide additional filtering using query parameters. Parameters append to the end of the Data Source URL. Query parameters can be static or dynamic. For example, name={{data.groupName}}.
Search Query Name
The name of the search query string parameter used when sending a request to filter results. The server at the specified URL must support this query parameter.
Refresh On
This field displays a list of the other components in your module. You can select a component here to refresh your Multi-Select Dropdown. When your end-user interacts with the selected component, the Multi-Select Dropdown resets.
You can also select Any Change. This refreshes the Multi-Select Dropdown if your end-user interacts with any of your components.
This setting watches other components in your module. The more components the component watches, the more performance issues can occur. It’s also important to note that processes large amounts of data on the client side will also impact performance.
Refresh Delay
Works with the Refresh On setting to set the number of milliseconds that pass before refresh. Once typing has finished, the delay begins.
The component has a minimum Refresh Delay of 250 ms, which is the default for this field.
Limit Number of Items
Limits the number of matching responses when working with large data sets. For example, an API might return more responses than you want to display, even when your end-user starts typing. Here, you can set a limit on how many results display.
Disable Limiting Response
When set to (ON), the request won't include the limit and skip options in the query string.
By default, this setting is (OFF).
Search Parameters are Required
When set to (ON), search parameters must be present to execute the search.
By default, this setting is (OFF).
Clear Value on Refresh
When set to (ON), the selected value is cleared after the Refresh On setting triggers.
By default, this setting is (OFF).
Authenticate
When set to (ON), authentication headers from the application are sent to the Data Source URL destination.
By default, this setting is (OFF).
Disable Filter Application
When set to (ON), filter parameters are not applied.
By default, this setting is (OFF).
Data Reference Key
Using the Data Reference Key option, data from another component populates the Multi-Select Dropdown component. You'll most often do this with a Data Table component. Add your data to the Data Table component. Then, reference it in your Multi-Select Dropdown component's configuration menu.
Think of this as a hybrid option of Values and Data Collections to populate your Multi-Select Dropdown component. You still use data stored in Unqork, but it's data from your module instead of a Data Collection.
Limits the number of matching responses when working with large data sets. For example, an API might return more responses than you want to show. Here, you can set a limit on how many results display.
Refresh On
This field displays a list of the other components in your module. You can select a component here to cause your Dropdown to refresh. When your end-user interacts with the selected component, the Dropdown resets.
Here, you can also select Any Change. This refreshes the Dropdown if your end-user interacts with any of your components.
This setting watches other components in your module. The more components the component watches, the more performance issues can occur. It’s also important to note that processes large amounts of data on the client side will also impact performance.
When set to (ON), the end-user must enter a value in the component's visible fields. When set to (OFF), the input is optional.
By default, Required is set to (OFF).
Required Error Message
A custom error message that displays below a required field. The error message displays when the end-user tries to save or submit the module without completing the required field.
Advanced Panel
Additional Validation Options
Setting
Description
Require Unique Submission Data
When set to (ON), the data submitted for this field must be unique and not submitted before.
By default, the Require Unique Submission Data toggle is set to (OFF).
Don't Allow Unique Values
When set to (OFF), your end-user can enter a custom value in the Dropdown field. This custom value saves and stores, even if the input doesn’t match existing values in the Dropdown. When set to (ON), your end-user can only select an existing value from the Dropdown.
By default, the Don't Allow Unique Values toggle is set to (OFF).
Updated CSS styling applies to all components that reference this custom class name.
Adding a Multi-Select Dropdown Component
Use a Multi-Select Dropdown to ask your end-user what vehicle types they own. Because the end-user could own multiple vehicle types, enable the Allow Multiple Selections setting. As the end-user selects vehicle types, they display above the drop-down as a button.
Configure the Multi-Select Dropdown Component
Configure a Multi-Select Dropdown to contain a list of vehicles the end-user can select from.
1.
Drag and drop a Multi-Select Dropdown component onto your canvas.
Though the Checkboxes component offers similar functionality, some scenarios require a Multi-Select Dropdown component. For example, if you have more than six options or don't want your full list of options shown on the page at all times, you can use the Multi-Select Dropdown component.
Examples of when to use a Multi-Select Dropdown component are:
Which countries have you visited in the last five years? Select all that apply.
Which of these products are you interested in? Select all that apply.
To learn more about general component settings and those that display when a component is associated with Data Models, view our General Component Settings article.
Display Panel
Field Text
Setting
Description
Property ID
A Property ID is the unique field ID used by Unqork to track and link components in your module.
Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.
User-friendly labels make your module more accessible. Keep labels short and descriptive (a word or two) using title case. For longer entries, use sentence case.
Placeholder Text
A short prompt telling end-users the expected value of an input field. For example: Enter your Social Security Number. Placeholder Text displays inside the input field until the end-user begins an entry.
Default State Options
Setting
Description
Read Only View
When set to (ON), the component is display-only. If another component sends content to the field, the end-user can view that content. Otherwise, end-users see the word None.
By default, the Read Only View toggle is set to (OFF).
Disable User Input
When set to (ON), end-users cannot interact with or edit the Express View's input field or element. When end-users hover over the field, their cursor changes to alert them to the status change.
By default, Disable User Input is set to (OFF).
Hide Field
Displays or hides the component from view. Setting Hide Field to (ON) hides the component in Express View. Setting it to (OFF) displays the component. The component is always visible in the Module Builder.
By default, Hide Field is set to (OFF).
Contextual Help
Setting
Description
Tooltip
A short hint that displays when an end-user positions their cursor over the (Tooltip) icon. Tooltips can display across more than one line.
Formatting
Setting
Description
Allow Multiple Selections
Setting the Use Input Mask toggle to (ON) makes the Input Mask and Format Data With Mask options available. Setting the toggle to (OFF) hides these options from view.
By default, the Use Input Mask toggle is set to (OFF).
Show Clear Button
When set to (ON), a Clear button displays after an end-user selects one or more options. The Clear button removes whatever selection(s) your end-user made.
By default, the Show Clear Button toggle is set to (OFF).
Hide Chevron
When set to (ON), the arrow (chevron) to the right of the component is hidden.
By default, Hide Chevron is set to (OFF).
Set Dropdown Menu Height
Sets the number of search result rows the component displays when filtered by an end-user. If there are more options than the number entered, your end-user can scroll to view them all. Or, they can enter a value to navigate to relevant results.
Item Template
Lets you choose which column of data you want to display as the label for the drop-down options. Replace the word label with your chosen attribute in the following string format: <span>{{ item.label }}</span>.
Data Panel
Data Source Types
There are three methods you can use to populate a Multi-Select Dropdown component: Values, URL, and Data Reference Key.
Values
Selecting Values displays a table where you can enter each option and its value.
Setting
Description
Option Label
Each option needs an end-user-facing label describing the choice that it represents. Enter your Option Labels using this column.
After you create an option, another row displays for you to create the next option.
To use data not stored in a specific component, select URL. Generally, this data lives in two places:
External to Unqork and pulled into the component using an external API call.
Internally and stored as a Data Collection.
To use an external API call, reference the provider's documentation. You'll find the API's URL address and the information you need to filter the data. To learn more, see our Using an External API in a Dropdown Component article.
To reference Data Collections in Unqork, use the Data Collections tab at the Application Level. Click Create Data Collection to create a new Data Collection. Or, explore the available Data Collections and use one of them.
Enter the information to display in the drop-down selections. These are your end-user's options. For external APIs, you'll find this information in the API documentation. To pull data from a Data Collection, enter the column header you want to use.
Select an external service configured through Unqork's Services Administration. This auto-populates the other required fields, including the Data Source URL.
Data Source URL
For an API to retrieve data, you need the API's URL information. In this field, enter the API information as obtained from the API documentation. Add additional filters at the end of the URL if you want to drill down to a specific type of data.
Value Property
If a data set includes a column for values, enter the column's name here.
If not specified, the application uses the option label.
Data Path
If using an API call to populate the component, enter a specific data property to reference here. This is useful if you want to show one piece of a larger data set in your Multi-Select Dropdown component.
Label Path
This field refers to the option labels you want to pull. Enter the option label's column header in this field.
Filter Query
Provide additional filtering using query parameters. Parameters append to the end of the Data Source URL. Query parameters can be static or dynamic. For example, name={{data.groupName}}.
Search Query Name
The name of the search query string parameter used when sending a request to filter results. The server at the specified URL must support this query parameter.
Refresh On
This field displays a list of the other components in your module. You can select a component here to refresh your Multi-Select Dropdown. When your end-user interacts with the selected component, the Multi-Select Dropdown resets.
You can also select Any Change. This refreshes the Multi-Select Dropdown if your end-user interacts with any of your components.
This setting watches other components in your module. The more components the component watches, the more performance issues can occur. It’s also important to note that processes large amounts of data on the client side will also impact performance.
Refresh Delay
Works with the Refresh On setting to set the number of milliseconds that pass before refresh. Once typing has finished, the delay begins.
The component has a minimum Refresh Delay of 250 ms, which is the default for this field.
Limit Number of Items
Limits the number of matching responses when working with large data sets. For example, an API might return more responses than you want to display, even when your end-user starts typing. Here, you can set a limit on how many results display.
Disable Limiting Response
When set to (ON), the request won't include the limit and skip options in the query string.
By default, this setting is (OFF).
Search Parameters are Required
When set to (ON), search parameters must be present to execute the search.
By default, this setting is (OFF).
Clear Value on Refresh
When set to (ON), the selected value is cleared after the Refresh On setting triggers.
By default, this setting is (OFF).
Authenticate
When set to (ON), authentication headers from the application are sent to the Data Source URL destination.
By default, this setting is (OFF).
Disable Filter Application
When set to (ON), filter parameters are not applied.
By default, this setting is (OFF).
Data Reference Key
Using the Data Reference Key option, data from another component populates the Multi-Select Dropdown component. You'll most often do this with a Data Table component. Add your data to the Data Table component. Then, reference it in your Multi-Select Dropdown component's configuration menu.
Think of this as a hybrid option of Values and Data Collections to populate your Multi-Select Dropdown component. You still use data stored in Unqork, but it's data from your module instead of a Data Collection.
Limits the number of matching responses when working with large data sets. For example, an API might return more responses than you want to show. Here, you can set a limit on how many results display.
Refresh On
This field displays a list of the other components in your module. You can select a component here to cause your Dropdown to refresh. When your end-user interacts with the selected component, the Dropdown resets.
Here, you can also select Any Change. This refreshes the Dropdown if your end-user interacts with any of your components.
This setting watches other components in your module. The more components the component watches, the more performance issues can occur. It’s also important to note that processes large amounts of data on the client side will also impact performance.
Data Storage
Setting
Description
Store Data in Database
The Store Data in Database setting affects how data persists through your application. When set to (ON), Unqork stores values entered into the field to the database (server-side submission). This occurs in three scenarios:
Navigating between Panels in a Navigation component. On navigation between pages (Panels), the component’s value saves to the database.
Triggering a module save event using a Button component with an Action Type of Save.
Navigating between screens of a workflow. On navigation between screens, the component’s value saves to the database.
By default, workflows persist data from all fields in the client-side submission when navigating between screens. However, only values from fields with Store Data in Database enabled store in the server-side submission.
Set the toggle to (OFF) when you don’t want to store the values from this field in the database.
When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response.
Store Data in Database also affects what data is tracked using Unqork’s built-in tracker. When the Enable Tracker and Track Value toggles are set to (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.
When set to (ON), the end-user must enter a value in the component's visible fields. When set to (OFF), the input is optional.
By default, Required is set to (OFF).
Required Error Message
A custom error message that displays below a required field. The error message displays when the end-user tries to save or submit the module without completing the required field.
Advanced Panel
Additional Validation Options
Setting
Description
Require Unique Submission Data
When set to (ON), the data submitted for this field must be unique and not submitted before.
By default, the Require Unique Submission Data toggle is set to (OFF).
Don't Allow Unique Values
When set to (OFF), your end-user can enter a custom value in the Dropdown field. This custom value saves and stores, even if the input doesn’t match existing values in the Dropdown. When set to (ON), your end-user can only select an existing value from the Dropdown.
By default, the Don't Allow Unique Values toggle is set to (OFF).
Updated CSS styling applies to all components that reference this custom class name.
Adding a Multi-Select Dropdown Component
Let's configure a Multi-Select Dropdown component referencing a Data Table component. Use the Multi-Select Dropdown to ask your end-user which vehicles they own.
Configure the Data Table Component
This Data Table component supplies the vehicle labels and values for your end-user to select from a drop-down menu in Express View.
These instructions assume that you have an open module saved with a title.
1.
In the Module Builder, drag and drop a Data Table component onto your canvas.
Structure of a Multi-Select Dropdown Component's Data
The Multi-Select Dropdown component's data stores in a key/value format. In the above example, the vehicles Multi-Select Dropdown component stores the tractor value from the dtVehicles Data Table component.
(
Data Collections
Multi-Select Dropdown component onto your canvas.
(ON), the request won't include the limit and skip options in the query string.
(OFF).
Data Table
