Navigate Action

The action module for this action is "vb/action/builtin/navigateAction".

This action will navigate the user to a page and also pass any parameters to activate that page. Parameters for this action are:

Parameter Name	Description
page	The path to the destination page. The path can be a single page ID, or a path starting with a page ID. It can be an absolute path starting at the application or relative to the current page. When used with 'flow' or 'application', the path cannot be absolute; it navigates to the page relative to the flow or App UI.
flow	ID of the destination flow, used to change the content of the flow displayed in the current page. When used with 'page', navigates to the page in that flow.
target	Target of the destination flow, used with 'flow' to change the content of the parent flow instead of the nested flow. Values are 'parent' or 'self' (default).
application	ID of the destination App UI, used to change the content of the App UI displayed in the base application. When used with 'page' and 'flow', navigates to the page or flow in that App UI.
params	A key/value pair map that will be used to pass parameters to a page (optional)
history	Defines the effect on the browser history. Values are 'replace', 'skip' or 'push'. If the value is 'replace', the current browser history entry is replaced, meaning that the back button will not go back to it. If the value is 'skip', the URL is not modified. (optional and default is 'push')

Page input parameters are page variables with the Input Parameter enabled. You can use the Navigate action to set the value for these input parameters. But if a page parameter was a path to a deeply nested page, like /shell/main/other, you'll see a list of all input parameters from each page/flow in the path (that is, input parameters for the shell page, the main flow, as well as other pages). Name collisions across flows/pages are not accounted for—something you'll need to keep in mind when defining input parameters.

Here's an example of the navigate action:

"myActionChain": {
  "root": "navigate",
  "actions": {    
    "navigate": {
      "module": "vb/action/builtin/navigateAction",
      "parameters": {
        "page": "myOtherPage",
          "params": {
            "id": "{{ $page.variables.myId }}"
         }
       }
     }
   }
 }

This returns the outcome 'success' if there was no error during navigation. If navigation completed successfully, returns the action result true, otherwise false. Returns the outcome fail with the error in the payload if there was an error.

Navigating to the same page

Navigating to the same page with different input params is considered as a valid navigation. Since the current page is not changing, only the page input variable value will change and the onValueChanged event will be triggered. When navigating to the same page, the events vbBeforeEnter, vbEnter, vbBeforeExit, and vbExit are not triggered because the page never transitioned to an enter or exit state.

The navigation is pushed into the browser history, so pressing the browser's Back button will restore the previous values of the input variables.

Navigating between App UIs or from a page extension

Navigating to the default landing page of an App UI is always allowed, but navigation to any other pages is restricted to pages where navigation to them has been exposed. Exposing a page is done by marking it with the navigation fromExternal property set to 'enabled' in the page descriptor and the parent flow descriptor.

If you expose a page or flow to navigation, it becomes part of your extension API. That means that you can no longer rename, delete, or change the required input parameters for this page or flow, as extensions may depend on them.

When navigating from a page in one App UI to a page in another App UI, and the page in the second App UI is not exposed, will throw the following error, and navigation will be canceled:

Navigation from page main/main-start to appUI2/main/main-other is not enabled

Property	Description
`fromExternal`	Defines if navigation to this page or flow is allowed from another App UI or from a page extension. For navigation to be allowed to a page, the entire hierarchy of containers (parent flow, application) need to have this property set to 'enabled'.This property is not required for the default page of an application. The default for this property is 'disabled'.
`embeddable`	Defines if this page or flow can be embedded in an `oj-vb-switcher` component. For the page to be allowed to be embedded in a switcher, the entire hierarchy of containers (parent flow, application) need to have this property set to 'enabled'. The default for this property is 'disabled'.

Example 1-25 Page or flow descriptor with navigation fromExternal property set to enabled

"navigation": {
  "fromExternal": "enabled"
}

Navigating from a page extension

When navigation is executed from a page extension, only pages marked with the fromExternal property set to 'enabled' are valid destination. If it is not enabled for the page, the following error is thrown, and navigation is canceled:

Navigation from page extension main/main-start to main/main-other is not enabled

