Comment on page

View Navigation

Definitions
The following terms are used throughout this page and are defined as:
Action
A navigational function that will navigate the user from the current view to another.
Actions include:
link
dismiss (and discard - a special case)
replace
clear
Navigational actions are namespaced to navigate.<action>().
Version compatibility
The navigate namespace and its primary navigation actions were introduced in version 4.50 of the JourneyApps Container.
navigate.getDeeplink was introduced in version 4.89.0 of the JourneyApps Runtime. See more details about deep linking to a view here.
Navigate
Transitioning from one view to another, modifying the view stack. Forward navigation adds a view to the view stack. Backward navigation navigates back to a view that is already on the view stack, while removing all views in between.
Top level view
A view that is not dependent on other views, i.e. it can be navigated to from anywhere in the app, and is typically used as the starting point of a workflow.
View stack
A virtual representation of the navigation history, with the current view at the top of the stack.
Accessed in JS using journey.viewStack. Please refer to the viewStack reference for more details.
View path
A unique path representing a view (which you specify when you create a view) used to navigate to the particular view.
Accessed from JS using view.path.
The view path is especially useful for functions in SharedJS or if you are logging usage of the app to an analytics service.
View parameters
Some views may expect data to be passed when navigating to them. These can be objects or other data types and are are specified in a view’s XML. Any view variable or JS variable may be passed as parameters (referred to as params).
For example, the view new_user requires two parameters (group and name) to passed to it:
<view title="New User">
   <param name="group" type="group"/>
   <param name="name" type="text"/>
   ...
</view>
Using object parameters simplify apps where there are multiple steps that work with the same object. For example, if the group object above is used or modified in multiple successive steps as part of a linear flow, you should specify it as a parameter for those views.
An example of a valid link to reach this view would be navigate.link('new_user', view.group, view.user_name), refer to Linking to a view for more detail.
View parameter attributes
required
Version compatibility
The required attribute was introduced in version 4.89.0 of the JourneyApps Runtime.
Optional
Type: boolean
Default: true
main.view.xml
<param name="job" type="job" required="false"/>
​
Specify whether a view parameter requires a value or not. If this attribute is set to false, the parameter does not require a value when navigating to the view (in-app or when using deep links). Important: this is only the case when there are no subsequent parameters in the link. For this reason, it is recommended to list required parameters first in a view, and optional parameters last.
Example
Given the following view:
job_details
<param name="job" type="job" required="true" />
<param name="site" type="site" required="true" />
<param name="current_date" type="date" required="false" />
The following links are valid:
main.ts
navigate.link('job_details', job, site);
navigate.link('job_details', job, site, new Date);
If the order of the view parameters were as follows:
job_details
<param name="job" type="job" required="true" />
<param name="current_date" type="date" required="false" />
<param name="site" type="site" required="true" />
Links need to include null for empty optional view parameters:
main.ts
navigate.link('job_details', job, null, site);
navigate.link('job_details', job, new Date, site);
transform-value
Version compatibility
The transform-value attribute was introduced in version 4.89.0 of the JourneyApps Runtime.
This attribute takes a function and passes an $event object. 
The $event object has the following structure:
"$event": {
    value: DB.object | string | null,
    param: {
        name: string // -> 'current_job'
        type: string // -> 'job'
        required: boolean // -> true
    }
}
Example:
main.view.xml
<param name="job" type="job" transform-value="$:loadJob($event)" />
<param name="compeletion_date" type="date" transform-value="$:getDate($event)" />
main.js
function loadJob(event) {
    // event.value => ''
    var job = DB.job.first(event.value);    
    return job;
}
​
function getDate(event) {
    // event.value => '1681822674806' | '1991/01/01' | null
    return new Date(event.value);
}
This function takes some input and outputs a value based on that input. It is not like any other JS/TS function; for example, navigate does not work within transform-value. Its sole purpose is to return a value to a view parameter.
This function is useful for setting a parameter where the event object needs to be transformed or retrieved from the DB from an ID. It is also useful to provide a fallback value (e.g. when a parameter is null).
The function always runs before init() . This ensures that anything that depends on the view parameter in init() can seamlessly execute.
It is executed every time before the view is added onto viewStack including:
In-app navigation using navigate() 
​Deep linking​
Note: The function does not execute when resume the flow happens (since in this case the view is already on the viewStack).
When an exception gets thrown in this function, the view cannot successfully load and the user will be taken to the main view.
Example use case
Here is an example use case to aid in explaining view navigation.
The above diagram represents the navigational flow of a fictitious app.
It consists of a Login page, from which the user navigates to individual landing views, according to some criteria (typically based on a role).
From a landing page, the user can navigate to any of the top level views and back, in any order. This is done using the replace action, only replacing the current view and not adding to the view stack. See Replacing a view.
When the user starts a linear flow from Top level 1, link is used. Navigating between steps adds to the view stack and allows the user to navigate forward and backward. (See Linking to a view and Dismissing a view).
When the user performs non-linear tasks, link from Top level 2 to Task 1 is used. Thereafter replace is used, allowing the user to jump between different tasks in the process. See Replacing a view.
The diagram also illustrates how clear is used, allowing the user to ‘log out’ and navigate to the login screen, clearing the views on the stack. See Clear and navigate.
Linking to a view
The link action performs forward navigation (→) and is typically used with linear workflows.
For example: A → B → C will result in a view stack of [A, B, C] with C being the active view.
Syntax
navigate.link(path, param1, param2, ...) — link to the specified view path and pass params.
Option
Required
Details
path
Required
String that represents a view path
params1, param2, …
Optional
Objects or other data passed to the view navigated to
Examples:
Using navigate.link in xml:
<view title="Main Menu">
    <button label="New User" on-press="$:navigate.link('new_user')" />
