By default, the Dropdown component stays collapsed until the end-user clicks to open it. After making a selection, the Dropdown list closes again. Your end-user has the option to type the first few letters of their response to quickly find that option in the list.
In this article, you'll learn about the Dropdown component, how to configure its settings, and how to use it in an application.
About the Configuration Window
TIP 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
Setting
Description
Label Text
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.
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.
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.
Hide Label
Setting the Hide Label toggle to (ON) stops Label Text from displaying in Express View. Your Label Text still displays in the Module Builder.
By default, the Hide Label toggle is set to (OFF).
Read Only View
When set to (ON), the component is display-only. If another component pushes content to the field, the end-user sees 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 can’t 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, the Disable User Input toggle is set to (OFF).
Hide Field
Shows or hides the component from view. Setting the Hide Field toggle to (ON) hides the component in Express View. Setting the toggle to (OFF) shows the component. The component is always visible in the Module Builder.
By default, the Hide Field toggle is set to (OFF).
Data Panel
Data Source Type
There are three methods that you can use to populate a Dropdown component: Values, URL, and Data Reference Key.
Values
Selecting Values displays a table where you can enter each option and its value.
To use data that are not stored in a specific component, select URL. Generally, this data lives in two places:
External to Unqork and stored in the component using an external API call.
Internally and stored as a data collection.
NOTE To use an external API call, reference the provider's documentation. There, 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, look through the available data collections and use one of those.
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.
For an API to bring in 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 itself.
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 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}}.
Refresh On
This field displays a list of the other components in your module. You can select a component here to refresh your Dropdown. When your end-user interacts with the selected component, the Dropdown resets.
You can also select Any Change. This refreshes the Dropdown if your end-user interacts with any of your components.
Require Search Parameters
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).
Data Reference Key
Using the Data Reference Key option, data from another component populates the Dropdown component. You'll most often do this with a Data Table component. Add your data to the Data Table. Then, reference the Data Table in your Dropdown's configuration window.
Think of this as a hybrid option of using Values and Data Collections to populate your Dropdown. You still use data stored in Unqork, but it's data from your module instead of a Data Collection.
Setting
Description
Data Reference Key
Enter the Property ID of the component whose data you're referencing.
Value Property
If a data set includes a column for values, enter the column's name here.
If not specified, the application uses the data drawn using the Label Path setting below.
Label Path
This field refers to the option labels to retrieve. If you're retrieving data from a Data Table component, enter the column header in this field.
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.
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.
NOTE 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.
NOTE 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. To learn more about Store Data in Database in the context of API modules, see the panelResponse Panel section of the API Specification Snippet article in our In-Product Help.
TIP 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.
Actions Panel
Triggers
Setting
Description
Trigger
To set up a trigger, enter the Property ID of your chosen logic component into this field. When the end-user performs an action on the current component, the triggered component fires.
Validation Panel
User Input
Setting
Description
Required
When set to (ON), the end user must enter a value in the component's visible fields. Set the toggle to (OFF) when an entry is optional.
By default, the Required toggle 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.
Updated CSS styling applies to all components that reference this custom class name.
Adding a Dropdown Component
Now, configure a Dropdown component asking about an end-user's education history. The Dropdown includes six options for selection. These instructions assume that you have an open module saved with a title.
1.
Drag and drop a Dropdown component onto the canvas.
The data structure of a Dropdown's selection is a key value pair. The key is the Property ID name of the component, and the value is stored as a string.
By default, the Dropdown component stays collapsed until the end-user clicks to open it. After making a selection, the Dropdown list closes again. Your end-user has the option to type the first few letters of their response to quickly find that option in the list.
In this article, you'll learn about the Dropdown component, how to configure its settings, and how to use it in an application.
About the Configuration Window
Display Panel
Field Text
Setting
Description
Label Text
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
Hide Label
Setting the Hide Label toggle to (ON) stops Label Text from displaying in Express View. Your Label Text still displays in the Module Builder.
By default, the Hide Label toggle is set to (OFF).
Disable User Input
When set to (ON), end-users can’t 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, the Disable User Input toggle is set to (OFF).
Read Only View
When set to (ON), the component is display-only. If another component pushes content to the field, the end-user sees that content. Otherwise, end-users see the word None.
By default, the Read Only View toggle is set to (OFF).
Hide Field
Shows or hides the component from view. Setting the Hide Field toggle to (ON) hides the component in Express View. Setting the toggle to (OFF) shows the component. The component is always visible in the Module Builder.
By default, the Hide Field toggle is set to (OFF).
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.
NOTE 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.
NOTE 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. To learn more about Store Data in Database in the context of API modules, see the panelResponse Panel section of the API Specification Snippet article in our In-Product Help.
TIP 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 Type
There are three methods that you can use to populate a Dropdown component: Values, URL, and Data Reference Key.
Values
Selecting Values displays a table where you can enter each option and its value.
To use data that are 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.
NOTE To use an external API call, reference the provider's documentation. There, 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, look through the available data collections and use one of those.
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.
For an API to bring in 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.
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 Dropdown component.
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}}.
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 itself.
Label Path
This field refers to the option labels you want to pull. Enter the option label's column header in this field.
Refresh On
This field displays a list of the other components in your module. You can select a component here to refresh your Dropdown. When your end-user interacts with the selected component, the Dropdown resets.
You can also select Any Change. This refreshes the Dropdown if your end-user interacts with any of your components.
Require Search Parameters
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).
Data Reference Key
Using the Data Reference Key option, data from another component populates the Dropdown component. You'll most often do this with a Data Table component. Add your data to the Data Table. Then, reference the Data Table in your Dropdown's configuration window.
Think of this as a hybrid option of using Values and Data Collections to populate your Dropdown. You still use data stored in Unqork, but it's data from your module instead of a Data Collection.
Setting
Description
Data Reference Key
Enter the Property ID of the component whose data you're referencing.
Value Property
If a data set includes a column for values, enter the column's name here.
If not specified, the application uses the data drawn using the Label Path setting below.
Label Path
This field refers to the option labels to retrieve. If you're retrieving data from a Data Table component, enter the column header in this field.
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.
Actions Panel
Triggers
Setting
Description
Trigger
To set up a trigger, enter the Property ID of your chosen logic component into this field. When the end-user performs an action on the current component, the triggered component fires.
Validation Panel
Input Required
Setting
Description
Required
When set to (ON), the end user must enter a value in the component's visible fields. Set the toggle to (OFF) when an entry is optional.
By default, the Required toggle 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.
Updated CSS styling applies to all components that reference this custom class name.
Adding a Dropdown Component
Now, configure a Dropdown component asking about an end-user's education history. The Dropdown includes six options for selection. These instructions assume that you have an open module saved with a title.
1.
Drag and drop a Dropdown component onto the canvas.
The data structure of a Dropdown's selection is a key value pair. The key is the Property ID name of the component, and the value is stored as a string.
(
Data Collections
(OFF).
Dropdown component onto the canvas.
Data.
Validation.
(ON).
