Page Overview

Related documents

• Page Reference
• Help Page Reference

Table of Contents

• Introduction
• The Nav page
• Page initialization
• Page states
• Model computation
• Help and tips
• Page creation

Introduction

Pages form the bulk of an app. A Page instance contains the following:

• A pageId string that is used for page lookup and navigation.
• A title that is displayed for navigation and Help.
• An array of computations to be run during Model execution.
• A Template or Component to instantiate in the View when the page is open.
• An array of tips. Tips are popup messages that provide helpful hints.
• Help information that is displayed on the Help page when the page is selected as the topic.
• Methods that are called when a page’s state changes or to save and restore page state variables.
• Methods that other pages can call to invoke page actions.

The Nav page

The built-in Nav page is always open and provides the base navigation elements that the user manipulates to open and close pages. The Nav page has a separate nav object that the Controller, View, and other pages use to interact with it. The Nav page manages the page stack, representing a stack of pages from the bottommost to the topmost. 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 Nav page 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 Nav page 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 Nav page (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 page provides standard navigation elements to allow the user to dismiss the 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.

Pages can be opened programmatically by other pages by calling:

• nav.basePage(pageId, arg)
  Opens the page as a base page.
• nav.popupPage(pageId, arg)
  Opens the page as a popup page.
• nav.popupPage(pageId, arg)
  Opens the page as an overlay page.

The base page is always at the bottom of the page stack, so there can only be one base page. When a new base page is opened, the old one is closed. However, the same page can be opened as both a base page and/or one or more popup pages.

When a page opens another page programmatically, it can specify an argument to adjust the target page's state. The argument is passed to the target page's open() method.

Page initialization

A page is usually created by calling ctl.createPage() when its code file is loaded by the app startup code. The app startup code calls ctl.startApp() which usually provides instructions to the Nav page about page navigation layout and which page will be displayed initially.

After the app is fully loaded, the Controller gathers all the created pages and creates and publishes their state variables in the global sv namespace object. It then retrieves any state saved in the device storage and asks each page to upgrade the saved to the current app version using the upgradeSavedState() method. After that, the Controller asks each page to restore its state variables using the setSavedState() method. The default setSavedState() method simply sets the page’s state variables to the values found in the saved state, but the page can override this. For example, examine the state for corruption before setting any state variables.

Once all the page state variables have been restored, the Controller calls each page’s init() method. The page can use this method to do any setup when the app is fully loaded, and all the public state variables are available. Once all the pages are initialized, the Controller runs the Model to set up the app state variables according to the saved state and then initializes the View according to instructions provided to ctl.startApp().

Page states

Pages can be in the following states:

• Closed
  The page is not displayed.
• Opened
  The page is displayed and interactive.
• Deactivated
  The page is displayed but not interactive.

After initialization, each page is in the Closed state. The Nav page automatically opens the initial page by asking the Controller to call the page's open() method. The Nav page does the same for pages selected by the user. After that, the Nav page calls the page’s component() or render() method to provide the Component or Template to build a Component tree that represents the page in the View. The Nav page then instantiates the Component or Template in the DOM.

A page moves back to the Closed state when it is dismissed. The Nav page removes it from the top the stack and calls the page’s close() method to allow it to clean up its state variables for the next instantiation.

A page moved to the Deactivated state when it is opened but is no longer the active page on the top of the stack. Deactivated pages cannot receive user inputs and its input state variables can’t be changed by the user. Their View elements remain in the DOM to preserve DOM state (e.g. scroll offsets), though they may not be displayed when they are completely obscured. When a page is deactivated, the Controller calls its deactivate() method, which returns an object representing the page's current instantiation. If the same page is reopened somewhere above the deactivated instance, the new instance will use the same state variables as the older instance. When the pages above the older instance close, the information returned by the deactivate() method is passed to the page’s reactivate() method to restore the instance state.

Model computation

Each page has an array of computations that are evaluated when the Model is executed. Each computation object specifies a computation function and three arrays containing state variable IDs or state variable objects: inputs, outputs, and referenced. The arrays may reference state variables on other pages.

The inputs array contains the list of state variables that should trigger the computation when any of them have changed (according to each state variable’s change criteria) since the last time the computation was run. The outputs array contains the list of state variables that are reset to their default value before the computation is run. This allows a computation function to return early if an error is detected without having to reset these state variables from previously computed values. The referenced array contains the list of state variables that are used by the computation function but don’t trigger the computation and should not be reset before the computation is executed. All the state variable instances contained in the three arrays are added to the io namespace which is passed to the computation function. Using this namespace instead of the global sv namespace to access state variables within the function will cause a reference error if the state variable is not present in any of the three arrays. This will help ensure that all state variables used by the function are accounted for.

In each cycle of Model execution, each page’s array of computations is evaluated in order, and any triggered computations are executed. In general, it’s better to ensure that individual computations that depend on the output of other computations are placed after those computations in the array. In addition, The Model attempts to order page evaluation so that pages that provide outputs to a page are evaluated before that page. However, cycles are allowed, and the Model will repeat evaluating all pages until all inputs are unchanged since the last time their dependent computation was evaluated. If the Model runs an excessive number of cycles, it will terminate with an assertion failure.

Help and tips

If desired, each page can have its own help topic by providing a renderHelp() method. The renderHelp() method returns a template containing the page help information. The help topic will be the page's title. A page can also provide additional help topics by calling help.addTopic() (see Help Page Reference).

A page can also have tips. Tips are popup messages that provide helpful hints. Some tips are displayed the first time a page is opened and others are displayed when a page is opened sometime later. For the latter type, tips display is throttled to minimize annoyance. An individual tip is only displayed once, but they are always available at the end of the page’s help page. See Page Reference.

Page creation

Pages are created by calling ctl.createPage(info). The info object contains the following properties:

• pageId
  The page’s ID. Used to look up pages or control navigation.
• title
  The page’s title is displayed by the built-in navigation.
• stateVarInfo
  An array of StateVar info structures as passed to the SV type's constructor with the addition of:
  • type
    The type string or type of the state variable to be created. All created state variables must have an ID with a pageId prefix that matches this Page’s pageId.
• computeInfo
  An array of objects specifying computations to be run when the Model is executed. Each object contains the following properties:

  • title
    The title of the computation. This is only used for logging the executed computations.

  • inputs
    An array of state variable ID strings or state variable instances that specifies the state variables that will trigger execution of this computation when any one of them has changed (using the state variable’s change criteria).

  • outputs
    An array of state variable ID strings or state variable instances that specifies the state variables that will be set to default before this computation is executed.

  • referenced
    An array of state variable ID strings or state variable instances that are referenced in the computation, but neither trigger the computation nor should they be reset to default values. However, they are used within the function and should appear in the io namespace.

  • fn The function to be executed when the computation is triggered. The function is passed two arguments:

    • io
      A state variable namespace with all the state variable instances specified by the inputs, outputs, and referenced arrays.
    • info
      An object containing the following properties:
      • inputs
        An array of input state variable instances.
      • outputs
        An array of output state variable instances
      • changed
        An array of input state variable instances that have changed with respect to the last time the computation was run.

  • render()
    Returns a Template, a string, a number, or an array of them that represent the contents of the page when opened.

    • tipInfo
      An object containing keys that each represent an ID for a tip. Each tip object contains the following properties:
      • id
        An ID string for this tip. The ID is used to record which tips have been displayed.
      • type
        A string indicating when the tip should be displayed. Tips are displayed as popup messages only once:
        • 'firstTime'
          Display the tip the first time the page is opened.
        • 'anyTime'
          Display the tip when the page is opened at a random time.
      • template
        A Template or string that contains the contents of the tip.
    • renderHelp()
      Returns a Template, a string, or an array of Templates and/or strings that represent the help information displayed when the page is selected as the help topic.

    The info object may also contain other methods that other pages can use to interact with the page. These are transferred to the Page object. For example:
    ctl.page('myPageId').myMethod().