Component Reference

Related documents

• Component Overview
• Built-in Components
• Template Markup Language (TML) Reference

Table of Contents

• Introduction
• Standard Attributes
• Constructor
  • Parent component
  • Component template
  • contextProps
• Class names
• Instance methods
  • currentClassName()
  • didMount()
  • getNodes()
  • render()
  • resize()
  • setClassName()
  • show()
  • sync()
  • willUnmount()
• Protected instance methods
  • buildContents()
  • delete()
  • findComponentsByTag()
  • findComponentsByClassName()
  • findComponents()
  • mount()
  • remount()
  • syncChildren()
  • unmount()
• Instance properties
  • _mon
  • baseClassName
  • children
  • contents
  • contextProps
  • id
  • isVisible
  • node
  • nodes
  • pageId
  • props
  • tag
  • template
• DOM element properties

Introduction

The Component class is intended as a superclass for other components. It implements component instantiation and destruction, and its mounting unmounting in the View. The default methods only need to be overridden when the subclass requires more advanced functionality.

Standard Attributes

Most Components take the following standard attributes:

• className
  A CSS class string. Typically, the className attribute string is combined with the value of any classSv attribute state variable is assigned to the first DOM node within the component instance. However, components are free it do something else or ignore it completely.
• classSv
  A View-type state variable with a value that is a CSS class string. Typically, the value of the classSv attribute state variable combined with the className attribute string is assigned to the first DOM node within the component instance. However, components are free it do something else or ignore it completely.

Constructor

Syntax

new Component(parent, template)

Parameters

• parent
  The parent Component that is creating this node. Set to null if this is the root of a tree.
• template
  A Template object that specifies the instance properties and children.

Parent component

The parent is recorded in the parent property, and this component instance is added to the parent’s children list. A unique ID is generated, and placed in the id instance property.

Component template

The Template object is recorded in the template instance property, and the template’s props object and children array are copied to the props and childTemplates instance properties, respectively, and may be referred to or changed by the other methods. The template’s props and children may be interpreted by the component in any way. It is not required that the component subtree reflects the Template subtree. For example, the children can be used as an XML database.

contextProps

If a contextProps object is present in the parent, it is shallowly copied to the contextProps instance property. If a template.props.contextProps object is present, it is merged over the contextProps instance property. See contextProps in Components Overview.

If template.props.tagNamespace is present, it must be Map of tag strings to Components.
Any tag namespace will added to the stack of tag namespaces used to build the component's subtree.

Class names

The Component superclass makes use of the following properties (copied from template.props):

• baseClassName
  A CSS class string that the component's implementation can set for class names that should always be present in it's nodes.
• props.className
  A CSS class string copied from template.props. Typically, the className attribute string is combined with the value of any classSv attribute state variable.
• props.classSv
  A View-type state variable copied from template.props with a value that is a CSS class string, copied from template.props.

By default, the currentClassName() method returns the combination of the baseClassName, props.className , and the value of the classSv attribute state variable. The default sync() method will use that result to call the setClassName() method whenever the value of the classSv state variable changes. By default, if the first the first content element is a DOM node (i.e., the component directly renders a DOM node) then the setClassName() method will assign the class name to that node. Otherwise, it will call the setClassName() method of the first child component.

Subclass components are free to treat CSS class names any way they choose, including overriding the setClassName() method, the currentClassName() method, the sync() method or completely ignoring CSS class name properties.

Note that a subclass can modify the props.className or baseClassName strings, and this will be reflected in subsequent class name assignments when any props.classSv state variable changes.

Instance methods

currentClassName()

Syntax

currentClassName()

Returns the current class name string. By default, this returns the combination of this.props.className, this.baseClassName, and the current value of any classSv state variable.

Return value

Returns the current class name string.

didMount()

Syntax

didMount()

Called after the render() method returns and the node representing this component are connected to the DOM.
This is a good opportunity to search for and record nodes or components used by the sync() method.
If the component overrides the default method, it should call super.didMount() to inform any child components or otherwise take responsibility for informing them of the mount.

getNodes()

Syntax

getNodes()

Returns an array of DOM nodes that represent the visual implementation of this component.
getNodes() builds the array from the contents array, recursively translating all sub-components into DOM nodes in order.

Return value

An array of DOM nodes that represent the component's DOM layout and are to be connected to an ancestor DOM node.

render()

Syntax

render(template)

Get the layout of the component. Returns a Template object, a string, a number, a DOM node, or an array containing a mix of these types.
Any returned DOM nodes should have all the child nodes from any sub-components attached as children of the node.

Parameters

• template
  A clone of the Template that created this Component.
  The method can use the props and children properties of this object or the props and template.children instance properties created by the constructor.

Return value

A Template object, a string, a number, a DOM node, a Component object, or an array containing a mix of these types.

resize()

Syntax

resize()

Tells a component that the viewport has changed and that it should adjust its layout appropriately.
This can involve calling remount() to recreate the layout from scratch.
The size of the viewport is available by calling view.width() or view.height().
If the component overrides the default method, it should call super.resize() to inform any child components or otherwise take responsibility for informing any child components of the resize event.

setClassName()

Syntax

setClassName(className)

setClassName() is used by the default sync() method to change the DOM className associated with the component, when required.
The default implementation sets the class name of the first DOM node retuned by the getNodes() method.
Override this method in the subclass if a different behavior is more appropriate.
This allows a subclass to change the way the class name is assigned without overriding the sync() method.

