Controller Reference

Related documents

• Controller Overview
• Storage reference
• Page reference
• App Startup
• State Variables Overview

Table of contents

• Introduction
• Exported identifiers
  • ctl
• ctl methods
  • computeModel()
  • computePage()
  • createPage()
  • doSync()
  • getSavedState()
  • hasPage()
  • onActivityChange()
  • onConnectivityChange()
  • onInit()
  • onResize()
  • page()
  • pages()
  • resetAppValues()
  • restore()
  • save()
  • setSavedState()
  • startApp()
  • sync()
  • translateIds()
  • upgradeSavedState()
• ctl properties
  • appId
  • appTitle
  • appVersion
  • debug
  • deviceType
  • isActive
  • isInitialized
  • isOnline
  • localStorageKey
  • sessionPages
  • Global ctl

Introduction

The Controller is accessed using the ctl object.

Exported identifiers

ctl

Syntax

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

The ctl object contains the properties and methods used to communicate with the Controller.

ctl methods

computeModel()

Syntax

ctl.computeModel()

The Model computations are executed until the Model stabilizes.

computePage()

Syntax

ctl.computePage(pageId)

Compute a specified page. The page's computations are run without first computing the pages that supply its inputs (its precedents). This ensure that the page's computed output state variables are up to date with respect to the page's input state variables.

If a page's computeInfo function makes a change to some state variables that are inputs to to another page compute functions it can call ctl.computePage() to update the associated output state variables immediately.

Parameters

• pageId
  The page ID string for the target page.

createPage()

Syntax

ctl.createPage(info)

Create a page instance. Any methods (except getters or setters) are copied into the returned page instance.

Parameters

• info
  An 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 (required)
      The type string or type of the state variable to be created.
    • id
      The state variables ID. The ID must have 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 has the following signature: fn(io, info).
      • io
        A state variable namespace with all the state variable instances specified by the inputs, outputs, and referenced arrays. It is recommended that the function use the io namespace instead of the global sv namespace to ensure that all the state variables it uses are accounted for in the three state variable arrays. Otherwise, the function may not be executed when a state variable it depends on changes, or an output state variable might not be set to the default value prior to execution. A reference to a state variable that doesn't exist in the io namespace would result in an error.
      • 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.
    • tipInfo
      An array of tip objects (default []). 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, if at least 7 days have passed since the last tip was shown.
      • template
        A Template or string that contains the contents of the tip.
    • Instance methods
      Instance methods for the returned Page instance are copied from the info object. One of either the render() or component() methods is required to be a displayable page.
    • Other methods
      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().

doSync()

Syntax

ctl.doSync()

Full synchronization of the Model and View is done immediately. The Model computations are executed until the Model stabilizes, and then the View is synchronized with the values in the updated state variables.

getSavedState()

Syntax

ctl.getSavedState()

Returns an object with the current app state for use in restoring using ctl.setSavedState().

Return value

An object containing the following properties:

• appId
  The current app ID passed to ctl.startApp()

• devAgent
  The navigator's agent string.

• devPlatform
  The curent platform string from localDevice.platform:

  • Android
  • desktop
  • iPad
  • iPhone

• devProps
  A string containing the following commas separated elements:

  • UI style: 'tab' or 'slide'
  • Native: True is running as a native Cordova app. False if running in a browser.
  • Mobile: True if this is considered a mobile device.
  • Touch: True if this is considered a touch device. False is the device has a mouse or separate touchpad.
  • Viewport: A string with the viewport size in the form ${width}w X ${height}h
  • Missing: A string containing missing environment elements from localDevice.missing

• saveTime
  The JavaScript Date for the time data was saved.

• guid
  The devices GUID from storage.guid. It has the form GUID-<Date.now()>, is created the first time the app is started, and is then restored from the ${appId}_guid key in local storage.

• version
  The current device version string in the form 'X.Y.Z. See versionCompare().

• sVarHistory
  An array of recent changed to saved state variables fron SV.getHistory()

• sVarState
  An object containing the state of all saved state variables obtained bay calling each page's getSavedState method

hasPage()

Syntax

ctl.hasPage(pageId)

