Links

object-table (v2) (deprecated)

object-table v2 is considered deprecated
Support for object-table v2 may be dropped in future versions of the JourneyApps Runtime. Please upgrade your app to use object-table v3 to ensure that your app remains compatible with the JourneyApps Runtime.
Version compatibility
object-table v2 was introduced in version 4.24.0 of the JourneyApps Container.

Top-level attributes

e.g.
<object-table limit="20" ...
Attribute
Details
Example
From version
limit
Integer. The number of items to display.
Defaults to 25
limit="10"
4.24.0
controls
Text. Where to place the controls (search bar, pagination controls). Options include: top, bottom, both, none. Defaults to bottom Note: When controls are set to none and the number of entries exceeds the limit, a "Show more" button will appear.
controls="top"
4.24.0
sticky-header
Boolean. Whether to freeze the header or not. Defaults to false
sticky-header="true"
4.24.0
sticky-footer
Boolean. Whether to freeze the controls (when they display at the bottom) Defaults to false
sticky-footer="true"
borderless
Boolean. Whether to display the outline borders or not. Defaults to false Note: Only applicable on mobile devices.
borderless="true"
4.24.0
smart-wrap
Boolean. Defaults to true Set to false for cases where default wrapping in table is not optimal.
smart-wrap="true"
4.24.0
mode
Text. scroll or paginate. Defaults to paginate. See Mode for more details
mode="scroll"
4.27.0
style, style-align, style-bold, etc.
Used to style an entire row given specific conditions. See Row and Cell Formatting for more details.
style="$:determineStyle($object)"
4.32.0
default-filter
The default value for filter= on columns inside the object table.
default-filter="false"
4.40.5
default-sorting
The default value for sorting= on columns inside the object table.
default-sorting="false"
4.40.5

Column-level attributes

e.g.
<column search="true" ... />
Attribute
Details
Example
From version
search
Boolean. Whether this column should be included when searching. Default:
  • When no columns specify a search="true", all columns are included when searching.
  • When any column is set to search="true, columns without it are not included in when searching.
search="true"
4.24.0
show-if, hide-if
Controls whether the column is hidden or shown.
show-if="$:shouldShowColumn()"
4.26.1
style, style-align, style-bold, etc.
Used to style a cell given specific conditions. See Row and Cell Formatting for more details.
style="$:determineStyle($object)"
4.32.0
icon
Adds an icon to the left-hand-side of a cell. The icon can be a Font Awesome icon or an Ionicons icon. Defaults to no icon.
icon="ion-checkmark"
4.32.0
sort
Puts the column into a default sort mode regardless of the underlying query. (Useful to indicate which column is being sorted when cells are editable). Can either be asc or desc
sort="asc"
4.32.0
sort-value
The value to sort the column on instead of the display value. Useful when the display value would be something like: R{cost} but the column should sort only on cost
sort-value="$object.cost"
4.32.0
filter
Boolean. Whether the column should be filterable. Defaults to true. Note: Filters only available on Desktop containers.
filter="true"
4.32.0
sorting
Boolean Whether the column is sortable. Defaults to true
sorting="false"
4.40.5

Sorting

All columns are sortable. Click on a column header to sort it, and again to toggle ascending/descending order.
If a column consists solely of numbers, it will be sorted by numeric value. Similarly, if the column can be matched as a date, the date value is used instead of the display value. Finally, it is possible to specify a sort-value attribute (see table above) to override this default behavior when the display value no longer represents the underlying scalar value (for example the display value being: Percent: {number}%)

Mode

Version compatibility
This feature was introduced in version 4.27 of the JourneyApps Container.
Object tables have two possible modes:
  1. 1.
    paginate (Paginating mode) (default)
  2. 2.
    scroll (Fixed height mode)
Note that for each of the two modes, limit has a different function.
Mode
Description
limit=
paginate
Data is loaded in pages, with controls to jump to the next or previous page.
The number of entries to display on a page
scroll
The data is loaded all at once, and the table itself is scrollable to reveal more data.
The height of the object table, measured in rows. e.g. limit="10" will fix the table's height to the same height as 10 one-line rows.
e.g.
<object-table mode="scroll" limit="10" ... />

