# object-dropdown

## Overview

{% hint style="info" %}
**Version compatibility**

* `object-dropdown` is supported in all versions of the JourneyApps Container and Runtime.
* It received several functional updates in version **4.84.0** of the JourneyApps Runtime, including the ability to [bind](#bind) to an array, which allows a user to select multiple options.
  {% endhint %}

The `object-dropdown` UI component lists objects from a [database query](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects) or [array](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects#arrays) for selection by the user. Once an object, or multiple objects (since runtime version 4.84.0) are selected, they can be stored as a field, or used to further your app's workflow.

### Basic Example

#### Binding a single object

{% code title="main.view\.xml" %}

```xml
<var name="countries" type="query:country" />
<!-- OR -->
<var name="countries" type="array:country" />

<var name="selected_country" type="country" />

<object-dropdown label="Country of residence" query="countries" bind="selected_country" required="false" />
```

{% endcode %}

{% code title="main.js" %}

```javascript
function init() {
     view.countries = DB.country.all();
     // OR
     view.countries = DB.country.all().toArray();
}
```

{% endcode %}

#### Binding multiple objects

{% code title="main.view\.xml" %}

```xml
<var name="countries" type="query:country" />
<!-- OR -->
<var name="countries" type="array:country" />

<var name="selected_countries" type="array:country" />

<object-dropdown label="Country of residence" query="countries" bind="selected_countries" required="false" />
```

{% endcode %}

{% code title="main.js" %}

```javascript
function init() {
     view.countries = DB.country.all();
     // OR
     view.countries = DB.country.all().toArray();
}
```

{% endcode %}

A selected option in the `object-dropdown` component:

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-0130fd892496347b341abc6a20324785c8441054%2Fobject-dropdown-example-closed.png?alt=media)

List of options in the `object-dropdown` component:

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-3cb62b9cfc139afc01cbc036c535c87c72b927da%2Fobject-dropdown-example-open.png?alt=media)

{% hint style="info" %}
**Note**

