list (legacy docs)

These list docs are out of date

New functionality and features were added to list in version 4.84.0 of the JourneyApps Runtime. Please refer to the latest docs here.

Version compatibility

list was introduced in version 4.29.0 of the JourneyApps Container.

This component should be used whenever you have a list of items that need to be used to navigate the user to another page, whether it’s a menu on the main view, a list of employees that need to get inspected and managed, or a list of messages or notifications that need to be viewed or read. Since it’s so customizable, you can adapt this component to look suitable for whatever you need to use it for.

Basic structure

list contains one or many list-item nodes.

<list>
    <list-item .. />
    <list-item .. />
    <list-item .. />
</list>

A list-item can be defined as either static (for basic usage) or dynamically (will repeat itself for each item in a query). A simple static list will be defined as:

<list>
    <list-item content="Accept" />
    <list-item content="Reject" />
    <list-item content="More info" />
</list>

While a dynamic list will be defined as:

<list>
    <list-item query="my_query" content="{title}" />
</list>

You can also mix dynamic and static list items together such as:

<list>
    <list-item content="More info" />
    <list-item query="my_query" content="{title}" />
    <list-item content="Accept" />
    <list-item content="Reject" />
</list>

Doing so allows for the creation of complex menu-like structures that contain the flow of navigation.

list-item syntax

list-item tags can be represented as either shorthand (perfect for quick and common use cases) or longhand (for more complicated use cases). In shorthand mode, you can simply add attributes such as content="test" on a list-item while in longhand mode you can nest a <content>test</content> tag inside the list-item.

Shorthand

<list>
    <list-item content="More info" />
</list>

Longhand

<list>
    <list-item>
        <content>More Info</content>
    </list-item>
</list>

Shorthand and longhand can be combined:

<list-item header="My header">
    <pills list="$:getMyPills()" />
</list-item>

Examples of all properties

<!-- The presence of `query` makes the list dynamic -->
<!-- The presence of `bind` makes the list selectable -->
<list-item query="my_query" bind="my_var">

    <header>Header</header>
    <!-- or -->
    <header>{formatString}</header>

    <content>Content</content>
    <!-- or -->
    <content>{formatString}</content>

    <footer>Content</footer>
    <!-- or -->
    <footer>{formatString} </footer>

    <asset icon="my-icon-name" />
    <!-- or -->
    <asset src="{formatString}" />
    <!-- or -->
    <asset src="{dbObject.photo}" /> <!-- Supported from v4.31 of the JourneyApps Container -->

    <accent color="positive" label="Label" />
    <!-- or -->
    <accent color="$:getColor()" label="{formatString}" />
    <!-- or -->
    <accent color="{formatString}" label="Label" />

    <!-- The presence of `action` makes the list clickable -->
    <!-- In dynamic list, you can pass the selected item via $selection -->
    <action icon="my-icon-name" on-press="clickedFunction" />
    <!-- or -->
    <action icon="my-icon-name" on-press="$:clickedFunction()" />
    <!-- or -->
    <action icon="my-icon-name" on-press="doSomething($selection)" />

    <pills list="$:getList()">
        <!-- or -->
        <pill color="positive" label="Label" show-if="$:condition()" hide-if="$:condition()"/>
        <pill color="$:getColor()" label="{formatString}" show-if="$:condition()" hide-if="$:condition()"/>
        <pill color="{formatString}" label="{formatString}"/>
    </pills>
</list-item>

Full list of supported shorthand properties

<list-item
    header=".."
    content=".."
    footer=".."
    icon=".."
    image=".."
    on-press=".."
    on-press-icon=".."
/>

Item	Description	Example	Shorthand supported?
header	The header of the list item. Can be a static string or a format string.	<header> Important header </header>	Yes
content	The content of the list item. Can be a static string or a format string.	<content> More details here </content>	Yes
footer	The footer of the list item. Can be a static string or a format string.	<footer> Created {daysCreated} days ago </footer>	Yes
asset	The icon or image to display on the left-hand-side of the item. The icon can be a Font Awesome icon or an Ionicons icon. Valid values for color: Any of your app's named colors (primary, secondary, positive, negative, etc) A hex value, e.g. #FFF A view variable my_var A function resolving to any of the above values, e.g. $:getMyColor() Defaults to: none To use an image, use the src attribute. Any uploaded png can be used. SVG files can be used from v4.36 of the JourneyApps Container. Both SVGs and PNGs will also use the color from v4.36 Both support the use of format strings and expressions.	<asset icon="ion-home" /> <asset icon="ion-home" color="positive" /> <asset icon="{$:getMyIcon()}" /> <asset icon="{iconToShow}" />	Yes
accent	label: Format String (optional) color: String (optional) Valid values for color: - Any of your app's named colors (primary, secondary, positive, negative, etc) - A hex value, e.g. #FFF - A view variable my_var - A function resolving to any of the above values, e.g. $:getMyColor() Defaults to: info	<accent label="{formatString}color="string" />	No
action	See below		Yes (on-press and on-press-icon)
pills	See below		No

