Links

list

Overview

Version compatibility
list was introduced in version 4.29.0 of the JourneyApps Container.
It received several functional updates in version 4.84.0 of the JourneyApps Runtime.
The list UI component lists clickable items in a more visually prominent and customizable manner than pure text-based lists. list is a very versatile UI component and can be applied in many use cases, some common ones include:
  • A list of jobs, where each job is color-coded per its status
  • A set of photos taken, where the photo is displayed in thumbnail format on the item
  • A set of navigational links
  • A list of actions or workflow steps where each action could show a completed state

Basic Structure

main.view.xml
<var name="tickets" type="query:ticket" />
<list empty-message="No recent field tickets" controls="top" limit="5">
<list-item query="tickets">
<pills>
<pill label="{date}" color="{rig.color}" />
</pills>
<header>{customer}</header>
<content>Pad: {pad_name} | Well: {well_name} | Rig: {rig}</content>
<footer>Total: ${ticket_total}</footer>
<accent label="Ticket Status: {status}" color="$:getStatusColor($object)" />
<action on-press="selectTicket($selection)" />
</list-item>
</list>
list contains one or many list-item elements, which are either static (for basic usage) or dynamic (will repeat itself for each item in a query).
See the list-item documentation for further details:

Standard Attributes

label

Advanced Attributes

align-label

controls

Optional
Type: none | bottom | top | both
Default: none
Version compatibility
controls was introduced in version 4.84.0 of the JourneyApps Runtime.
Controls allow a user to search a list and, if the list is paginated, to navigate to the next, previous or a specific page. Controls are hidden by default, but can be positioned at the bottom and/or top of a list.
<list controls="top">
<list-item>
...
</list-item>
</list>

Positioning

Parameter
Description
Example
top
Positions controls at the top of the list
controls="top"
both
Positions controls at top AND bottom of the list
controls="both"
bottom
Positions controls at the bottom of the list
controls="bottom"
none
No controls
controls="none"

content-direction

Version compatibility
content-direction was introduced in version 4.86.1 of the JourneyApps Runtime.
Optional
Type: left-to-right, right-to-left
Default: left-to-right
Specify the direction of the component’s content. Typically this mirrors all elements within the component.
<columns>
<column>
<info>content-direction="left-to-right"</info>
<list content-direction="left-to-right">
<list-item icon="fa-plus-circle">
<pills>
<pill label="Newly created users: 4" color="positive" />
</pills>
<header>Add User</header>
<content>Add a new user to the selected district</content>
</list-item>
</list>
</column>
<column>
<info>content-direction="right-to-left"</info>
<list content-direction="right-to-left">
<list-item icon="fa-plus-circle">
<pills>
<pill label="Newly created users: 4" color="positive" />
</pills>
<header>Add User</header>
<content>Add a new user to the selected district</content>
</list-item>
</list>
</column>
</columns>

label-case

Version compatibility
label-case was introduced in version 4.86.1 of the JourneyApps Runtime.

label-color

Version compatibility
label-color was introduced in version 4.86.1 of the JourneyApps Runtime.

limit

Version compatibility
limit was introduced in version 4.84.0 of the JourneyApps Runtime.
Optional
Type: integer (minimum 2)
Default: none
The limit specifies the maximum number of list-items shown on a single page in a list. Once a limit is defined, the list becomes paginated and automatically computes how many pages there will be based on the total amount of items available from the query attribute.
Tip: When setting a limit ensure you also set the controls attribute. This will allow users to paginate and search as necessary.
<list controls="top" limit="8">
<list-item>
...
</list-item>
</list>

empty-message

Version compatibility
empty-message was introduced in version 4.84.0 of the JourneyApps Runtime.
Optional
Type: string
Default: unset
Text that is displayed inside the list when it is empty.
<list label="Technicians assigned to the job" empty-message="No technicians are currently assigned">
<list-item query="assigned_technicians">
...
</list-item>
</list>

icon-position

Version compatibility
icon-position was introduced in version 4.86.1 of the JourneyApps Runtime.
Note
icon-position specifies the icon position for all list-items in the list, whether the icon was defined per its shorthand version or longhand version.

id

show-if and hide-if

show-pagination

Version compatibility
show-pagination was introduced in version 4.89.0 of the JourneyApps Runtime.
Optional
Type: boolean
Default: true
In a paginated list, and when controls are shown, the show-pagination attribute can be used to show or hide the pagination controls. This may be useful for lists that only have a single page.
Version compatibility
show-search was introduced in version 4.89.0 of the JourneyApps Runtime.
Optional
Type: boolean
Default: true
When controls are shown, the show-search attribute can be used to show or hide the search box independent of the pagination controls.

Component Methods

The following component methods are available when an id is assigned to the component and component.list({id:'my-id'}) is called from JS/TS:

clearSearch

Programmatically clears the search value from the search box.

nextPage

Programmatically select the next page in a paginated list.

previousPage

Programmatically select the previous page in a paginated list.

scrollIntoView

Programmatically scroll until the list is visible in the view.

selectItem

Select a list-item from the list by its header text. This will trigger the list-item's on-press event.
main.view.xml
<list id="my-list">
<list-item>
<header>Manage Assets</header>
<action on-press="$:manageAssets()" />
</list-item>
<list-item>
<header>Manage Categories</header>
<action on-press="$:manageCategories()" />
</list-item>
</list>
main.js
function select() {
component.list({id: 'my-list'}).selectItem('Manage Assets');
}

selectItemByIndex

Select a list-item from the list by its index. This will trigger the list-item's on-press event. Note: Indexes begin at 1.
main.view.xml
<list id="my-list">
<list-item>
<header>Manage Assets</header>
<action on-press="$:manageAssets()" />
</list-item>
<list-item>
<header>Manage Categories</header>
<action on-press="$:manageCategories()" />
</list-item>
</list>
main.js
function select() {
component.list({id: 'my-list'}).selectItemByIndex(1);
// Selects the "Manage Assets" list-item
}

selectPage

Programmatically select the a page in a paginated list by its page number.

setSearch

Programmatically enter a search value and triggers a search of the list.