Component ReferenceThe 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.
Most Components take the following standard attributes:
classNameclassName 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.classSvclassSv 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.new Component(parent, template)
parenttemplateThe parent is recorded in the parent property, and this component instance is added to the parent’s children list. The id instance property is set to props.id if present, otherwise a unique ID is generated from the ID prefix and a counter. The ID prefix is contextProps.idPrefix if present, otherwise the pageId. The component is registered in the view's ID map.
The Template object is recorded in the template instance property, and the template’s props object is copied to the props instance property, and may be referred to or changed by the other methods. The template’s children are not copied: the children instance property is the array of child Components (initially empty), so use this.template.children or the template argument of render() to get the child templates. 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.
contextPropsIf 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.
The Component superclass makes use of the following properties (copied from template.props):
baseClassNameprops.classNametemplate.props. Typically, the className attribute string is combined with the value of any classSv attribute state variable.props.classSvtemplate.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.
currentClassName()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.
Returns the current class name string.
didMount()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()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.
An array of DOM nodes that represent the component's DOM layout and are to be connected to an ancestor DOM node.
render()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.
templateprops and children properties of this object or the props and template.children instance properties.A Template object, a string, a number, a DOM node, a Component object, or an array containing a mix of these types.
resize()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()setClassName(className)
setClassName() is used by the default sync() method to change the DOM className associated with the component, when required.
The default implementation ORs baseClassName into the passed class name, then assigns it to the first content element if that is a DOM node, otherwise it calls setClassName() of the first child component.
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.
classNameshow()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.
showItshowIt can take the following values:truefalse'toggle'sync()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()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.
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.
buildContents(template)
templateAn array of Components and/or DOM nodes.
delete()delete()
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.
findComponentById()findComponentById(id)
Finds a component in this component’s child subtree by its id property.
idThe first matching component in depth-first order, or undefined if there is none.
findComponentsByTag()findComponentsByTag(tag)
Finds a component in this component’s child subtree by its tag. All components that have the specified tag are returned.
tagtag using strict equality, so it must be the same type of tag used to create the component.An array of components with the specified tag.
findComponentsByClassName()findComponentsByClassName(className)
Finds a component in this component’s child subtree by its class name.
All components that have the class name(s) in the result of their currentClassName() method (props.className, baseClassName and the current classSv value) are returned.
classNameAn array of Components that have the specified class name.
findComponents()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.
fncomponentAn array of components that pass the test. If no elements pass the test, an empty array is returned.
mount()mount()
The mount() method renders the component and builds a contents array, as follows:
render() method to get the component's content layout.buildContents() method to transform the result from render() into an array of DOM nodes or Component trees.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()remount()
Calling remount() will cause this component instance to be remounted. It does the following:
_mon monitors, so they report a change on the next sync().didMount() on the new subtree, then sync().syncChildren()syncChildren()
If the component is not hidden, call the sync() method of the direct children of this component.
unmount()unmount()
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.
_monAn object where SvMonitor objects for this component are kept by convention.
An object.
baseClassNameA class name string that is always added to the current class name. See the currentClassName() method.
An string.
childrenAn array containing the direct child components of this node.
An array.
contentsAn array containing the DOM nodes and/or components that comprise the component’s layout.
An array.
contextPropsAn object containing properties that are inherited from an ancestor.
See contextProps in Components Overview.
An object.
idThe 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.
A String.
isVisibleTrue when the Component and all of its ancestors are not hidden.
A Boolean.
nodeThe single DOM node that represents this component. There will be an assertion failure unless the contents array has exactly one entry. If that entry is a child component, its first node is returned.
A DOM node.
nodesThe array of DOM nodes that represent the component's layout. A shorthand for the results of getNodes().
An Array of DOM nodes.
pageIdThe 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'.
A String.
propsA shallow copy of the props object from the Template used to create this component.
An Object.
tagA copy of the tag from the Template used to create this component.
A String or Component.
templateThe Template use to create this component.
A Template.
Component.getNodes()Component.getNodes(contents)
Returns a flat array of the DOM nodes for an array of contents (DOM nodes and/or Components), recursively resolving each child component to its nodes. Used by getNodes() and by components that build their own DOM nodes from the results of buildContents().
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.