action

Lists support the <action> tag, making it clickable.

In dynamic lists, the current item is passed through to the `on-click` as `$selection`, e.g. `on-click="doSomething($selection)"`

The <action> tag has the following configuration:

Option	Required	Details
on-press	required	The JavaScript/TypeScript function call to be performed when the user clicks on the list item.
icon	optional	The icon to display on the right-hand side. Valid options include any Ionicon. Defaults to no icon.
validate	optional	Whether to run field validation before calling the associated on-press (see above). Can be either true, false, or the result of a function, e.g. ($:shouldBeValidated()).

pills

<pills> appear next to the header of an item. They can be used to convey status-like information about the item in a dynamic and colorful way. Pills can either be declared in the view XML (Static pills) or in the view JS (Dynamic pills)

Static Pills

<pills>
    <pill label="Status" color="positive" show-if="$:shouldShowPill()" />
</pills>

Option	Required	Details
label	Required	The text to display in the pill. Can be a format string.
color	Optional	The color of the pill. Valid values for color: Any of your app's named colors (primary, secondary, positive, negative, etc) A hex value, e.g. #FFF A view variable my_var A function resolving to any of the above values, e.g. $:getMyColor() Defaults to: primary
show-if	Optional	If the pill should display or not. Valid values include true, false or the result of a function, e.g. $:shouldShowPill() Defaults to: true
hide-if	Optional	The opposite of show-if. Defaults to: false

Dynamic Pills

Alternatively, you can return an array of pills from the view JS. e.g.

<pills list="$:getMyPills()" />

function getMyPills() {
    return [
        {label: "Pill 1", color: "negative"},
        {label: "Pill 2", color: "info"}
    ];
}

Note: Returned pill objects only have label and color attributes. All returned objects will show as pills.

function getMyPills(obj) {
    var myPills = [];
    if (obj.status == 'In progress') {
        myPills.push({
            label: "In progress",
            color: "info"
        });
    }
    if (!obj.recently_updated) {
        myPills.push({
            label: "Needs attention",
            color: "warning"
        });
    }
    return myPills;
}

Static lists

Example 1: Menu

Tip: Use a list instead of a menu with a lot of button elements inside of it. list is a lot more compact and more familiar to the user than a long list of buttons.

<list>
    <list-item header="Home" icon="ion-home" on-press="$:goToHome()" on-press-icon="ion-chevron-right" />
    <list-item header="Back" icon="ion-back" on-press="$:goBack()" on-press-icon="ion-chevron-right" />
</list>

Without using short-hand syntax, declaring the above menu looks like this:

<list>
    <list-item>
        <header> Home </header>
        <asset icon="ion-home" />
        <action icon="ion-chevron-right" on-press="$:goToHome()" />
    </list-item>
    <list-item>
        <header> Back </header>
        <asset icon="ion-home" />
        <action icon="ion-ios-arrow-back" on-press="$:goBack()" />
    </list-item>
</list>

Dynamic lists

<list>
    <list-item query="my_query">
        <header> {name} </header>
        <content> Click here for more info on {name} </content>
        <accent color="{color}" />
        <action icon="ion-chevron-right" on-press="$:show($selection)" />
    </list-item>
</list>

Static & Dynamic lists

<list>
    <list-item>
        <header> New User </header>
        <content> Click here to create a new user </content>
        <accent color="positive" />
        <action icon="ion-chevron-right" on-press="createNewUser" />
    </list-item>
    <list-item query="my_users">
        <header> {name} </header>
        <content> Click here for more info on {name} </content>
        <accent color="info" />
        <action icon="ion-more" on-press="show($selection)" />
    </list-item>
</list>