Links

object-list

Overview

An object-list displays data from objects (from database query or array) in a visible way. It differs in this regard from the 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:

Initialization of Data for object-list

All object-list variations (see below) use a DB query or array to determine which objects to display.
main.view.xml
<var name="all_items" type="query:item" />
<!-- OR -->
<var name="all_items_array" type="array:item" />
main.js
function init() {
view.all_items = DB.item.all();
// OR
view.all_items_array = DB.item.all().toArray();
}

Non-Selectable object-list

This list can be used for display purposes only and doesn't allow the user to select anything.
main.view.xml
<var name="all_items" type="query:item" />
​
<object-list query="all_items" label="All Items:" empty-message="There are no items" />

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)
main.view.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" />

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.
main.view.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>
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 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.
main.js
function selectItem(clickedItem) {
navigate.link("view_item", clickedItem);
}
We can also call the link directly from the on-press attribute:
main.view.xml
<action on-press="navigate.link('view_item', $selection)" />

Standard Attributes

bind

bind only applies to selectable object-lists.

label

query

Required
Default: unset
query contains the name of the query or array variable to populate the objects in the object-list.
<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

required only applies to selectable object-lists.

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-dropdown list. Can be a static string, a format string or a JS/TS function.
schema.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>
main.view.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" />

empty-message

Optional
Type: string (static text, a format string or the return value of a JS/TS function)
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