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 accompanying navigation actions were introduced in v4.50 of the JourneyApps Container.
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.

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);
}
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" />

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;
}
Copy link
On this page
Definitions
Example use case
Linking to a view
Dismissing a view
Replacing a view
Clear and navigate
resume Callback
Overriding the built-in back button