--- category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend] keyword: [Extend, Presentation Components, widgets, tags, UI components] nav: wcp_docs parent_url: /wcp_docs/ title: dropdown layout: subsection wd_wcptag: dropdown --- Creates a prompt that enables users to select an option from a list of options. Use `dropdown` on edit pages when you want the user to select a single option from a dropdown list. You can also use the `dropdown` tag with the `dropdownEditButton`. The `dropdown` widget value is a list of strings. ## Populating the Dropdown List To define the values in the `dropdown` list, use 1 of these mutually exclusive attributes: - values Specify `values` with endpoint data, which must be a list containing the `id` and `descriptor` fields. Using the `values` attribute is the most common way to populate a list. This sample `dropdown` displays the `descriptor` values from the `supervisoryOrganizations` endpoint: ``` { "type": "dropdown", "label": "dropdown using default descriptors", "id": "instanceListSimple", "values": "<% supervisoryOrganizations.data %>" } ``` The sample `supervisoryOrganizations` endpoint: ``` { "baseUrlType": "workday-staffing", "name": "supervisoryOrganizations", "authType": "sso", "url": "/supervisoryOrganizations" } ``` This snippet from the `supervisoryOrganizations` response displays the `data` list containing the `id` and `descriptor` root-level fields: ``` "data":[ { "id":"e02485f863ec48d39a082bb95cc4abe4", "descriptor":"4000 Human Resources", "name":"Human Resources", . . . }, . . . ] ``` To override the default `id` and `descriptor` fields, set the `idKey` and `displayKey` attributes. Example: If you want to display the `name` instead of the `descriptor` field in the `supervisoryOrganizations` data, set the `displayKey` attribute: ``` { "type": "dropdown", "label": "dropdown using displayKey", "id": "supervisoryOrgsDropdown", "displayKey": "name", "values": "<% supervisoryOrganizations.data %>" } ``` When you set `displayKey` to name, the `instanceList` displays Human Resources instead of 4000 Human Resources. To display values from a subfield in the list or to manipulate the shape of the list values, you can use PMD Scripting. Example: This sample `dropdown` displays the `email` values from the `person` subfield. For demonstration purposes, this snippet assumes non-empty email values. ``` { "type": "dropdown", "id": "emailDropdownList", "label" : "dropdown using script", "values": "<% workers.data .filter (worker => { !empty worker.person.email }) .map (worker => { { 'id': worker.person.id, 'descriptor': worker.person.email } }); %>" }, ``` This snippet from the `workers` response displays the `data` list containing the `person` subfield: ``` "data": [ { "descriptor": "Abby Brennan [C]", "id": "6dcb8106e8b74b5aabb1fc3ab8ef2b92", "person": { "email": "abrennan@workday.net", "id": "dc4945b8b8be429e87564e01889c69f5", "phone": "+1773721-9821" }, . . . }, . . . ] ``` - instanceList Specify the `instanceList` attribute with a list of hard-coded `id` and `descriptor` fields. Example: ``` { "type": "dropdown", "selectedValues": "<% ['Special Leave'] %>", "label": "What type of leave are you applying for?", "id": "dropdownList", "instanceList": [ { "id": "Special Leave", "descriptor": "Special Leave" }, { "id": "Special Leave - Domestic", "descriptor": "Special Leave - Domestic" } ], "required": "true" } ``` If you have a short list of hard-coded options, you can alternatively use the other list widgets such as the `checkBoxList` or `radioGroup`. ## Mobile Support Android, iOS ## Attributes - cacheValues Data type: boolean Indicates whether or not to cache values for sharing among users. - displayKey Data type: string The name of the field containing the display value on the list. The default is `descriptor`, which assumes that the data collection contains a field named `descriptor`. Typically used with the `idKey` attribute to override the default `id` field on the list. Supports JSONPath notation. If your data collection doesn't contain the `descriptor` field, use `displayKey` to override the default. Specify a root-level field. If you want to use a nested field, use JSONPath notation. - enabled Data type: dynamicBinding-Boolean If true, users can enter values on the widget. If false, users can only view the widget. - guide Data type: `guide` Displays a ? widget that opens a popup window containing guidance information about a widget on an edit page. For details, see the `guide` tag. - helpText Data type: binding-String Text that displays when a user hovers their cursor over the widget. Note: The Chrome browser truncates the tooltip to 1400 characters. - id Data type: binding-String Unique identifier used to reference this widget from other tags. Notes: - The `id` must start with a letter. - The `id` must be unique per page. - To enable other widgets to reference this widget `id`, place this widget before the other widgets on the PMD. The PMD validation returns an "Undefined variable" error if it doesn't find a previously defined `id` in the PMD. - Workday recommends that you include the `id` in your tag definitions for debugging purposes. - idKey Data type: string The name of the ID field, which is the index field on the list. The default is `id`, which assumes that the data collection contains a field named `id`. Typically used with the `displayKey` attribute to override the default `descriptor` field on the list. Supports JSONPath notation. If your data collection doesn't contain the `id` field, use `idKey` to override the default. Specify a root-level field. If you want to use a nested field, use JSONPath notation. - instanceList Data type: list of instance objects An array of `id` and `descriptor` values in the list. Example: ``` "instanceList": [ { "id": "1", "descriptor": "Yes" }, { "id": "2", "descriptor": "No" } ] ``` Notes: - You can't combine `instanceList` with the `instanceListLoopTag` or `values` attributes to populate a list. These attributes are mutually exclusive. - To enable the related actions menu and view link, set the `wid` attribute. Specify the binding to the ID field containing the instance Workday ID. For details, see Enabling the Related Actions Menu in [instanceList](/wcp_docs/hcb1512514976081.html). - instanceListLoopTag Data type: instanceLoop Note: Workday recommends using PMD scripting with the `values` attribute to reshape data instead of the `instanceListLoopTag` attribute. Creates list values by using a template instance while iterating through a data collection. The `instanceListLoopTag` attribute is an [instanceLoop](/wcp_docs/fem1530169946255.html) tag that specifies the: - `templateInstance` - Contains the template `id` and `descriptor` fields for a list item. You can specify root-level or nested fields. - `on` - The binding to the data collection. - `as` - The variable reference for each instance. - `limit` - Optional maximum number of list items. Example: ``` "instanceListLoopTag": { "type": "instanceLoop", "id": "sampleInstanceListLoopTag", "templateInstance": { "id": "<% workerInstance.primarySupervisoryOrganization.id %>", "descriptor": "<% workerInstance.primarySupervisoryOrganization.descriptor %>" }, "on": "<% workers.data %>", "as": "workerInstance", "limit": 5 } ``` Note: You can't combine `instanceListLoopTag` with the `instanceList` or `values` attributes to populate a list. These attributes are mutually exclusive. - label Data type: dynamicBinding-String Text that displays beside or above most widgets. Often used in simple widgets that include inputs. The maximum number of characters is 255. - render Data type: binding-Boolean If true, this tag renders as a widget on the page. If false, the loaded page doesn't add this tag or its children. The default is true. Unlike the `visible` attribute, when `render` is false, other tags on the page can't reference this tag or widget on edit pages. On view pages, a tag can't reference other tags regardless of the `render` attribute value. - required Data type: dynamicBinding-Boolean If true, the user must enter a value on the widget before submitting the page. - selectedValues Data type: dynamicBinding-List The first ID in the list specifies the selected item on the widget. The specified ID must be included in the list of values. - sortOrder Data type: binding-String When you set `sorted` to true on the `section` or `fieldSet` parent of this widget, the `sortOrder` attribute determines the order of this widget within its parent. The sort order is relative to the siblings of the widget. Typical values are "a", "b", "c", and so on. Example: The widget with `"sortOrder": "a"` displays before the widget with `"sortOrder": "b"`. Note: The `sortOrder` doesn't apply to sorting data on the widget. `sortOrder` only applies to the placement order of the widgets within the parent widget. - valueOutBinding Data type: dynamicBinding-String A binding to the JSON field that stores the widget value in the outbound request payload. Example: ``` { "type":"textArea", "id":"memo", "label":"Memo", "value":"<% queryParams.memo %>", "valueOutBinding": "expensesPostEndpoint.memo" } ``` When the user submits the edit page, we send the request payload containing field values as specified in `valueOutBinding`. This sample JSON request payload contains the memo field sent to the sample `expensesPostEndpoint`: ``` {"memo": "Sample value from the memo widget."} ``` If you want to send an array of JSON values to the outbound endpoint, specify the path using this pattern: `anEndpointName.[].aJsonFieldName`. Example: To send this array to the sample outbound endpoint: ``` [{"memo":"First memo"}, {"memo":"Second memo"}] ``` Specify this `valueOutBinding`: ``` "valueOutBinding" : "expensesPostEndpoint.[].memo" ``` Note: If the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the widget's `valueOutBinding` data in the outbound payload. To include the `valueOutBinding` data in the payload, use the `onSend` event handler. - values Data type: dynamicBinding-List Defines all possible values that a user can select from a list. Each value defaults to an id and descriptor for persistence and display. You can customize these values on the idKey and displayKey attributes. Note: You can't combine `values` with the `instanceList` or `instanceListLoopTag` attributes to populate a list. These attributes are mutually exclusive. - valuesOut Data type: list of outValue objects An array of values and their bindings to JSON fields in the outbound request payload. An array item consists of these attributes: - `value` - An object binding of the value to include in the outbound JSON. - `valueOutBinding` - A string binding of the JSON field that contains the value in the request payload. We send the request payload with the outbound endpoint when the user submits the page. You can use `valuesOut[]` to: - Send a single piece of data to multiple outbound fields or endpoints. Example: A street address persisting to a Billing Address field and a Shipping Address field or different endpoints. - Apply a function to the outbound value when persisting the data. Example: Convert a date to a specific format or convert a list to a string. In this example, the value of the `country` widget is sent to 2 different outbound fields `shippingAddress.country` and `billingAddress.country`. ``` "valuesOut": [ { "value": "<% country.value[0] %>", "valueOutBinding": "anOutboundEndpoint.shippingAddress.country.id" }, { "value": "<% country.value[0] %>", "valueOutBinding": "anOutboundEndpoint.billingAddress.country.id" } ] ``` This example uses PMD functions to extract the year and month from date values, and sends them separately to the outbound endpoint: ``` "valuesOut": [ { "value": "<% date:month(date1.value) %>", "valueOutBinding": "anOutboundEndpoint.dateMonth" }, { "value": "<% string:toString(date:year(panelList1Date1.value)) %>", "valueOutBinding": "anOutboundEndpoint.dateYear" } ] ``` Note: If the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the widget's `valuesOut` data in the outbound payload. To include the `valuesOut` data in the payload, use the `onSend` event handler. - visible Data type: dynamicBinding-Boolean If true, the widget generated by this tag is visible. If false, this tag and its children tags aren't visible. This tag provides the ability to display or hide the widget dynamically based on user interactions on the page. The default is true. Unlike the `render` attribute, the generated widget persists on the page even when `visible` is false. Notes: - When the widget or field you’re hiding changes on the page, you must include it inside a `fieldSet`. - When the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the `valueOutBinding` or `valuesOut` data of the widget in the payload. To include the `valueOutBinding` or `valuesOut` data in the payload, use the `onSend` event handler. ## PMD Scripting Methods - clearError() Return type: `void` Description: Clears the validation error. - clearWarning() Return type: `void` Description: Clears the validation warning. - getLabel() Return type: `string` Description: Returns the list label. - getPromptSelections(int index) Return type: `List` Returns a list containing the `id` of the selected values of a multilevel `instanceList`. Example: `promptSelections[0]` contains the `id` of the selected value at the root level. `promptSelections[1]` contains the `id` of the selected value at the second level, and so on. Note: The `getPromptSelections(index)` method (or its equivalent `promptSelections` property) applies only to a multilevel `instanceList` that contains `monikerLevels`. You can use promptSelections as a URL path parameter of a deferred endpoint that returns the sublevel values. See "Defining a Multilevel List" in [instanceList](/wcp_docs/hcb1512514976081.html). - getSelectedEntries() Return type: `List` Description: Returns a list of maps containing the `id` and `descriptor` fields for the selected entries on the instance list. Example: `[{"id": "123", "descriptor": "Logan McNeil"}]` If the list doesn't have a selected value, the `getSelectedEntries` method (or its equivalent `selectedEntries` property) returns an empty list, `[]`. When you get the `descriptor` value of the selected entry, always check whether or not the list value is empty. Example: ``` <% !empty someList.value ? someList.selectedEntries[0].descriptor : null %> ``` - getValue() Return type: `List` Description: Returns this instance list as a list of instance ids. Example: `["123", "456"]` If the list is empty, the `getValue` method (or its equivalent `value` property) returns an empty list, `[]`. - getValueOutBinding() Return type: `string` Description: Returns the outbound value binding of this instance list. - isEnabled() Return type: `boolean` Description: If true, this widget is enabled. - isRequired() Return type: `boolean` Description: If true, this widget is required. - isUpdated() Return type: `boolean` Description: If true, this widget is manually updated by the end-user. - isUpdatedByScript() Return type: `boolean` Description: If true, this widget is programmatically updated by a PMD script. - isVisible() Return type: `boolean` Description: If true, this widget is visible. - setEnabled(boolean enabled) Return type: `void` Description: Enables or disables this widget. - setError(String error) Return type: `void` Description: Sets the validation error. The input error message displays in the page error window. - setLabel(String label) Return type: `void` Description: Sets the list label. - setRequired(boolean required) Return type: `void` Description: Makes this widget required or not required. - setValue(List value) Return type: `void` Description: Sets this instance list to the specified list of instance `id` values. You can use `someList.setValue(['id1', 'id2'])` to set the `selectedValues` property of an `instanceList`. - setValueOutBinding(String valueOutBinding) Return type: `void` Description: Sets the outbound value binding to this instance list. - setValues(List dataSource) Return type: `void` Description: Sets all possible values of this instance list. The dataSource list must include the `id` and `descriptor` fields (or the fields specified by the `idKey` and `displayKey` attributes). - setVisible(boolean visible) Return type: `void` Description: Displays or hides this widget. If you need to change the visibility of a list widget, ensure that it's inside a `fieldSet`. - setWarning(String warning) Return type: `void` Description: Sets the validation warning. ## PMD Scripting Events - onChange Triggers when the user changes the value of the widget.