Linking Views (deprecated)

This method of linking views is deprecated in favor of the navigate.x syntax

Support for link.x and dismiss.x may be dropped in future versions of the JourneyApps Runtime. Please update your app to use the navigate.x syntax to ensure that your app remains compatible with the JourneyApps Runtime.

View Paths

Each view has a unique path (which you specify when you create a view), which is used to link to it.

It is possible to get the name of the view path in the JS using view.path. This is especially useful for functions in the SharedJS or if you are logging usage of the app to an analytics service.

Using Links (deprecated)

Links are global functions defined using link. You can access the link function from both the XML and JS. Using the 'link' function adds the linked view to the view stack.

From the XML (deprecated)

Links can be specified in the XML in any components with an on-press option. Here's an example where the user is navigated to the new_user view when clicking on the button:

<view title="Main Menu">
    <button label="New User" on-press="link.new_user()" />
</view>

From the JS

The same link function can be used in the JS. This is useful when more logic is required before navigating a user to another view.

However, for the simple example above, the following XML and JS code would be required to link via the JS:

<view title="Main Menu">
    <!-- This button calls a JS  -->
    <button label="New User" on-press="createUser()" />
</view>

function createUser() {
  	// Include other logic here!
    link.new_user();
}

Parameters

Some views expect certain data to be passed to them when navigating to them in the app. The data that is required is specified in "parameters". Parameters can be objects or other data.

For example, the view new_user might require two parameters to function correctly:

<view title="New User">
    <param name="group" type="group"/>
    <param name="name" type="text"/>

    ...
</view>

An example of a valid link to reach this view would be the following (see both XML and JS examples):

...
<var name="group" type="group" />
<var name="user_name" type="text" />
...
<button label="New User" on-press="link.new_user(group, user_name)" />
...

// When linking from the JS
function createUser() {
    link.new_user(view.group, view.user_name);
}

Using object parameters simplifies apps where there are multiple steps that work with the same object. For example, if the group object above is used/modified in multiple successive steps as part of a linear flow, you should specify it as a parameter for those views.

Any view and JS variables may be passed as parameters.

Closing Views

To save and close a view on a button press, use the built-in function dismiss(). Example:

<button on-press="dismiss()" label="Save" />

This will automatically save all objects defined in the view. To close the view without saving, use discard() instead:

<button on-press="discard()" label="Cancel" />

Closing Multiple Views

To close multiple views, for example to return to the main menu, a named dismiss link can be used. These are the same as normal links, but use the global dismiss object instead of the link object. Note that dismiss links take no parameters.

<button on-press="dismiss.main()" label="Main Menu" />

Similarly, discard.main() can be used to go back without saving.

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="dismiss()">
   <!-- ... -->
</view>

function confirmBack() {
    var confirmed = confirmDialog('Back', 'You will lose unsaved changes. Are you sure?', 'Yes', 'No').

    return confirmed;
}

<!-- 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;
}

View Stack

Container Compatibility

This feature was released in v4.40.1 of the JourneyApps Container

The view stack is exposed to developers as journey.viewStack.

Example usage:

var views = journey.viewStack.views() // returns an array of view instances
var myView = journey.viewStack.findFirst('my_view_path'); // view instance or null
var myView = journey.viewStack.findLast('my_view_path'); // view instance or null
var myView = journey.viewStack.find('my_view_path'); // view instance or null

A view instance contains the following items:

Name	Type	Comment
path	string	The path name of the view, e.g. "inventory".
index	number	The position of the view on the stack, e.g. 3.
variables	object	Read-only object of the view variables.

journey.viewStack.findFirst() finds the first instance of the view on the stack, i.e. the one closest to the 'main' view.

journey.viewStack.findLast() finds the last instance of the view on the stack, i.e. the one closest to the current view. Since finding the last view on the stack is the more common, you can also use the alias journey.viewStack.find().