Navigation with the page parameter

The 'page' parameter is the ID of a sibling page or a path starting with a sibling page's ID (like pageId/flowId/...). It cannot be or start with a flow ID.

Example 1-26 Navigate to a sibling of the current page

To navigate to page other, a sibling of the current page:

"parameters": {
  "page": "other"
}

Example 1-27 Navigate to a sibling page and change content of the nested flow

To navigate to flow main, which is defined under the sibling page other:

"parameters": {
  "page": "other/main"
}

Example 1-28 Navigate to the root application

To navigate to the root of the application:

"parameters": {
  "page": "/"
}

Example 1-29 Navigate to the current flow's default page

To navigate to the current flow's default page:

"parameters": {
  "page": ""
}

Example 1-30 Navigate to a deeply nested page relative to the application root

To navigate to a deeply nested page relative to the root of the application:

"parameters": {
  "page": "/shell/main/other"
}

Navigation with the flow parameter

The 'flow' parameter can only be the ID of a flow defined below the current page or an empty string.

Example 1-31 Navigate to a specific flow

To change the content of the flow displayed in the current page to the flow main:

"parameters": {
  "flow": "main"
}

Example 1-32 Navigate to a page in a specific flow

To change the content of the flow displayed in the current page to the flow main and navigate to the page other or the flow main:

"parameters": {
  "flow": "main",
  "page": "other"
}

Example 1-33 Navigate to the current page's default flow

To navigate to the current page's default flow:

"parameters": {
  "flow": ""
}

Example 1-34 Navigate the parent flow to a specific flow

To change the parent flow to the flow main:

"parameters": {
  "target": "parent",
  "flow": "main"
}

Example 1-35 Navigate the parent flow to the default flow

To change the parent flow to the default flow:

"parameters": {
  "target": "parent",
  "flow": ""
}

Example 1-36 Navigate to any page in a sibling flow

To change the parent flow to the flow main and navigate to page other in the flow main (note that page can be a path):

"parameters": {
  "target": "parent",
  "flow": "main",
  "page": "other"
}

Navigation with the application parameter

The 'application' parameter can only be the ID of an App UI defined in the current host application or an empty string.

When working with App UIs, the flow to be used is defined by the defaultFlow property in app.JSON.

When the flow is defined, it replaces the App UI's default flow.
When both flow and page are defined, the flow is always applied first; page navigation is relative to the flow.
When only the page is defined, page navigation is relative to the default flow.
When the page is a path, it's considered as being relative to the flow.
When page starts with a backslash (/), it is ignored.

Example 1-37 Navigate to the default flow of a specific App UI

To navigate to the default flow of App UI appUi2:

"parameters": {
  "application": "appUi2"
}

Example 1-38 Navigate to a page in a specific App UI

To navigate to the page other within the default flow in App UI appUi2:

"parameters": {
  "application": "appUi2",
  "page": "other"
}

Example 1-39 Navigate to a deeply nested page in an App UI

To navigate to a deeply nested page next in App UI appUi2:

"parameters": {
  "application": "appUi2",
  "page": "other/main/next"
}

where other is a page within the default flow of appUi2, main is a flow, and next is a page.

Example 1-40 Navigate to a flow in an App UI

To navigate to a flow main in App UI appUi2:

"parameters": {
  "application": "appUi2",
  "flow": "main"
}

When main is a sibling of the default flow, the default flow is replaced with the main flow.

Example 1-41 Navigate to a page in another flow in an App UI

To navigate to a page other in flow main in App UI appUi2:

"parameters": {
  "application": "appUi2",
  "flow": "main",
  "page": "other"
}

Example 1-42 Navigate to the current App UI's root

To navigate to the root of the current App UI (the default page of the current App UI):

"parameters": {
  "application": ''
}

Example 1-43 Navigate to a deeply nested page relative to the current App UI's default flow

To navigate to a deeply nested page next relative to the current App UI's default flow:

"parameters": {
  "application": '',
  "page": "other/main/next"
}

where other is a page in current App UI's default flow, main is a flow, and next is a page.