Returns true if a page with ID pageId exists. Unlike ctl.page() it does not cause an assertion failure if the page is not found.

Parameters

• pageId
  The page ID string for the target page.

onActivityChange()

Syntax

ctl.onActivityChange(callbackFn)

Calls callbackFn(isActive) when the app transitions between foreground and background processing.

Parameters

• callbackFn
  A function with the signature callbackFn(isActive). The function is called when the app transitions between foreground and background processing. It takes a single argument:
  • isActive
    Trus if the app is now the foreground app.

onConnectivityChange()

Syntax

ctl.onConnectivityChange(callbackFn)

Calls callbackFn(isOnline) when the device connects or disconnects from the Internet.

Parameters

• callbackFn
  A function with the signature callbackFn(isOnline). The function is called when the device connects or disconnects from the Internet. It takes a single argument:
  • isOnline
    Trus if the device is now connected to the Internet and false if disconnected.

onInit()

Syntax

ctl.onInit(callbackFn)

Calls callbackFn() after the controller is initialized. The function can assume:

• The app is fully loaded
• All pages are created and their state variables are restored to the last saved values.
• The Model and View have been synchronized.

If ctl.onInit() is called after the controller is initialized, the function is called after the current thread of execution terminates.

Parameters

• callbackFn
  A function with the signature callbackFn().

onResize()

Syntax

ctl.onResize(callbackFn)

Calls callbackFn() when the viewport is resized.

Parameters

• callbackFn
  A function with the signature callbackFn().

page()

Syntax

ctl.page(pageId)

Returns the page instance whose ID is pageId. Causes an assertion failure if the pageId is not found.

Parameters

• pageId
  The page ID string for the target page.

pages()

Syntax

ctl.pages()

Returns an array of all the page instances.

resetAppValues()

Syntax

ctl.resetAppValues()

Resets every input state variable to its default (using setDflt()), calls setSavedState(null) on every page so that each page can react to the reset, and then schedules a ctl.sync().

restore()

Syntax

ctl.restore(state)

Calling ctl.restore() with no argument causes the Controller to restore the app state from the device storage. If that is not available or the saved values are corrupted, it will reset the application state to default values. If the state parameter is present, it will restore app state from that.

Parameters

• state (optional)
  If provided specifies the app state to restore from. The format is that same a the object returned by getSavedState()

save()

Syntax

ctl.save()

Calling ctl.save() causes the Controller to save the app state to the device storage and, if online, to the server.

The Controller calls ctl.save() itself at the end of every doSync(), but only if some page's hasChanged() reports a change in its saved state variables.

setSavedState()

Syntax

ctl.setSavedState(state)

Set the current application state according to state.

Parameters

• state
  An object containing the application state as returned by ctl.getSavedState().

startApp()

Syntax

ctl.startApp(info)

This is called by the app startup code (usually app.js) to start the Controller. The info object contains the instructions for the controller to set up the app.

Note: The app startup code must also import any modules that contain pages so that they will load. ctl.startApp() installs a window.onload handler that first awaits storage.migrateLegacyLocalStorage() (a failure there never prevents startup) and then initializes the Controller and processes the pages. See App Startup.

Parameters

• info
  An object containing the following properties:
  • id (optional)
    The ID string of this app. The app ID will be used to access the server and as part of the storage key for the device localStorage. If the id is omitted, the title is used by default.
  • template
    The root Template object for the app.
  • title (optional)
    The app title string. This should be the full app title, not the shorter app ID. If omitted, the title defaults to 'My App'.
  • version (optional)
    The app version string in the form 'X.Y.Z'. See versionCompare(). If omitted, the version defaults to '0.0.1'.
  • deviceType (optional)
    A string indicating the type of device the app is running on. One of 'Desktop', 'Phone', or 'Tablet'. Defaults to 'Desktop'.
    • isDebug (optional)
      If true, sets ctl.debug to enable extra debug logging and exception handling. Defaults to true.

sync()

Syntax

ctl.sync()

Schedules a full synchronization of the Model and View. The synchronization is delayed at least until the current thread of execution terminates. Subsequent calls to ctl.sync() have no effect until the synchronization is executed.

translateIds()

Syntax