</view>
Notice the use of $:, this will evaluate the function in the view context.
Using navigate.link with params in JS
function editUser(currentUser){
    navigate.link('edit_user', currentUser);
}
link()
Deprecation warning
The link() function might be deprecated in the near future.
link.view_path() — link to the specified view path link.view_path.with.slash(params) — link to a view path containing / (the slashes are replaced with a .)
Using link in JS:
function createUser() {
    // Include other logic here
    link.new_user();
}
Dismissing a view
The dismiss action performs backward navigation (←).
Calling dismiss on a view (e.g. on a button press) will save and close that view and navigate to the previous view on the stack. Given a view stack of [A, B, C] dismiss ← will result in a view stack of [A, B].
To close the view without saving variables and view state, chain discard.
Closing multiple views, for instance to return to a top level view, use the dismiss action specifying a view path, navigate.dismiss('view_path').
Syntax
navigate.dismiss() — dismiss the active view 
navigate.dismiss(path) — dismiss to the specified view path
navigate.discard().dismiss(path) — dismiss to the specified view path without saving
Option
Required
Details
path
Optional
String that represents a view path. If no path is provided, the active view will be dismissed to the previous view on the stack.
Note: dismiss and discard does not take view parameters.
Examples:
Using navigate.dismiss to a view path in xml:
<button on-press="$:navigate.dismiss('main')" label="Main Menu" />
This will automatically save all objects defined in the view.
Using navigate.discard().dismiss in xml:
<button on-press="$:navigate.discard().dismiss('main')" label="Main Menu" />
dismiss()
Deprecation warning
The dismiss() function might be deprecated in the near future.
dismiss()— dismiss the active view 
discard() — dismiss the active view without saving 
discard.view_path() — dismiss to the specified view path without saving
Examples:
Using dismiss() in xml:
<button on-press="dismiss()" label="Save" />
This will automatically save all objects defined in the view.
Using discard() in xml:
<button on-press="discard()" label="Cancel" />
Replacing a view
Instead of adding a view to the view stack, the replace action (denoted by ⇌) replaces the current view and navigates to a new view.
For example: A → B ⇌ C will result in [A, C] on the view stack. A → B ⇌ C ⇌ D ⇌ B will result in [A, B] on the view stack.
The replace view action is typically used for non-linear workflows, but is also a powerful tool to build apps that consists of various top level views.
replace calls the target view’s init() function, instead of the resume() callback when navigating to it. You can read more about the resume callback in a section below.
Syntax
navigate.replace(path, param1, param2, ...) — replace with the specified view path passing params.
navigate.discard().replace(path, param1, param2, ...) — discard unsaved changes and replace with the specified view path, passing params.
Option
Required
Details
path
Required
String that represents a view path
param1, param2, …
Optional
Objects or other data passed to the view navigated to
Examples:
Using navigate.replace in xml:
<button on-press="$:navigate.replace('tasks/task_1')" label="Complete Task" />
Using navigate.replace in JS:
function toMyDashboard() {
    // Other logic here
    navigate.replace('dashboards/tech');
}
Using navigate.replace with params:
<button on-press="$:navigate.replace('tasks/task_2', view.results)" label="Complete Task" />
The replace action reduces the need to manage the view stack manually and makes for clearer navigation within your app.
Clear and navigate
The clear navigation action (denoted by ⇒) will remove all views currently on the view stack and navigate to the target view.
For example:
Normal linking A → B → C → D will have [A, B, C, D] on the view stack Performing ⇒ E will result in a view stack of [E]
Also when ⇒’ing to a view already on the stack, e.g. A → B → C → D ⇒ B will result in [B]
The clear action is typically used when navigating away from a point in the app, where the navigation history is not needed anymore, for instance when a user logs out.
Syntax
navigate.clear(path, param1, param2, ...) — clear and navigate to the specified view path, passing params.
navigate.discard().clear('view_path', param1, param2, ...) — discard unsaved changes, clear and navigate to the specified view path, passing params.
Option
Required
Details
path
Required
String that represents a view path
param1, param2, …
Optional
Objects or other data passed to the view navigated to
Examples:
Using navigate.clear in xml:
<list>
    <list-item on-press="$:navigate.clear('login')" header="Log out" icon="ion-home"/>
