View Reference

Related documents

• Template Reference
• Template Markup Language (TML) Reference

Table of contents

• Introduction
• Standard colors
• Device size classes
• Exported identifiers
  • view
• view methods
  • appendNodes()
  • createNode()
  • defineComponentTag()
  • doSync()
  • getComponentById()
  • getComponentClass()
  • resize()
  • setSizeClass()
  • sync()
  • toText()
• view properties
  • bottom
  • hasSafeArea
  • 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.

These properties are adjusted when switching between dark mode and light mode. The application should use these properties when appropriate.

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 < 512, 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:

• viewSize-medium
• viewSizeGE-medium
• viewSizeGE-small
• devsizeLT-large

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.

view methods

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. 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 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.

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 setSizeClass() method will set a series of CSS class strings of the form prefix-sizeClass. The sizeCLass is one of the size class strings and the prefix is one of:

• viewSize-
  The current viewport size class. CSS can use this class for styles that are specific to the size class. For example, a viewSize-medium 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 in px.

Value

A number.

hasSafeArea

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

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 in px.

Value

A number.

right

The viewport offset from the right of the screen in px.

Value

A number.

top

The viewport offset from the top of the screen in px.

Value

A number.

width

The viewport width in px.

Value

A number.