Row and Cell Formatting

Version compatibility
This feature was introduced in version 4.32 of the JourneyApps Container.

Row vs Cell styling

  • To style a specific cell, the property should be added to the <column> tag.
  • To style an entire row, the property should be added to the <object-table> tag.
Example:
<!-- Adding style-bold here will bold the entire row if shouldBeBold returns true for that row -->
<object-table query="transactions" style-bold="$:shouldBeBold($object)">
<column heading="Title">{title}</column>
<!-- Adding style-background-color here styles each cell in the column individually -->
<column heading="Type" style-background-color="$:determineBackgroundColor($object)">{type}</column>
</object-table>

Styleable properties

Field
Description
Example
style-align
The alignment of the text within the cell. left, right, center Defaults to center
style-align="right" style-align="$:getAlignment($object)"
style-background-color
The background color of the cell. Default values include:
  • Hex value, e.g. #123456
  • Named color, e.g. positive, negative, primary, secondary, warning
Defaults to #FFFFFF (white)
style-background-color="positive" style-background-color="$:getBackgroundColor($object)"
style-bold
Boolean. If the text should be bold or not. Defaults to false
style-bold="true" style-bold="$:shouldBeBold($object)"
style-color
The text color of the cell. Default values include:
  • Hex value, e.g. #123456
  • Named color, e.g. positive, negative, primary, secondary, warning
Defaults to #111111 (JourneyApps default)
style-color="#123456" style-color="$:getTextColor($object)"
style-icon-color
The color of the left-hand-side icon (if present). Default values include:
  • Hex value, e.g. #123456
  • Named color, e.g. positive, negative, primary, secondary, warning
Defaults to #111111 (the same as JourneyApps's text default)
style-icon-color="positive" style-icon-color="$:getIconColor($object)"
style-italics
Boolean. If the text should be italicized or not. Defaults to false
style-italics="true" style-italics="$:shouldBeItalics($object)"
style-strikethrough
Boolean. If the text should be strikethrough or not. Defaults to false
style-strikethrough="true" style-strikethrough="$:shouldBeStrikethrough($object)"
style-underline
Boolean. If the text should be underlined or not. Defaults to false
style-underline="true" style-underline="$:shouldBeUnderline($object)"
style
Object. Combination of these attributes, programatically determined by the JavaScript/TypeScript. See section below for details.
style="$:getStyle($object)"
Example:
<object-table query="transactions">
<column heading="Title">{title}</column>
<column heading="Type" style-background-color="$:determineBackgroundColor($object)">{type}</column>
</object-table>
function determineBackgroundColor(obj) {
if (obj.type == 'Income') {
return 'positive';
} else {
// This is an expense
return 'negative';
}
}

style=``

Styles can be computed programmatically using JavaScript/TypeScript.
Example:
function getStyle(obj) {
// Return an object with all the same properties listed in the table above
// Properties do not have `style-` in front of them
// Camel-case is used instead of dashes
return {
align: 'left',
bold: true,
italics: true,
underline: true,
strikethrough: true,
// Colors can be hex or named
color: 'positive',
backgroundColor: 'positive',
iconColor: 'positive'
};
}
Notes:
  • Returning an empty object will apply no styling
  • Properties omitted from the returned object will not be affected

Editing Cells

Version compatibility
This feature was introduced in version 4.32 of the JourneyApps Container.
To make a cell editable, add an <edit- entry into the column. Valid options include edit-text, edit-number, edit-boolean, edit-date, edit-datetime and edit-select. They are explained in more detail below.

Display and edit flow

Step
Visually
Programatically
Initially
The object table will appear in a read-only (display) mode.
The value in display= is displayed.
As soon as the user taps or clicks on a cell
The cell will go into edit mode, allowing the user to modify the value.
The value in value= is shown to the user as the initial editing value.
After modifying the value, the user presses enter
The table goes back into display mode.
The function in on-change gets called and the value in display= gets recomputed and displayed.

Example

