All View Components → object-table

Select a view component to see details on how it works:

object-table

A component that displays a objects in a table, and optionally allows the click on one of the objects / rows.

Similar to Regular Lists, tables can be customised in three different ways:

Non-Selectable Table	Selectable Table	Clickable Table
This table can be used for display purposes only and doesn't allow the user to select anything.	This table 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).	This table allows the user to tap / "click" on a particular row/object, and a specified JavaScript function is then immediately called, and the object that the user selected is passed as an argument to the JavaScript function.

	A Selectable Table is typically used in conjunction with a button — The user selects an object in the table, and then clicks a button to take an action — for example call a JavaScript 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)	The JavaScript function that is called when the user taps on a row is typically used to follow a link to a next screen — Therefore, a Clickable Table is used for similar cases as a Selectable Table, but it provides a better user experience because it requires less scrolling and tapping by the user.

Applicable to All Examples: Initialisation of Data in JavaScript

All object-tables use a Query to determine what objects are displayed in it. The query is stored in an array variable.

Code in View XML:

<var name="all_items" type="item" array="true" />

Code in View JavaScript:

// This function is called each time the view is loaded
function init() {
    // initialize any data here that should be available when the view is shown
     view.all_items = DB.item.all();
}

Example 1 — Non-Selectable Table

Code in View XML:

<!-- Variables go here: -->
<var name="all_items" type="item" array="true" />

<!-- Components go here: -->
<object-table collection="all_items" label="Snag List Items">
    <column heading="Number">{number}</column>
    <column heading="Name">{name}</column>
</object-table>

Appearance on mobile device:

Example 2 — Selectable Table

Since a Selectable Table allows the user to select an option, you need a variable in which to store the selected object, and then specify that variable at bind="" in the object-table.

Code in View XML:

<!-- Variables go here: -->
<var name="all_items" type="item" array="true" />
<var name="selected_item" type="item" />    

<!-- Components go here: -->
<object-table collection="all_items" bind="selected_item" label="Snag List Items">
    <column heading="Number">{number}</column>
    <column heading="Name">{name}</column>
</object-table>

Appearance on mobile device — when the last item has been selected:

Example 3 — Clickable Table

Code in View XML:

<!-- Variables go here: -->
<var name="all_items" type="item" array="true" />

<!-- Components go here: -->
<object-table collection="all_items" label="Snag List Items">
    <column heading="Number">{number}</column>
    <column heading="Name">{name}</column>
    
    <action onpress="selectItem" />
</object-table>

Note that a function name of your choosing is specified at onpress="", which you then need to define in the view's JavaScript. The object that the user selected in the object-table is passed as an argument to this JavaScript function (clickedItem in the example below).

The most common use case of a Clickable Table is to call a 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.

Code in View JavaScript:

function selectItem(clickedItem) {
  return link.view_item(clickedItem);
}

The appearance of a Clickable Table on a mobile device is currently the same as a Non-Selectable Table:

Configuration:

Option	Required?	Details
`collection`	required	Name of the array variable storing the query to populate the objects shown in the table. Note that the sorting of the query will determine the sort order of the items in the object-table. See Sorting for more information.
`bind`	optional	The name of the variable in which the object that the user has selected must be stored. It must be an object of the same type as in `collection`. If `bind` is not specified, this table will be Non-Selectable.
`label`	optional	Text to display above the table. It can be a Format String to make the text dynamic.
`emptyMessage`	optional	Text to display when the `collection` is empty. Defaults to "No data".
`required`	optional	If this is a Selectable Table, setting `required="true"` will require the user to select an object before proceeding to a next view. Defaults to `false`.
`show-if`	optional	Controls whether the component is hidden or shown. The argument specified to `show-if` can either be a literal boolean value (`true` or `false`), or it can specify a variable, parameter or attribute that can be a string, number, object, etc. that evaluates to false or evaluates to true (see the section Show/Hide Components Dynamically for full details).
`hide-if`	optional	The opposite of `show-if` (see above).

Nested Tags — Columns

An object-table can contain any number of <column> tags that respresent the vertical columns in the table.
Not to be confused with the columns component used for tablet apps.

Each column contains a Format String for the value of the column in each row — typically an attribute of the object.

A column may optionally have a heading attribute (Format String). If at least one column has a heading attribute, a header row will be added to the table with the headings of the columns.