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. paginate (Paginating mode) (default)

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. $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. 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. 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');
}