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:
stringDefault: 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 9mo ago