View Reference

Related documents

• Template Reference
• Template Markup Language (TML) Reference

Table of contents

• Introduction
• Standard colors
• Utility CSS classes
• Device size classes
• Exported identifiers
  • view
• view methods
  • addRootComponent()
  • appendNodes()
  • createNode()
  • defineComponentTag()
  • doSync()
  • getComponentById()
  • getComponentClass()
  • init()
  • resize()
  • setSizeClass()
  • sync()
  • toText()
• view properties
  • bottom
  • hasSafeArea
  • isInitialized
  • rootNode
  • height
  • left
  • right
  • top
  • width

Introduction

The View is accessed using the view object. The view restricts the viewport to be within the "safe area": A rectangular area that does not include any cutouts for cameras or other devices.

The view attaches to a DOM node with an ID of root. This must be defined in the app's index.html file before the view is initialized.

Standard colors

The View defines the following custom properties:

• --main-text-color
  The main text color.
• --main-text-warning-color
  The text color for warnings.
• --main-text-caution-color
  The text color for cautions.
• --main-text-bg-color
  The main text background color.
• --main-text-color-sel
  The main text color for selected elements.
• --main-text-bg-color-sel
  The main text bg color for selected elements.
• --main-fill-color
  The fill color for unused areas.
• --main-input-color
  The main text color for inputs.
• --main-input-bg-color
  The main text background color for inputs.
• --main-input-border-color
  The main border color of inputs.
• --main-output-color
  The main text color for outputs.
• --main-disabledInput-color
  The main text color for disabled inputs.
• --main-disabledInput-bgColor
  The main background color for disabled inputs.
• --main-wrapper-haze
  The semi-transparent haze over background content.
• --main-button-text-color
  The main button text color.
• --main-button-text-bg-color
  The main button text background color.
• --main-dialog-border-color
  The main border color for dialogs.
• --main-list-border-color
  The main border color for list items.
• --rounded-corner-buffer
  The buffer used to keep content clear of rounded device corners (iPhone).

These properties are adjusted when switching between dark mode and light mode: the .darkMode CSS class overrides the text, background, fill, input, output, disabled-input, and haze colors. The application should use these properties when appropriate.

Utility CSS classes

view.css also defines the following classes and rules:

• .warningColor, .warning: Text in the warning color.
• .cautionColor, .caution: Text in the caution color.
• .okColor, .ok: Text in green.
• .input: Gives an element the border and padding of an input.
• .input-disabled: Gives an element the disabled input colors.
• .inputButton: A small button floated to the right of an input.
• #root safe-area padding: #root is padded by the device's safe-area insets (constant() before iOS 11.2, env() after).
• .nativeAndroid #root: Removes the #root padding because the native Android WebView is already inside the safe area. The app sets the nativeAndroid class on the html element in its app.js.
• Base font size: #root has a font size of min(calc(10px + 0.7vmin), 17px), which an app may override in its app.js.

Device size classes

The application can choose a set of device size breakpoints to use in its CSS. A size class is associated with each range of sizes between the breakpoints. For example, if the breakpoints are viewport widths of 512 and 1024 then the class large can be associated with widths ≥ 1024, the class medium can be associated with widths ≥ 512 and < 1024, and the class small can be associated with widths < 512.

Once the size classes are defined, the view can set up useful class strings. For example, if the device size is medium, then the view can set up the following CSS classes in the root node:

• viewSizemedium
• viewSizeGE-medium
• viewSizeGE-small
• viewSizeLT-large

Note that the current-size class has no hyphen: it is viewSize followed directly by the size class name. See the view.setSizeClass() method.

Exported identifiers

view

Syntax

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

The view object contains the properties and methods used to communicate with the View. It is also available as the global window.view for debugging.

view methods

addRootComponent()

Syntax

view.addRootComponent(componentOrTemplate)

Adds a Component class or a Template object to the root. A Component class is wrapped in a Template. Anything else must be a Template object, not a string or an array. Fails an assertion if called after view.init().

Parameters

• componentOrTemplate
  A Component class or a Template object.

appendNodes()

Syntax

view.appendNodes(parent, nodes)

Appends child DOM nodes to a parent DOM node. The nodes array will be flattened and compacted. Elements may be strings or DOM nodes. If an element is a string, it is converted to a DOM test node after having any custom character entities processed (See Character Entities).

Parameters

• parent
  The DOM node to append child nodes to.
• nodes
  An array of DOM nodes and/or strings and other arrays of DOM nodes and/or strings.

