Dropdown Component

Function

a!dropdownField( label, labelPosition, instructions, required, disabled, choiceLabels, choiceValues, placeholder, value, validations, saveInto, validationGroup, requiredMessage, helpTooltip, accessibilityText, showWhen, searchDisplay, data, sort, marginAbove, marginBelow )

Displays a list of choices for the user to select one item and saves a value based on the selected choice.

Parameters

Usage considerations

When to use a dropdown

There are multiple selection components you can use to display options in an interface. As a best practice, you should use a dropdown component when there are only a small set of options.

If there aren't many options and users would benefit from easily seeing them all at once, consider using radio buttons.

If there are a large set of options, consider using a picker component. The picker search runs server-side and the performance cost of loading options happens while the user is searching. This may lead to better performance than a dropdown if you have a large set of options.

If the user may select none, one, or many of the options, use either the checkbox component or a multiple dropdown component.

Using the choiceLabels and choiceValues parameters

When configuring the Choice Labels and Choice Values parameters, keep the following in mind:

• The Choice Labels cannot be null.
• The Choice Values cannot contain nulls or duplicate values.
• The Choice Labels list and Choice Values list must be the same length.

When you select Record Type as the data source, the Choice Labels and Choice Values are automatically populated with record field references. By default, the labels will be the first text field from the record type, and the values will be the primary key field.

You can format and display multiple record fields in the Choice Labels parameter using fv!data and a record field reference. For example, if you want to display a list of US cities with their states in parentheses, you could use the following expression:

1
choiceLabels: fv!data[recordType!Location.fields.city] & " (" & fv!data[recordType!Location.fields.state] & ")"

This would display choice labels as:

1
2
3
4
5
New York City (New York)
Los Angeles (California)
Chicago (Illinois)
Houston (Texas)
Phoenix (Arizona)

Handling duplicate values in records-powered components

In a records-powered dropdown component, the fields used in the choiceValue and choiceLabels parameters determine how duplicate values are handled.

Automatically remove duplicate values

When you use the same record field for the choiceValue and choiceLabels parameters, any duplicate field values are automatically removed from the list of options.

For example, let’s say you use an Employee record type as the source of a dropdown component. The record type has a department field with the following values:

• Sales
• Engineering
• Sales
• Marketing
• Engineering

If you set both choiceValue and choiceLabels to the department field, the dropdown component will automatically filter this list to show only the unique values:

• Engineering
• Marketing
• Sales

Display all values, including duplicates

To display all values in the component, including duplicate values, you must provide a unique choice value for each choice label.

For example, let’s say you use an Employee record type as the source of a dropdown component and there are two employees named “Olivia Smith.”

To show two different employees both named "Olivia Smith," you would configure the parameters as:

