# object-list

## Overview

An `object-list` displays data from objects (from [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)) in a visible way. It differs in this regard from the [`object-dropdown`](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-dropdown) component, the latter needs to be selected by a user to display the data and allow them to select an option.

An `object-list` can be customized in 3 ways:

* [Non-Selectable](#non-selectable-object-list)
* [Selectable](#selectable-object-list)
* [Clickable](#clickable-object-list)

### Initialization of Data for `object-list`

All `object-list` variations (see below) use a [DB 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) to determine which objects to display.

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

```xml
<var name="all_items" type="query:item" />
<!-- OR -->
<var name="all_items_array" type="array:item" />
```

{% endcode %}

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

```javascript
function init() {
     view.all_items = DB.item.all();
     // OR
     view.all_items_array = DB.item.all().toArray();
}
```

{% endcode %}

### Non-Selectable `object-list`

This list can be used for display purposes only and doesn't allow the user to select anything.

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

```xml
<var name="all_items" type="query:item" />

<object-list query="all_items" label="All Items:" empty-message="There are no items" />
```

{% endcode %}

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

### Selectable `object-list`

This list allows the user to select one of the objects in it, which is then highlighted. The selected object is stored in a specified variable (specified using `bind=""` see *Configuration* below).

A Selectable List is typically used in conjunction with a button — The user selects an object in the list, and then clicks a button to take an action — for example, calling a JavaScript/TypeScript function which does something with the object that the user selected (referencing the variable in which the selected object is stored), or follow a link (passing the selected object as a parameter to the next view)

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

```xml
<var name="all_items" type="query:item" />
<var name="selected_item" type="item" />

<object-list query="all_items" bind="selected_item" label="All Items:" empty-message="There are no items" />
```

{% endcode %}

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

### Clickable `object-list`

This list allows the user to tap or click on a particular object, a specified JavaScript/TypeScript function is then called, and the object that the user selected is passed as an argument to the JavaScript/TypeScript function.

An arrow on the right side of the `object-list` items hints to the user that the list items are clickable.

The JavaScript/TypeScript function that is called when the user taps on a list item is typically used to follow a link to a next screen — Therefore, a Clickable Regular List is used for similar cases as a Selectable Regular List, but it provides a better user experience because it requires less scrolling and tapping by the user.

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

```xml
<var name="all_items" type="query:item" />

<object-list query="all_items" label="All Items:" empty-message="There are no items">
  <action on-press="selectItem($selection)" />
</object-list>
```

{% endcode %}

Note that a function call of your choosing is specified at `on-press=""`, which you then need to define in the view's JavaScript/TypeScript. The object that the user selected can be passed as an argument to this JavaScript/TypeScript function (`clickedItem` in the example below) by using the special `$selection` variable.

The most common use case of a clickable list is to call a navigation [link](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/view-navigation) when the user clicks on an item, and pass the clicked object as an argument to the link — which we show in this example below.

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

```javascript
function selectItem(clickedItem) {
    navigate.link("view_item", clickedItem);
}
```

{% endcode %}

We can also call the link directly from the [`on-press`](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/action#on-press) attribute:

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

```xml
<action on-press="navigate.link('view_item', $selection)" />
```

{% endcode %}

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

## Standard Attributes

### `bind`

{% hint style="info" %}
`bind` only applies to [selectable](#selectable-object-list) `object-list`s.
{% endhint %}

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

### `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 query or array variable to populate the objects in the `object-list`.

```xml
<var name="all_items" type="query:item" />
<var name="selected_item" type="item" />

<object-list query="all_items" bind="selected_item" label="All Items:" empty-message="There are no items" />
```

### `required`

{% hint style="info" %}
`required` only applies to [selectable](#selectable-object-list) `object-list`s.
{% endhint %}

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

## Advanced Attributes

### `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-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-list label="Country of residence" display="{name} - {population}" query="countries" bind="selected_country" required="true" />
```

{% endcode %}

### `empty-message`

**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**: "No items to display"

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

### `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 %}