Navigation System Reference

Related documents

• Controller Overview
• Page Overview
• Controller Reference
• Page Reference
• View Reference
• Component Reference
• Help Page Reference

Table of Contents

• Introduction
  • Page types
  • Navigation styles
  • Dark mode
  • Initialization
• nav page state variables
  • Page histogram
• Exported identifiers
  • nav
• nav object methods
  • basePage()
  • currentPageId()
  • help()
  • lockPage()
  • isPopup()
  • popupDone()
  • popupPage()
  • overlayPage()
  • unlockPage()
• Nav component
• Attributes

Introduction

The MVCS page navigation system consists of three parts: a nav object, a nav controller page, and a Nav Component. The nav object provides methods and properties to control page navigation, the nav page provides state variables and Model computations in support of page navigation, and the Nav Component provides the navigation "chrome" and an area to display the selected page.

Page types

The navigation system manages a page stack, representing a stack of pages from the bottommost to the topmost. All the pages on the stack remain open, but only the topmost one is active. See Page Overview for a description of page open and active states. There are three types of pages:

• Base
  The base page is the bottommost page on the page stack. The base page does not overlay any other page. The navigation system provides navigation elements (tabs or a slide-in menu) to allow the user to select among the available base pages. Base pages are normally opened only by the navigation system in response to user actions.

• Popup
  Popup pages completely cover base pages or other popup pages. Pages beneath it are not visible. Popup pages can be requested by the navigation system (e.g., the Help page) or by the currently active page at the top of the stack. When a popup page is requested, the current page is deactivated, and the popup is pushed onto the top of the page stack and then opened. The Nav Component provides standard navigation elements to allow the user to dismiss the popup page. When a popup page is dismissed, it is removed from the stack, and the topmost page is reactivated.

• Overlay
  Overlay pages are a type of popup page that may not completely cover other pages. Unobscured pages beneath the overlay page remain visible. The Nav page does not provide standard navigation elements for overlay pages. Instead, the page must provide a means for the user to dismiss it. The built-in dialog page is an example of an overlay page.

It is possible for the same page to appear more than once in the stack as one or more popup pages or as a base page and popup pages. Overlay pages typically appear only at the top of the stack.

Navigation styles

The navigation system supports two styles of base page navigation:

• slide
  The page selection menu slides in from the left. The top of the viewport has a header bar with a menu button that makes the slide-in menu appear. The slide-in menu also has a similar button to make the slide disappear. The slide menu allows pages to be grouped. Selecting a group name makes the grouped pages appear in an accordion style. This style is best for narrow devices like phones or narrow desktop windows.
• tab
  A menu bar contains tabs for page selection. Pages can be grouped under a tab. When a group tab is selected, a dropdown menu with the group contents appears. This style is best for wider viewports like large desktop windows or tablets. The menu bar can appear at the top of the viewport or bottom of the viewport. The latter allows page selection on tablets without having the user's hand obscure the display.

Navigation style is controlled by setting the value of the nav_style state variable. The position of the tab is controlled by setting the value of the nav_tabFooter state variable.

Dark mode

The normal presentation style is a dark font color on a light background. If the nav_darkMode state variable value is true, then the presentation is a light font color on a dark background.

Initialization

When the application starts up, it specifies the navigation layout by calling ctl.startApp(info). The info.template property includes the Nav component. The Nav component's attributes set the menu layout and initial starting page. Note that it's possible for the application to not use the Nav component, in which case it must provide its own navigation. For example:

ctl.startApp({
	deviceType: deviceType(),
	title: 'Example 1',
	id: 'Example1',
	template: tml`<Nav layout=${['adder', 'set']} startPage=adder />`
});

nav page state variables

The nav page provides several state variables that other pages can use to control nav page characteristics or to trigger Model or View actions:

• nav_darkMode
  A booleanInput state variable. If nav_darkMode is true, then the displayed output will be in dark mode (light on dark), and the root node will have the CSS class darkMode.
• nav_online
  A modelValue state variable. If nav_online is true, then the device is online. This is useful as a trigger for model computations.