<object-table query="users">
<!-- The display value of the column moves into `display` -->
<column heading="Name" display="{name}">
<!-- `value` is the initial value shown when the user edits the cell -->
<!-- `on-change` is run when the users is done changing the value -->
<!-- Note that $object is exposed here for quick referencing -->
<edit-text value="$object.name" on-change="$:runOnChange($object, newValue, oldValue)" />
</column>
</object-table>

Properties on <edit-

Field
Description
Example
value
The initial editing value.
Can either be:
  • $object.[field]
  • The result of a function, e.g. $:getInitialEditingValue($object)
value="$object.name" value="$:getName($object)"
on-change
The function to be called as soon as the user hits enter. Note that $object, newValue and oldValue are exposed and can be passed to the function. Note return false if the cell should not automatically deselect after the user has pressed enter. This can be used for validations.
on-change="$:updateValue($object, newValue, oldValue)"
Caveat: Prepend $: to the on-change function
If you return false from your on-change function, be sure to prepend $: to your on-change value, e.g. $:updateValue($object, newValue, oldValue). This allows JourneyApps to handle the returned value correctly.

Example

<object-table query="items">
<column heading="Description">{description}</column>
<!-- Display the cost with a $ sign, e.g. $12 -->
<column heading="Cost" display="${cost}">
<!-- When the user edits the number, don't display the $ sign, only 12 -->
<edit-number value="$object.cost" on-change="$:updateCost($object, newValue)" />
</column>
</object-table>
function updateCost(obj, newValue, oldValue) {
if (isValidCost(newValue)) {
obj.cost = newValue;
obj.save();
} else {
notification.error("Invalid cost value");
// The cell will revert back to edit mode, allowing the user to correct the data that caused the validation error
return false;
}
}

<edit- types

Name
Details
Example
edit-text
Used to edit a string.
<edit-text value="$object.name" on-change="$:onChange($object, newValue, oldValue)" />
edit-number
Used to edit a number. A numerical keyboard will show on mobile.
<edit-number value="$object.age" on-change="$:onChange($object, newValue, oldValue)" />
edit-date
Used to edit a date. A date picker will show.
<edit-date value="$object.dob" on-change="$:onChange($object, newValue, oldValue)" />
edit-datetime
Used to edit a datetime. A date picker will show, followed by a time picker.
<edit-datetime value="$object.datetime" on-change="$:onChange($object, newValue, oldValue)" />
edit-boolean
Used to edit a boolean value. A checkbox will show.
<edit-boolean value="$object.some_property" on-change="$:onChange($object, newValue, oldValue)" />
edit-select
Used to pick a value from a list of possible values. Note:
  • Has an options tag, used to specify a list of options
See below
User Experience Tip: Specify an orderBy on your query
Since the default ordering for queries is by modification date, editing the value of an object's field via edit- will cause that object to be the last modified one. This causes your query to reload and the last modified object will be at the end of the list, creating the impression that it disappeared. To prevent this from happening, be sure to specify an orderBy on your query on something other than the modification date, e.g. DB.user.all().orderBy('name'). This keeps the ordering stable, resulting in better user experience.

edit-select examples