</list>
The clear action will save view state by default, but can be chained to discard() navigate without saving. Using navigate.clear in JS, without saving view state:
function cancelTasks(){
    // other logic here
    navigate.discard().clear('tech_landing');
}
Using navigate.clear with params in xml:
<button on-press="$:navigate.clear('dashboard', query_range_str, query_range_end)" label="Dashboard" />
Deep link to a view
Please see the following section for deep linking to a view when opening a container:
Deep Linking
resume Callback
A resume function may be defined on a view, which is called whenever the user returns to the view from a different view, either via a dismiss function or via the back button.
The resume function receives a single "from" parameter, with the following properties:
path: the path of view that the user returned from
dismissed: true if the dismiss() function or a dismiss link was used to return
back: true if the user used the back button to return
An example:
function resume(from) {
    if(from.dismissed && from.path == 'user/new') {
        dialog("New User", "A new user has been created");
    }
}
Resume functions may also chain further links. However, it is recommended to use a dismiss link instead.
Overriding the built-in back button
By default, the built-in back button has the same behavior as the discard() function.
This can be changed by specifying an on-back handler on the view. If the function triggers navigation or returns false, the default back behavior is suppressed. Otherwise, the default discard() is performed after the handler has completed.
Examples
<!-- Example 1: Save data when back is pressed. -->
<view title="Example" on-back="$:navigate.dismiss()">
    <!-- ... -->
</view>
<!-- Example 2: Confirm when going back. -->
<view title="Example" on-back="$:confirmBack()">
    <!-- ... -->
</view>
function confirmBack() {
    var confirmed = confirmDialog('Back', 'You will lose unsaved changes. Are you sure?', 'Yes', 'No').
​
    return confirmed;
}

Option	Required	Details
`path`	Required	String that represents a view path
`params1, param2, …`	Optional	Objects or other data passed to the view navigated to

Option	Required	Details
`path`	Optional	String that represents a view path. If no `path` is provided, the active view will be dismissed to the previous view on the stack.

Option	Required	Details
`path`	Required	String that represents a view path
`param1, param2, …`	Optional	Objects or other data passed to the view navigated to

Option	Required	Details
`path`	Required	String that represents a view path
`param1, param2, …`	Optional	Objects or other data passed to the view navigated to

Query DB Objects

Deep Linking

Last modified 3mo ago

View Navigation

Definitions

Action

Navigate

Top level view

View stack

View path

View parameters

View parameter attributes

`required`

`transform-value`

Example use case

Linking to a view

Syntax

Examples:

link()

Dismissing a view

Syntax

Examples:

dismiss()

Replacing a view

Syntax

Examples:

Clear and navigate

Syntax

Examples:

Deep link to a view

resume Callback

An example:

Overriding the built-in back button

Examples