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()
  • basePageIds()
  • help()
  • lockPage()
  • isPopup()
  • popupDone()
  • popupPage()
  • overlayPage()
  • parseRef()
  • refProblem()
  • templateRefs()
  • unlockPage()
• Nav component
• Attributes
• Header and button components

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_selectedPage
  A modelValue state variable containing the page ID of the page at the top of the page stack, including popup and overlay pages. It changes whenever a page is opened or a popup is dismissed. It should be used only for reading; use the nav methods to change pages.
• 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 pages opened per session. The value is a Map. Each key is a page ID, and its value is the number of sessions in which that page has been opened; a page is counted at most once per session. The special key sessionCount holds the number of sessions. A new session starts when more than one hour passes between page openings, and when the app starts. The state variable is saved globally so that the histogram persists across sessions and app instantiations. Its saved state is an array of [key, count] entries (Array.from(map)), which is validated on restore (it must include a numeric sessionCount); an invalid saved state starts a new histogram. The state variable is never reset to a default.

Exported identifiers

nav

Syntax

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

The nav object provides methods and properties to control page navigation. It is also assigned to the global/window object as window.nav for use in debugging.

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: if any are present, the request is ignored and a message is logged. If the navigation is locked to a different page by lockPage(), the request is also silently ignored.

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. This includes popup and overlay pages, so it is not necessarily the base page. It returns the value of the nav_selectedPage state variable.

Return value

A page ID string.

basePageIds()

Syntax

nav.basePageIds()

Returns the IDs of the base pages: every page that the Nav component's layout can select, in layout order, with the pages in groups flattened. These are the pages that open without an argument.

Return value

An array of page ID strings.

help()

Syntax

nav.help(pageId)
nav.help()

Opens the Help page as a popup page with pageId as the help topic. If the help page does not have a topic of that name, the topic selection is left unchanged.

Parameters

• pageId (optional)
  The ID of the page to be the help topic. If omitted, the default is the page ID of the current page, nav.currentPageId().

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.

parseRef()

Syntax

nav.parseRef(ref)

Splits a <Ref> reference string, "pageId" or "pageId.arg", at its first . into a page ID and an argument. The argument is everything after the first ., so it may itself contain . characters.

Parameters

• ref
  The reference string.

Return value

An array [pageId, arg], where arg is undefined if there is none. If ref is empty, an empty array.

refProblem()

Syntax

nav.refProblem(ref)

Returns a description of why a <Ref> reference can't be opened, or an empty string if it can. It checks that the page exists, that the page takes an argument if one is given, and, for the help page, that the help topic exists. Other arguments (such as a procedure or breaker) depend on the aircraft, so the application must check them. It is used to validate help and other text.

Parameters

• ref
  The reference string, "pageId" or "pageId.arg".

Return value

A string: the problem description, or '' if there is no problem.

templateRefs()

Syntax

nav.templateRefs(template)

Returns the page references contained in a template: the ref of each <Ref> or <ClRef> element and the pageId of each <NavPopupButton> element. Only literal string values are found; content that is rendered by a function isn't built until the template is rendered. Templates in the props of elements (such as a Card title) are searched as well.

Parameters

• template
  A Template or an array of them.

Return value

An array of reference strings, "pageId" or "pageId.arg", suitable for refProblem().

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.

If the application does not use the Nav component, it must provide its own navigation using the nav object methods. The Nav component calls nav.basePage() when it renders, to open the locked page, if any, or else the startPage.

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.

Header and button components

The navigation system also provides several small components that pages can use in their own layouts. They are available as tags in templates:

• NavHeaderBar
  The standard navigation header bar used for popup pages and small-screen pages. It renders a div with the CSS class navHeaderBar added to its className, and passes its other attributes to the div. Its children, typically buttons or text, are placed inside.
• NavPopupHeader
  The header bar for a popup page. It has attribute pageId. It renders a NavHeaderBar with the CSS class navPopupHeader that contains a NavDoneButton, the title of the page pageId, and a NavHelpButton. The Nav component displays it automatically when the topmost non-overlay page is a popup page.
• NavHelpButton
  A "Help" button that calls nav.help() to open the help topic for the current page. It is not displayed while the Help page itself is the current page.
• NavDoneButton
  A button that calls nav.popupDone() to dismiss the topmost popup page. Its label is "Done" when there is one popup page on the stack, or "< Back" when popups are stacked on other popups.
• NavPopupButton
  A button that opens a popup page when clicked. It has attribute pageId, the ID of the page to open with nav.popupPage(), which is called with no argument. All other attributes and the children are passed to a Button component.