createNode()

Syntax

view.createNode(tag, props, children)

Returns a DOM node with the specified properties and children. Each property is assigned as a DOM property on the node (not set as an HTML attribute). Properties starting with 'data-' are set as node data properties. The following attributes are converted to their equivalent DOM properties:

• class is converted to className
• rowspan is converted to rowSpan
• colspan is converted to colSpan

Parameters

• tag
  The node tag string.
• props (optional)
  An object whose properties are used to set the node's properties.
• children (optional)
  An array of DOM nodes and/or strings (strings become text nodes), or a string. If an array, the nodes are set as the new DOM nodes children using view.appenNodes(). If a string, it is used to set the node's innerHTML property.

defineComponentTag()

Syntax

view.defineComponentTag(tag, component)

Associate a component tag string with its Component subclass. Once defined, the tag may be used in TML strings. Otherwise, the TML template would have to import and refer to the component itself.

Parameters

• tag
  The tag string to associate with the Component
• component
  A Component class.

doSync()

Syntax

view.doSync()

Synchronize the entire view from the root. Calls the sync() method on the root Component. This will traverse the Component tree calling the sync() method as required to cause the Components to update the displayed elements to the current state variable state.

Unlike view.sync(), this synchronizes the View immediately.

getComponentById()

Syntax

view.getComponentById(id)

Return the component given the ID.

Most Components generate DOM elements containing the Component ID in the data-cid attribute. Use this ID with view.getComponentById() in the debugger console to explore the Component controlling the DOM element.

Return value

A Component.

getComponentClass()

Syntax

view.getComponentClass(tag)

Return the component class for a given component tag string. See defineComponentTag()

Parameters

• tag
  A tag string.

Return value

A Component.

init()

Syntax

view.init()

Initializes the entire View. Called at device ready. Builds the Component tree from the root components added with view.addRootComponent(), mounts it on the root node, and synchronizes it. Asserts that at least one root component has been added. Sets view.isInitialized to true.

resize()

Syntax

view.resize()

Notify the entire View that the viewport has been resized.

setSizeClass()

Syntax

view.setSizeClass(curSizeClass, sizeClasses)

Sets the size class CSS strings in the root node. The sizeClasses parameter is an array of the possible size class strings ordered from largest to smallest. The curSizeClass is the viewport's current size class. The method first removes any existing root node classes beginning with viewSize, then sets a series of CSS class strings of the form prefixsizeClass. It fails an assertion if curSizeClass is not in sizeClasses. The sizeClass is one of the size class strings and the prefix is one of:

• viewSize (no hyphen)
  The current viewport size class. CSS can use this class for styles that are specific to the size class. For example, a viewSizemedium CSS class would apply only when the viewport size falls into the medium size class.
• viewSizeLT-
  The current viewport size is smaller than the specified size class. CSS can use this class for styles that are specific to all size classes that are smaller than the size class. For example, a viewSizeLT-medium CSS class would apply only when the viewport size is smaller than medium.
• viewSizeGE-
  The current viewport size is equal to or larger than the specified size class. CSS can use this class for styles that are specific to all size classes are larger than or equal to the size class. For example, a viewSizeGE-medium CSS class would apply only when the viewport size is medium or larger.

Parameters

• curSizeClass
  The size class string that the application has determined represents the current viewport size.
• sizeClasses
  An array of application size classes from largest to smallest.

sync()

Syntax

view.sync()

Schedule a synchronization of the entire View. This can be called multiple times and the synchronization, using view.doSync()).

toText()

Syntax

view.toText(template)

Extracts the text from anything that the view accepts as a template (strings, arrays or templates).

Parameters

• template
  A string, array, or Template object to extract text from.

view properties

bottom

The viewport offset from the bottom of the screen, as the computed style value of the root node.

Value

A string including units, for example '0px'.

hasSafeArea

True if the device's viewport has a "safe area": A rectangular area that excludes any intrusions on the viewport.

Value

A Boolean.

isInitialized

True once view.init() has completed.

Value

A Boolean.

rootNode

The current root DOM node of the View.

Value

A DOM node

height

The viewport height in px.

Value

A number

left

The viewport offset from the left of the screen, as the computed style value of the root node.

Value

A string including units, for example '0px'.

right

The viewport offset from the right of the screen, as the computed style value of the root node.

Value

A string including units, for example '0px'.

top

The viewport offset from the top of the screen, as the computed style value of the root node.

Value

A string including units, for example '0px'.

width

The viewport width in px.

Value

A number.