Example 1
Simple string array
<object-table query="users">
<column heading="Name"> {name} </column>
<!-- favorite_color is a string, one of: "Red", "Purple", "Blue", "Green", "Yellow" -->
<column heading="Favorite color" display="{favorite_color}">
<edit-select options="$:getColorOptions()" value="$object.favorite_color" on-change="$:updateFavoriteColor($object, newValue, oldValue)" />
</column>
</object-table>
function getColorOptions() {
return ["Red", "Purple", "Blue", "Green", "Yellow"];
}
function updateFavoriteColor(obj, newValue, oldValue) {
obj.favorite_color = newValue;
obj.save();
}
Example 2
Array of {key, value} objects
<object-table query="users">
<column heading="Name"> {name} </column>
<!-- favorite_color is a string, one of: "r", "p", "b", "g", "y" -->
<column heading="Favorite color" display="{favorite_color}">
<!-- Dropdown will display "Red", "Purple", "Blue", "Green", "Yellow" -->
<edit-select options="$:getColorOptions()" value="$object.favorite_color" on-change="$:updateFavoriteColor($object, newValue, oldValue)" />
</column>
</object-table>
function getColorOptions() {
return [
{
key: 'r',
value: "Red"
},
{
key: 'p',
value: "Purple"
},
{
key: 'b',
value: "Blue"
},
{
key: 'g',
value: "Green"
},
{
key: 'y',
value: "Yellow"
}
];
}
function updateFavoriteColor(obj, newValue, oldValue) {
// newValue is one of "r", "p", "b", "g", "y"
obj.favorite_color = newValue;
obj.save();
}
Example 3
Using a single object with key and value
<object-table query="users">
<column heading="Name"> {name} </column>
<!-- favorite_color is a string, one of: "r", "p", "b", "g", "y" -->
<column heading="Favorite color" display="{favorite_color}">
<!-- Dropdown will display "Red", "Purple", "Blue", "Green", "Yellow" -->
<edit-select options="$:getColorOptions()" value="$object.favorite_color" on-change="$:updateFavoriteColor($object, newValue, oldValue)" />
</column>
</object-table>
function getColorOptions() {
return {
'r': "Red",
'p': "Purple",
'b': "Blue",
'g': "Green",
'y': "Yellow"
};
}
function updateFavoriteColor(obj, newValue, oldValue) {
// newValue is one of "r", "p", "b", "g", "y"
obj.favorite_color = newValue;
obj.save();
}

Cell-level actions

Version compatibility
This feature was introduced in version 4.32 of the JourneyApps Container.
To apply an action on a cell-click level, add an <action> to the <column> tag.
<object-table>
<column>
<!-- `icon` is displayed on the right-hand-side of the cell -->
<action on-press="processAction($object)" icon="ion-chevron-right" />
</column>
</object-table>
For example:
<object-table query="items">
<column heading="Name">
{name}
</column>
<column heading="Cost" display="{cost}">
<action on-press="$:inspectCost($object)" icon="ion-chevron-right" />
</column>
</object-table>

Object Table Actions

Version compatibility
This feature was introduced in version 4.34.6 of the JourneyApps Container.
Object Table Actions enable additional buttons to be appended to the controls area of an object table. Additionally, these buttons can call functions passing the current data in the object table.
For example:
<object-table label="My Table" limit="17" empty-message="Your items will appear here" query="employees" mode="paginate">
<column heading="Name">{name}</column>
<column heading="Date" show-if="false">{date}</column>
<button-group>
<button icon="fa-download" label="Export CSV" on-press="exportCSV($filteredData, filteredDisplayData, controls)"/>
<button icon="fa-envelope" label="Email" on-press="exportCSV($filteredData, filteredDisplayData, controls)"/>
</button-group>
</object-table>
Each of the buttons call a function in their on-press attribute with the following three parameters:
  1. 1.
    $filteredData: An object of the form {columns: string[], rows: DatabaseObject[]}. DatabaseObject refers to the familiar JourneyApps object that can be used to update values in the database.
  2. 2.
    filteredDisplayData: An object of the form {columns: string[], rows: string[][]}. The rows correspond to the text currently displayed in the table. This object can be directly passed to CSV's stringify function to create a CSV export of the table's data.
  3. 3.
    controls: An object of the form {page: number, totalPages: number, limit: number, filters: {string: string[]}}. This represents the current state of the search criteria and filters applied to the object table.
In both parameters where data is passed to the function the sort order and current table filters are applied to the data.
User Experience Tip: Use mode="split" on the button-group
When you have more than one button in the button-group and would like to emphasize one of them, use mode="split". This will display the first button in the group and place the rest in an Action Sheet.

Example: One-click CSV export

<model name="employee" label="Employee">
<field name="name" label="Name" type="text:name" />
<display>{name}</display>
</model>
<view title="CSV Export">
<var name="employees" type="query:employee" />
<object-table label="Employees" query="employees">
<column heading="Name">{name}</column>
<button-group>
<button icon="fa-download" label="Export CSV" on-press="exportCSV($filteredData, filteredDisplayData, controls)"/>
</button-group>
</object-table>
</view>
function exportCSV(filteredData, filteredDisplayData, controls) {
var data = CSV.stringify(filteredDisplayData);
saveFile(data, 'data.csv');
}