ctl.translateIds(sVarState, stateVersion, versionTranslations)

Uses the versionTranslations array to map a set of old state variable IDs to new state variable IDs in the sVarState object. The versionTranslations array elements are arrays containing two values:

[version, idTranslations]

The versionString is an app version string (e.g., '2.5.1') that specifies the earliest version that the translated state variable IDs apply to. The translations are only applied if stateVersion is earlier than version. idTranslations is an array containing one to three elements: [from], [from, to] or [from, to, valueFn]. from may be a string or a RegExp. If a string, then the properties in sVarState with key from are renamed to the string in to. If a RegExp, then all the keys in sVarState are explored, and any key matching the RegExp will be renamed to the string using:

key.replace(from, to)

The to string can refer to groupings in the from RegExp. If a valueFn is provided (it is only used when to is given), it is a function that returns a transformed value for the new key. It is called with the old key value and the old key string as arguments. to may be omitted ([from]), in which case the matching key or keys are deleted from sVarState.

For example:

const state = {
	a1: 1,
	a2: 2,
	b: 3,
	c: 4,
};
const translations = [
	['2.0.0', [
		[/^a(\d)$/, 'aa$1'],
		['b', 'bb'],
		['c', 'cc', (v) => v + 1],
	]]
];
ctl.translateIds(state, '1.0.0', translations)

will change state to:

{
	aa1: 1,
	aa2: 2,
	bb: 3,
	cc: 5,
}

Parameters

• sVarState
  An object containing state variable state with the keys being the state variable IDs each with the associated state variables value. See getSavedState().
• stateVersion
  An app version string. See versionCompare().
• versionTranslations
  An array containing the following elements: [version, idTranslations]:
  • version
    A version string specifying the earliest version that the new IDs apply to.
  • idTranslations
    An array containing one to three elements: [from], [from, to] or [from, to, valueFn].
    • from
      A string or RegExp. If a string, the key to be renamed in state. If a RegExp, all keys in state matching from will be renamed using key.replace(from, to).
    • to (optional)
      A string specifying the new key name. If from is a RegExp, then to may refer to groupings in from. If omitted, the matching key or keys are deleted.
    • valueFn (optional)
      A function with the signature valueFn(oldValue, oldKey) that returns a new value for the renamed property. If omitted, the old value is used.

upgradeSavedState()

Syntax

ctl.upgradeSavedState(state)

Upgrades previously saved state to the current version. ctl.upgradeSavedState() calls every page's upgradeSavedState() method passing the state.sVarState and state.version as arguments. If any of the calls return false, the state is considered corrupt.

If the saved data's minor release number (i.e., the first two release numbers) is greater than the current minor release number, then the data is considered incompatible.

Parameters

• state
  An object containing the application state as returned by ctl.getSavedState().

Return value

The method may return any of the following strings:

• 'corrupt'
  The data is not interpretable by the version of the app.
• 'incompatible'
  The data comes from a more recent minor version than the current version of the app. It was possibly saved by an update app on another device.
• 'success'
  The upgrade was successful.

ctl properties

appId

The app ID passed to ctl.startApp()

Value

A string.

appTitle

The app title passed to ctl.startApp()

Value

A string.

appVersion

The app version passed to ctl.startApp(). A short ID for the app used to identify the app in the environment.

Value

A string.

debug

Set to true when extra debug logging and exception handling are required.

Value

A Boolean.

deviceType

The device type passed to ctl.startApp().

Value

A string: 'Desktop', 'Phone' or 'Tablet'.

isActive

True when the app is in the foreground. It starts false and is only set when the first pause, resume, pageshow, pagehide or visibilitychange event arrives.

Value

A Boolean.

isInitialized

True once the Controller's initialization is complete.

Value

A Boolean.

isOnline

True when the device is connected to the Internet.

Value

A Boolean.

localStorageKey

The string ${appId}Input, set by ctl.startApp() from the app ID (the id option, or the title if id is omitted).

Value

A string.

sessionPages

The set of IDs of the pages visited during the current session. It is cleared when a new session starts and reported to the server in the session start marker.

Value

A Set of page ID strings.

Global ctl

The Controller is also available as window.ctl for debugging.