By default, when 12 or more options are listed in an `object-dropdown` a search box appears at the top of the list of options. It can be used to more efficiently find an option. See the [search-controls reference](#search-controls) for more information.
{% endhint %}

## Standard Attributes

### `bind`

{% content-ref url="../xml-fields/bind" %}
[bind](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/bind)
{% endcontent-ref %}

**Example - bind to a single object:**

{% code title="main.view\.xml" %}

```xml
 <var name="countries" type="query:country" />
 <var name="selected_country" type="country" />

 <object-dropdown label="Country of residence" placeholder="Select a country" query="countries" bind="selected_country" required="false" />
```

{% endcode %}

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FHquo2L5dZpn6ZUfeK83y%2FScreen%20Shot%202022-09-01%20at%203.14.55%20PM.png?alt=media&#x26;token=51b86d4f-2a8b-4b17-8746-f8aae049ee27" alt=""><figcaption></figcaption></figure>

#### Example - bind to an array:

{% hint style="info" %}
**Version compatibility**

Binding an `object-dropdown` to an array was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

{% code title="main.view\.xml" %}

```xml
<var name="countries" type="query:country" />
<var name="selected_countries" type="array:country" />

<object-dropdown label="Previous countries of residence" placeholder="Select all that apply" query="countries" bind="selected_countries" required="false" />
```

{% endcode %}

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FqUVBk4w4jLhtgJirusx0%2FScreen%20Shot%202022-09-01%20at%203.17.40%20PM.png?alt=media&#x26;token=b952a8fd-fc45-4a88-8459-af7bfbacc6a0" alt=""><figcaption></figcaption></figure>

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `query`

**Required**

**Default**: unset

`query` contains the name of the [database query](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects) or [array](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects#arrays) variable to populate the objects in the `object-dropdown`.

```xml
<var name="countries" type="query:country" />
<!-- OR -->
<var name="countries" type="array:country" />

<object-dropdown query="countries" bind="selected_country" required="false" />
```

### `required`

{% content-ref url="../xml-fields/required" %}
[required](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/required)
{% endcontent-ref %}

## Advanced Attributes

### `align-content` <a href="#standard-attributes" id="standard-attributes"></a>

{% hint style="info" %}
**Version compatibility**

`align-content` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/align-content" %}
[align-content](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-content)
{% endcontent-ref %}

### `align-dialog-content`

**Optional**

**Type**: `center` | `left` | `right`

**Default**: `center`

{% hint style="info" %}
**Version compatibility**

`align-dialog-content` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

Specifies how the content of the list of options dialog should be aligned. This includes the display value of each option, as well as the header text of the dialog.

```xml
<object-dropdown label="Country of residence" align-dialog-content="left" query="countries" bind="selected_country" />
```

### `align-label`

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `clear-button-visibility`

{% content-ref url="../xml-fields/clear-button-visibility" %}
[clear-button-visibility](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/clear-button-visibility)
{% endcontent-ref %}

### `dialog-title`

**Optional**

**Type**: `string`

**Default**: "Choose an option"

{% hint style="info" %}
**Version compatibility**

`dialog-title` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

Header text of the dialog that displays the list of options of the `object-dropdown`.

```xml
<object-dropdown label="Country of residence" dialog-title="Choose the country of residence" query="countries" bind="selected_country" />
```

### `disabled`

{% content-ref url="../xml-fields/disabled" %}
[disabled](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/disabled)
{% endcontent-ref %}

### `display`

**Optional**

**Type**: `string`

**Default**: The `<display/>` tag of the object as defined in the app's data model

Specifies the display value of each option in the `object-dropdown` list. Can be a static string, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml).

{% code title="schema.xml" %}

```xml
<model name="country" label="Country">
    <field name="name" label="Name" type="text:name"/>
    <field name="population" label="Population" type="integer"/>
    
    <display>{name}</display>
</model>
```

{% endcode %}

{% code title="main.view\.xml" %}

```xml
<!-- Here the display value for each option is the country's name and population, separated by a "-" -->
<object-dropdown label="Country of residence" display="{name} - {population}" query="countries" bind="selected_country" required="true" />
```

{% endcode %}

### `empty-message`

{% hint style="info" %}
**Version compatibility**

`empty-message` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `string` (static text, a [format string](https://docs.journeyapps.com/reference/app-features/xml-format-strings) or the return value of a [JS/TS function](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml))

**Default**: unset

Text that is displayed if no options are available to list once the user opens the `object-dropdown`.

### `icon-position` <a href="#standard-attributes" id="standard-attributes"></a>

{% hint style="info" %}
**Version compatibility**

`icon-position` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/icon-position" %}
[icon-position](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/icon-position)
{% endcontent-ref %}

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.84.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `label-color`

{% content-ref url="../xml-fields/label-color" %}
[label-color](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-color)
{% endcontent-ref %}

### `modifier-text`

{% hint style="info" %}
**Version compatibility**

`modifier-text` was introduced in version **4.84.0** of the JourneyApps Run
{% endhint %}

{% content-ref url="../xml-fields/modifier-text" %}
[modifier-text](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/modifier-text)
{% endcontent-ref %}

### `on-change`

{% content-ref url="../xml-fields/on-change" %}
[on-change](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-change)
{% endcontent-ref %}

### `placeholder`

{% content-ref url="../xml-fields/placeholder" %}
[placeholder](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/placeholder)
{% endcontent-ref %}

### `search-controls`

**Optional**

**Type**: `auto` | `none` | `show`

**Default**: `auto`

{% hint style="info" %}
**Version compatibility**

`search-controls` was introduced in version **4.84.0** of the JourneyApps Runtime`.`
{% endhint %}

Set the visibility of the search box of the `object-dropdown` component. `auto` shows the search box when the list of options contains 12 options or more. `none` never shows the search box, and `show` always shows the search box at the top of the list of options.

```xml
<object-dropdown label="Country of residence" query="countries" bind="selected_country" search-controls="show" />
```

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.objectDropdown({id:'my-id'})` is called from JS/TS:

### `clear`

Programmatically clear the selected value(s) bound to the `object-dropdown`.

### `clearSearch`

Programmatically clear a value entered into the search box.

### `openDropdown`

Programmatically open the list of items.

### `closeDropdown`

Programmatically close the list of items.

### `scrollDown`

Programmatically scroll down the list of items when the `object-dropdown` is opened.

### `scrollIntoView`

Programmatically scroll until the `object-dropdown` is visible in the view.

### `scrollUp`

Programmatically scroll up the list of items when the `object-dropdown` is opened.

### `selectItem`

Programmatically select an item from the list by its display value.

{% code title="main.view\.xml" %}

```xml
<var name="countries" type="query:country" />
<var name="selected_country" type="country" />

<object-dropdown id="my-dropdown" query="countries" bind="selected_country" label="Country" />
```

{% endcode %}

{% code title="main.js" %}

```javascript
function select() {
    component.objectDropdown({id: 'my-dropdown'}).openDropdown(); // Need to open the dropdown first
    component.objectDropdown({id: 'my-dropdown'}).selectItem("Germany");
}
```

{% endcode %}

### `selectItemByIndex`

Programmatically select an item from the list by its index. **Note**: Indexes begin at 1.

{% code title="main.view\.xml" %}

```xml
<var name="countries" type="query:country" />
<var name="selected_country" type="country" />

<object-dropdown id="my-dropdown" query="countries" bind="selected_country" label="Country" />
```

{% endcode %}

{% code title="main.js" %}

```javascript
function select() {
    component.objectDropdown({id: 'my-dropdown'}).openDropdown(); // Need to open the dropdown first
    component.objectDropdown({id: 'my-dropdown'}).selectItemByIndex(2);
    // Selects the second country in the list
}
```

{% endcode %}

### `setSearch`

Programmatically enter a search value and triggers a search of the `object-dropdown`.