object-list
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: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();
}
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" />

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" />

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);
}
main.view.xml
<action on-press="navigate.link('view_item', $selection)" />

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" />
Optional
Type:
string
Default: The
<display/>
tag of the object as defined in the app's data modelSpecifies 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" />
Optional
Default: "No items to display"
Text that is displayed if no options are available to list once the user opens the
object-list
.Last modified 1yr ago