• choiceValue: recordType!Employee.fields.id (This provides a unique value for each employee)
• choiceLabels: recordType!Employee.fields.displayName (This displays the employee's name)

Because each "Olivia Smith" has a unique ID in the choiceValue, the dropdown component will list both of them as distinct selectable options.

Sort choices

The way you sort the choices depends on the source of the component. If no sort is applied, the labels will appear in the order they're provided.

When you select Record Type as the data source:

• The choice order is determined by the Sort parameter.

• You can automatically sort by the values configured in the Choice Labels or Choice Values parameters by using "choiceLabels" or "choiceValues" in the a!sortInfo() function.

  For example, a!sortInfo(field: “choiceLabels”, ascending: true) would automatically sort the choices by the values in the Choice Labels parameter.

When you select Other as the data source:

• The choices display in the order defined in the Choice Labels.

Using the placeholder parameter

To allow users on web to clear the selected value, text must be specified for the placeholder parameter. Users can always clear the value on the Appian for Mobile application.

Passing a null value to the dropdown's Selected Value parameter causes the placeholder text to appear selected. The Placeholder and Selected Value parameter cannot both be null.

Row limit for records-powered components

Interface components that use a record type as the data source are known as records-powered components.

Records-powered components can display a maximum of 5,000 rows. As a best practice, you should not display all 5,000 rows in a component since it may impact performance.

Query timeout for records-powered components

Queries to synced and unsynced record types will timeout after 65 seconds. If you are querying large volumes of data, this may cause the interface or expression to error.

To resolve timeout errors, reduce the amount of data in your query by:

• Reducing the batch size.
• Limiting the number of fields returned.
• Applying more specific filters.

Some complex queries may result in reduced performance. Ensure you're following query best practices.

Examples

Record type object references are specific to each environment. If you copy and paste the example with record field references into your interface, it will not evaluate. Use that example as a reference only.

Dropdown with choices from a record type

In this example, the component's choices are retrieved from a reference record type that contains the full names and abbreviations of US states.

The choiceLabels parameter references the name field and the name_short field to display the name of each state and the state's abbreviation in parentheses. The choiceValues are set using the record type's primary key field, id.

1
2
3
4
5
6
7
8
9
10
11
12
a!dropdownField(
  data: recordType!AT State,
  choiceLabels: fv!data[recordType!AT State.fields.name] & " (" & fv!data[recordType!AT State.fields.name_short] & ")",
  choiceValues: recordType!AT State.fields.id,
  label: "State",
  placeholder: "Select a State",
  value: ri!customer[recordType!AT Customer.relationships.address.fields.stateId],
  saveInto: ri!customer[recordType!AT Customer.relationships.address.fields.stateId],
  sort: a!sortInfo(
    field: "choiceLabels",
    ascending: true)
)

Dropdown with the first choice selected by default and search on auto

Since the searchDisplay parameter is set to AUTO and the number of choiceValues is less than 12, no search box will be displayed.

Use the interactive editor below to test out the example code.

Since the searchDisplay parameter is set to AUTO and the number of choiceValues is more than 11, a search box will be displayed.

Use the interactive editor below to test out the example code.

Dropdown with no choice selected by default and search on

Since the searchDisplay parameter is set to ON, even though the number of choiceValues is less than 12, a search box will be displayed.

Use the interactive editor below to test out the example code.

Feature compatibility

Old versions

There are older versions of this interface component. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Related recipes

The following recipes include usage of the Dropdown Component.

• Add Validations to an Inline Editable Grid (Validation, Grids, Looping):

  Allows the user to change data directly in a grid, and validate a various entries.

• Add, Edit, and Remove Data in an Inline Editable Grid (Grids, Looping):

  Allow the user to change data directly in an inline editable grid.

• Conditionally Hide a Column in a Grid (Grids, Conditional Display):

  Conditionally hide a column in a read-only grid when all data for that column is a specific value.

• Configure Buttons with Conditional Requiredness (Validation):

  Present two buttons to the end user and only make certain fields required if the user clicks a particular button

• Configure Cascading Dropdowns (Conditional Display, Choice Components):

  Show different dropdown options depending on the user selection.

• Configure a Dropdown Field to Save a CDT (Choice Components):

  When using a dropdown to select values from the database, or generally from an array of CDT values, configure it to save the entire CDT value rather than just a single field.

• Configure a Dropdown with an Extra Option for Other (Choice Components):

  Show a dropdown that has an "Other" option at the end of the list of choices. If the user selects "Other", show a required text field.

• Configure an Array Picker with a Show All Option (Pickers):

  Allow users to choose from a long text array using an autocompleting picker, but also allow them to see the entire choice set using a dropdown.

• Display Multiple Files in a Grid (Document Management, Grids):

  Show a dynamic number of files in a grid and edit certain file attributes.

• Dynamically Show Sales by Product Category Compared to Total Sales (Records, Reports, Charts, Filtering):

  This pattern illustrates how to create an area chart that dynamically displays sales generated by product category compared to total sales.

• Filter a Grid Using a Dropdown (Grids, Filtering, Records):

  Configure a dropdown for users to filter data in a read-only grid.

• Save a User's Report Filters to a Data Store Entity (Grids, Smart Services, Filtering, Reports):

  Allow a user to save their preferred filter on a report and automatically load it when they revisit the report later.

• Searching on Multiple Columns (Grids, Filtering, Reports):

  Display a grid populated based on search criteria specified by end users.

• Track Adds and Deletes in Inline Editable Grid (Grids):

  In an inline editable grid, track the employees that are added for further processing in the next process steps.

• Update an Entity-Backed Record Type from its Summary View (Records, Smart Services):

  Enable users to make quick changes to a record by updating it right from a record view.

• Upload Multiple Documents in an Editable Grid (Document Management, Records):

  Build a form that allows users to create a record and upload related documents in an editable grid.

• Use Links in a Grid to Show More Details and Edit Data (Grids):

  Allow end users to click a link in a read-only grid to view the details for the row, and make changes to the data. The data available for editing may include more fields than are displayed in the grid.

• Use Selection For Bulk Actions in an Inline Editable Grid (Grids):

  Allow the user to edit data inline in a grid one field at a time, or in bulk using selection.

• Use Validation Groups for Buttons with Multiple Validation Rules (Validation):

  Present two buttons to the end user that, based on the selection, will validate only after a particular button is clicked.

• Use a Filter to Adjust Chart Reference Lines (Filtering, Charts):

  Using a dropdown, filter the results of a data set while also adjusting a chart reference line.

• Year-Over-Year Report (Charts, Reports, Formatting):

  This is a feature-rich, interactive report for sales and profits by products over select periods of time.

Feedback