Navigation Plugin

The navigation plugin manages a stack of views. Only the topmost view is visible. To navigate to a plugin, create the plugin you wish to navigate to and supply it as an argument to navigateToPlugin. To navigate to a url, there are two options. The first is to create a WebViewPlugin, navigate that plugin with your desired navigation calls, and push it onto the stack using navigateToPlugin. The second option is to use the convenience method navigateToUrl which does all of that for you.

When navigating to a web page, the webview plugin automatically transitions to a loading state which is dismissed when the navigation completes. The topmost view will then display the loaded page.

When the navigation plugin navigates to a native plugin view, the native plugin view is immediately visible.

The navigation plugin can coordinate it's behaviour with a header bar plugin. Associating a header bar plugin with a navigation plugin will allow the navigation plugin to update the items in the header bar. The navigation plugin updates the items based on information passed into the header option during calls to the navigate and navigateToPlugin methods. The navigation plugin persists the state of the header bar for each view in the stack. When a view is popped off the stack, the navigation plugin will retrieve the state of the header bar associated with that view and repopulate the associated header bar with the retrieved state.

Sample Usage #

Using the convenience method to navigate to a url:

const navigationView = await NavigationPlugin.init()
const webViewPluginOptions = {
    disableScrollBounce: []
navigationView.navigateToUrl('', {}, webViewPluginOptions)

Creating a WebViewPlugin and navigating to it:

const webView = await WebViewPlugin.init()
const navigationView = await NavigationPlugin.init()

Note: These samples have the same end result with one key difference -- in the first example subsequent navigations will call navigateToUrl and stack new webview plugins, in the second example all navigations will occur in the existing webview plugin (no stacking) and the developer has the option to handle navigations as they wish.

Member Variables

defaultWebViewPluginOptions #

A set of options to be applied to all new WebViewPlugins that are created via this NavigationPlugin. Keys in this object must match methods on WebViewPlugin. The values for this object should be any params required to call the method wrapped in an array.

For example:

navigationView.defaultWebViewPluginOptions = {
    hideScrollBars: [],
    manuallyShowPageForHosts: [['', '']]

Note: In the above example manuallyShowPageForHosts takes a list param hosts, which is why we have a list within a list.

If methods are defined twice in defaultWebViewPluginOptions or if methods that counteract each other are supplied (for example hideScrollBars and showScrollBars), the behaviour is undefined.



NavigationPlugin.init() #

Creates and returns an instance of the navigation plugin that is used to make subsequent method calls.


getLoader() #

Returns the loader instance for this navigation plugin instance.

setLoaderPlugin(loaderPlugin) #

Sets a loader plugin that will be used to provide a loading view that is overlaid when pages are loading.


navigateToUrl(url, options, webViewPluginOptions) #

Convenience method that navigates a web view to the given URL. This will create a new WebViewPlugin, navigate it, and then push it on the navigation stack. Any further navigations within this new WebView will call navigateToUrl and therefore stack by default.

The options structure is as follows:

    header: {
        leftIcon: {
            id: 'back',
            imageUrl: 'file:///back-icon.png'
        centerIcon: {
            id: 'center',
            title: 'Astro'
        rightIcon: {
            id: 'cart',
            pluginAddress: plugin.toMethodArg()

The webViewPluginOptions structure is as follows (related: defaultWebViewPluginOptions):

    hideScrollBars: [],
    navigationHandler: function() {...},
    manuallyShowPageForHosts: [['', '']]

The WebViewPlugin will be created with its disposeWhenPopped flag set to true so that it cleans up after itself when it is popped from the navigation stack.

navigateToPlugin(plugin, options) #

Navigates to the specified plugin.

Note It is the developer's responsibility to clean up plugins after they have been popped from the navigation stack if they are no longer to be used. See WebViewPlugin's disposeWhenPopped.

getTopPlugin #

Returns the top-most plugin on the navigation stack (ie. the currently visible plugin).

popToRoot(options) #

Pops to the root view in the stack of views.

back() #

Navigates back. Pops the current view off of the navigation stack to reveal the previous one.

setHeaderBar(plugin) #

Sets the associated header bar for this NavigationPlugin. The NavigationPlugin will keep the associated header bar's items in sync with the navigation state and will coordinate animations as needed.

disableDefaultNavigationHandler() #

Disables default navigation. Navigation will be canceled after calling this method unless you bind to the navigate event and explicitly call navigateToUrl(url) yourself.

enableDefaultNavigationHandler() #

Enables default navigation. Navigation will be handled automatically. You may still bind to the navigate event to be be notified of navigations.

canGoBack() #

Returns a boolean for whether or not you can go back in the navigation stack.

enableBackGesture() - (iOS only) #

Enables the interactive pop gesture for going back. This is the default. This is a no-op on Android as it is not the expected behaviour called out in the Android design guildelines.

disableBackGesture() - (iOS only) #

Disables the interactive pop gesture for going back. This is a no-op on Android.

setLoaderViewBackgroundColor(options) - (PWA only) #

Sets the background color of the loading view that gets displayed between PWA transitions. The options argument must contain a key 'color' with a valid hex color value.


The following events are triggered by the NavigationPlugin. In addition to these events, all events triggered by all plugins on the stack are also triggered on the navigation plugin. For example, all WebViewPlugin events triggered by any webview plugin on the stack will also be broadcast on the navigation plugin containing it. Subscribers have access to the original triggering plugin via the event paramaters.

Sample usage:

// In this example myCustomWebViewEvent is an event triggered on
// a WebViewPlugin that was pushed onto the navigator and is no
// longer on the top of the stack.
navigator.on('myCustomWebViewEvent', (params) => {
    const sourcePlugin = await navigator.getEventPluginPromise(params)
    // Call a method on the original triggering plugin

back → {url, canGoBack} #

Fires for every back navigation. This typically happens when the user hits Android hardware back button or navigationView.back() is called or, on iOS, the user swipes from the left edge. Note: This event will not get fired if JavaScript calls window.history.back() inside of a webview.

Sample usage:

navigator.on('back', (params) => {
    if (params.url == '') {
        alert('Welcome back home')
    if (!params.canGoBack) {
        alert('You are at the root')

popToRoot → {url} #

Fires when a popToRoot navigation has occurred.

Sample usage:

navigator.on('popToRoot', (params) => {
    if (params.url == '') {
        alert('Welcome back to Mobify\'s home page')
    } else {
        alert('Welcome home')