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:

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

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

Previousobject-table (v1) (deprecated)Nextscan-barcode (legacy docs)

Last updated 2 years ago

Top-level attributes

Column-level attributes

Sorting

Mode

Row and Cell Formatting

Row vs Cell styling

Styleable properties

style=``

Editing Cells

Display and edit flow

Example

Properties on <edit-

Example

<edit- types

edit-select examples

Cell-level actions

Object Table Actions

Example: One-click CSV export

Properties on `<edit-`

`<edit-` types

`edit-select` examples