• nav_tabFooter
  A booleanInput state variable. When nav_tabFooter is true and the nav_style state variable is set to 'tab', then the tab bar is displayed at the bottom of the screen and the root node will have the CSS class tabFooter.
• nav_style
  A modelValue state variable that sets the current navigation style. The navigation style can be one of:
  • 'slide'
    Slide in menu navigation for narrow devices. The root node will have the CSS class slide.
  • 'tab'
    Tabbed navigation for wide devices with a mouse or trackpad. The root node will have the CSS class tab.

Page histogram

The nav page maintains a special state variable, nav_pageHistogram, that contains a histogram of page opened per session.

Exported identifiers

nav

Syntax

import {nav} from 'common/mvcs/export.js';

The nav object provides methods and properties to control page navigation.

nav object methods

The nav object contains both methods and data properties to control navigation. The methods are:

basePage()

Syntax

nav.basePage(pageId, arg)

Open pageId as a base page that replaces the current base page. The arg parameter is passed to the page's open() method. This must only be called when there are no popup or overlay pages.

Parameters

• pageId
  The ID of the page to be opened.
• arg
  The argument value to passed to the page's open() method.

currentPageId()

Syntax

nav.currentPageId()`

Returns the page ID of the currently active page on top of the page stack.

Return value

A page ID string.

help()

Syntax

nav.help(pageId)

Opens the Help page as a popup page with pageId as the help topic.

Parameters

• pageId
  The ID of the page to be the help topic.

lockPage()

Syntax

nav.lockPage(pageId)

The lockPage() method opens pageId as a base page and locks the navigation so that the base page can't change. This is used to lock the Terms of Use page until it is acknowledged. The lock is released by the the unlockPage() method

Parameters

• pageId
  The ID of the page to be opened and locked.

isPopup()

Syntax

nav.isPopup()

nav.isPopup() returns true if the current top page is a popup or overlay page. It returns false if the current page is a base page. It is possible for the same page to be on the page stack more than once and this method can help distinguish pages invoked as a popup page versus as a base page.

Return value

A boolean value.

popupDone()

Syntax

nav.popupDone()

Closes the current top popup or overlay page. This must only be called whent here is a popup page on the page stack. On normal popup pages popupDone() is called automatically when the user clicks the "Done" button. On overlay pages, the page must call popupDone() when the the page is dismissed.

popupPage()

Syntax

nav.popupPage(pageId, arg)

Open pageId as a popup page. The arg parameter is passed to the page's open() method.

Parameters

• pageId
  The ID of the page to be opened.
• arg
  The argument value to passed to the page's open() method.

overlayPage()

Syntax

nav.overlayPage(pageId, arg)

Open pageId as an overlay page. The arg parameter is passed to the page's open() method.

Parameters

• pageId
  The ID of the page to be opened.
• arg
  The argument value to passed to the page's open() method.

unlockPage()

Syntax

nav.unlockPage()

The unlockPage() method clears the page lock initiated by the lockPage() method. It releases the lock and resets the base page to the previous value or the starting page. This is used to unlock the Terms of Use page when it is acknowledged.

Nav component

Syntax

tml`
	<Nav startPage=myStartPageId layout=myPageLayout />
`

The Nav component provides the View infrastructure for standard MVCS page navigation. It displays the "chrome" that provides navigation elements and an area to display selected pages.

The layout attribute is an array that contains the page ID strings of the menu. The array can also contain an object that contains a group title and another sub-array of page IDs in the group. The layout is used to set the tab or slide-in menus. The startPage attribute sets the initially selected page.

Note that it is possible for the application

Attributes

• layout (required)
  An array specifying the menu layout. The array contains either page ID strings or objects representing a group of sub-pages. A group object contains two properties:
  • title
    A string containing the title of the group that will be displayed in the tab or list item.
  • subPages
    An array of page ID strings of the pages in the group.
• startPage (required)
  The page ID of a page in the layout that will be the page displayed initially. This may be overridden during page initialization. For example, a Terms of Use page can request that it should be displayed initially and locked by calling the nav.lockPage() method if the terms of use have not been agreed to yet.