Parameters

• className
  A CSS class string to be associated with the component.

show()

Syntax

show(showIt)

The show() method causes the Component to be displayed or hidden depending on the value of showIt.
The DOM nodes associated with the Component are otherwise undisturbed and maintain their internal state, such as scroll offsets.
The state of visibility is reflected by the isVisible property.

Parameters

• showIt
showIt can take the following values:
  • true
    Display the component.
  • false
    Hide the component.
  • 'toggle'
    If the component is hidden, display it. If the component is displayed, hide it.

sync()

Syntax

sync()

Tells a component to synchronize the displayed values with internal state or state variables.
If the component overrides the default method, it should call super.sync() to synchronize any child components and process the classSv monitor or otherwise take responsibility for that.

willUnmount()

Syntax

willUnmount()

Called before unmounting. Tells a component that it is about to be discarded and should remove any event listeners, or any other state outside of the component that uses its DOM nodes.
If the component overrides the default method, it should call super.willUnmont() to inform any child components or otherwise take responsibility for informing any child components of the pending unmount.

Protected instance methods

These methods are tools to be used by subclass instance methods.

buildContents()

Builds an array suitable for the contents property given the results of the render() method.

Note: buildContents() is only used in situations where building, mounting, and unmounting must be done by hand, such as a page navigator or the root of the View.

Syntax

buildContents(template)

Parameters

• template
  A Template object, a string, a number, a DOM node, a Component object, or an array containing a mix of these types.

Return value

An array of Components and/or DOM nodes.

delete()

Syntax

delete(template)

Removes the component from the ID map and deletes it from its parent’s children array.

Note: delete() is only used in situations where building, mounting, and unmounting must be done by hand, such as a page navigator or the root of the View.

findComponentsByTag()

Syntax

findComponentsByTag(tag)

Finds a component in this component’s child subtree by its tag. All components that have the specified tag are returned.

Parameters

• tag
  A tag string or Component class. This must be the same type of tag used to create the component.

Return value

An array of components with the specified tag.

findComponentsByClassName()

Syntax

findComponentsByClassName(className)

Finds a component in this component’s child subtree by its className property.
All components that have the className string in the props.className property are returned.

Parameters

• className
  A CSS class string.

Return value

An array of Components that have the specified class name string in the props.className property.

findComponents()

Syntax

findComponents(fn)

Finds a component in this component’s child subtree using a function. The function is iteratively passed each component in the subtree. All components for which the function returns true are returned.

Parameters

• fn
  A function to execute for each component in the subtree.
  It should return a truthy value to keep the element in the resulting array, and a falsy value otherwise.
  The function is called with the following arguments:
• component
  A component in the subtree.

Return value

An array of components that pass the test. If no elements pass the test, an empty array is returned.

mount()

Syntax

mount()

The mount() method renders the component and builds a contents array, as follows:

• Calls the render() method to get the component's content layout.
• Calls the buildContents() method to transform the result from render() into an array of DOM nodes or Component trees.
• Assigns the results of buildContents() to the contents array.

Note: mount() is only used in situations where building, mounting, and unmounting must be done by hand, such as a page navigator or the root of the View.

remount()

Syntax

remount(fn)

Calling remount() will cause this component instance to be remounted. It does the following:

• Notes the position in an ancestor DOM node of the current DOM nodes associated with this component.
• Calls the unmount() method to discard the child component subtree, remove any nodes hooked to an ancestor node from the ancestor and discard them.
• Calls the mount() method to rerender and rebuild the contents array.
• Calls getNodes() to extract the DOM nodes for this component and reattaches them to the ancestor node at the same place as the previous set of nodes.

syncChildren()

Syntax

syncChildren(fn)

If the component is not hidden, call the sync() method of the direct children of this component.

unmount()

Syntax

unmount(fn)

Unmount the component. The child component subtree will be discarded, and any nodes hooked to an ancestor node will be removed from the ancestor and discarded.

Instance properties

_mon

An object where SvMonitor objects for this component are kept by convention.

Value

An object.

baseClassName

A class name string that is always added to the current class name. See the currentClassName() method.

Value

An string.

children

An array containing the direct child components of this node.

Value

An array.

contents

An array containing the DOM nodes and/or components that comprise the component’s layout.

Value

An array.

contextProps

An object containing properties that are inherited from an ancestor.
See contextProps in Components Overview.

Value

An object.

id

The unique ID for this component instance. Assign this ID as the id attribute of a node in the Component implementation to find the associated component during debugging.

Value

A String.

isVisible

True when the Component is not hidden.

Value

A Boolean.

node

The first node that is returned by the getNodes() method. There will be an assertion failure if there is more than one entry or no entries returned by getNodes().

Value

A DOM node.

nodes

The array of DOM nodes that represent the component's layout. A shorthand for the results of getNodes().

Value

An Array of DOM nodes.

pageId

The pageId string of the Nav page that this Component instance belongs to. If it does not belong to any specific page this value is 'View'.

Value

A String.

props

A shallow copy of the props object from the Template used to create this component.

Value

An Object.

tag

A copy of the tag from the Template used to create this component.

Value

A String or Component.

template

The Template use to create this component.

Value

A Template.

DOM element properties

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.