The Controller is accessed using the ctl object.
ctlimport {ctl} from 'common/mvcs/export.js';
The ctl object contains the properties and methods used to communicate with the Controller.
ctl methodscomputePage()ctl.computePage(pageId)
Compute a specified page. 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.
pageIdcreatePage()ctl.createPage(info)
Create a page instance. Any methods (except getters or setters) are copied into the returned page instance.
infopageIdtitlestateVarInfoinfo structures as passed to the SV type's constructor with the addition of:type (required)idpageId prefix that matches this page’s pageId.computeInfotitleinputsoutputsreferencedio namespace.fn The function to be executed when the computation is triggered. The function is has the following signature: fn(io, info).ioinputs, 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.infoinputsoutputschangedtipInfoidtype'firstTime''anyTime'templateinfo object. One of either the render() or component() methods is required to be a displayable page.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()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()ctl.getSavedState()
Returns an object with the current app state for use in restoring using ctl.setSavedState().
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:
AndroiddesktopiPadiPhonedevProps
A string containing the following commas separated elements:
'tab' or 'slide'${width}w X ${height}hlocalDevice.missingsaveTime
The JavaScript Date for the time data was saved.
guid
The devices GUID from the set_guid state variable. Usually this is derived from Date.getTime() the first time the app is started and then restored from 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
onActivityChange()ctl.onActivityChange(callbackFn)
Calls callbackFn(isActive) when the app transitions between foreground and background processing.
callbackFncallbackFn(isActive). The function is called when the app transitions between foreground and background processing. It takes a single argument:isActiveonConnectivityChange()ctl.onConnectivityChange(callbackFn)
Calls callbackFn(isOnline) when the device connects or disconnects from the Internet.
callbackFncallbackFn(isOnline). The function is called when the device connects or disconnects from the Internet. It takes a single argument:isOnlineonInit()ctl.onInit(callbackFn)
Calls callbackFn() after the controller is initialized. The function can assume:
If ctl.onInit() is called after the controller is initialized, the function is called after the current thread of execution terminates.
callbackFncallbackFn().onResize()ctl.onResize(callbackFn)
Calls callbackFn() when the viewport is resized.
callbackFncallbackFn().page()ctl.page(pageId)
Returns the page instance whose ID is pageId. Causes an assertion failure if the pageId is not found.
pageIdresetAppValues()ctl.resetAppValues()
Resets all the saved state variable values to their defaults.
restore()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.
state (optional)getSavedState()save()ctl.save()
Calling ctl.save() causes the Controller to save the app state to the device storage and, if online, to the server.
setSavedState()ctl.setSavedState(state)
Set the current application state according to state.
statestartApp()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. The Controller will process them when the onload event fires.
infoid (optional)localStorage. If the id is omitted, the title is used by default.templatetitle (optional)'My App'.version (optional)'X.Y.Z'. See versionCompare(). If omitted, the version defaults to '0.0.1'.deviceType (optional)'Desktop', 'Phone', or 'Tablet'. Defaults to 'Desktop'.sync()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()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 two or three elements: [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 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.
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,
}
sVarStategetSavedState().stateVersionversionTranslations[version, idTranslations]:versionidTranslations[from, to] or [from, to, valueFn].fromstate. If a RegExp, all keys in state matching from will be renamed using key.replace(from, to).tofrom is a RegExp, then to may refer to groupings in from.valueFn (optional)valueFn(oldValue, oldKey) that returns a new value for the renamed property. If omitted, the old value is used.upgradeSavedState()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.
stateThe method may return any of the following strings:
'corrupt''incompatible''success'ctl propertiesappIdThe app ID passed to ctl.startApp()
A string.
appTitleThe app title passed to ctl.startApp()
A string.
appVersionThe app version passed to ctl.startApp(). A short ID for the app used to identify the app in the environment.
A string.
debugSet to true when extra debug logging and exception handling are required.
A Boolean.
isActiveTrue when the app is in the foreground.
A Boolean.
isOnlineTrue when the device is connected to the Internet.
A Boolean.