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:

• Non-Selectable

• Selectable

• Clickable

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.

pagebind

label

pagelabel

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.

pagerequired

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

pageshow-ifpagehide-if