CalDOM 1.0.7 Documentation

(Optional) "+tag" creates a new Element.

'<tag></tag>' creates specified HTML structure. "~svg_tag" creates a SVG element.

Otherwise, it can be a CSS Selector, an XPath query starting with "$", a CalDom instance, a single Node/Element, an array of Nodes or a NodeList/HTMLCollection.

(Optional) Child elements to be passed into append(). Can be CalDOM/Node/String or an array of them. See append() for all possibilities.

This might be useful for code-clarity at render() function for reactive components. See examples at react().

(Optional) parent_window default to current window. Use this to work with iframes or external windows.

CSS Selector to find or XPath query starting with "$"

Can be a zero-based index or a minus(-i) index from end (Eg: -1 returns last element)

(Optional) Default is immediate parent. If a number is given, n-th parent is returned (zero-based). If a string is given, first parent(s) to match the CSS selector is returned.

(Optional) CSS selector to match

Function to callback. Callback is called with 2 arguments: callback(elem: Node, index: Number). The enumeration stops if the callback returns false.

Function to callback. Callback is called with 2 arguments: callback(elem: Node, index: Number).

(Optional) A HTML string or an array of HTML strings to set at corresponding n-th element.

If not given, an array of innerHTML for all elements in this CalDom instance is returned.

(Optional) Text or an array of text to set at corresponding n-th element.

If not given, an array of textContent is returned.

(Optional) Value or array of values to to be set at corresponding n-th element.

If not given, array of values will be returned.

Attribute name as a String or { key: value, ... } object to set multiple attributes

(Optional) Value or array of values to be assigned at corresponding n-th element.

If not given, an array of attribute values for the given key is returned.

Variable name as a String or { key: value, ... } object to set multiple variables.

(Optional) Value or an array of values to be to be assigned at the corresponding n-th element. If empty, an array of given key's values is returned.

Can be any javascript Object, usually a string.

(Optional) Can be any javascript Object or an array of Objects to be to be assigned at the corresponding n-th element.

CSS property name or { property: value, ... } object to set multiple rules

CSS value or an array of values to be set at n-th element for the given CSS property name.

A single class name or multiple class names separated by spaces or as an array.

A single class name or multiple class names separated by spaces or as an array.

(optional) Display value. Default to "block"

A single event name or multiple event names separated by spaces or as an array.

Callback function to handle the event.

(Optional) options to pass into addEventListener's 3rd param.

A single event name or multiple event names separated by spaces or as an array.

Callback. The same callback provided at on() or Node.addEventListener() should be provided.

(Optional) options to pass into removeEventListener's 3rd param.

First argument can be a CalDom instance, a Node/String or an array of Node/String.

Provided elements are added to the first element of this CalDom instance. This is XSS safe as it's considering String inputs as a text node. Use .html() or init _("<h1></h1>") to inject HTML.

See the examples for wide range of possibilities.

(Optional) If the first argument is not an array-type, all ...arguments are added to the first element of this CalDom instance.

First argument can be a CalDom instance, a Node/String or an array of Node/String.

Items are prepended to the first element of this CalDom instance. This is XSS safe as it's considering String inputs as a text node. Use .html() or init _("<h1></h1>") to inject HTML.

(Optional) If provided, items are inserted before this element instead before the firstChild.

Render function that returns the new replacement element.

The callback receieves 3 parameters: render_callback( current_elem: Node, index: Number, caldom_instance: CalDom ): {Node || CalDom}

(Optional, but requires to initiate) Any value or an { key: value, ... } object.

(Optional, but requires to initiate) Reactive configuration containing render(), update(), etc.

(Optional, if update() is given) Should return a CalDom or a Node/Element. Return false to terminate render process.

render(state: any, component: CalDom): receieves state and component(this CalDom instance) as arguments.

All CalDom methods & properties (find(), text(), css(), etc.) can be accessed via component. Eg: component.text("Hello World!").

CalDom sync child nodes (including text), attributes, CSS, value, checked, indeterminate, selected & _data property set by .data() between connected DOM & virtual DOM. It doesn't sync changed events & other custom properties directly attached to DOM nodes.

To force a complete Node replacement with all events and properties, set a different/incremental "caldom-v" attribute to the element at render() ("v" as in version of the element).

The first render() gets executed synchronously. After that, render() gets executed asynchronously through requestAnimationFrame when the state changes. This is asynchronous in both watched = true mode or when react() is called manually.

Calling react() with a brand new state execute render() synchronously. Eg: app.react( new_state );

(Optional, if render() is given) If an update() function is present, CalDom will execute it instead of render(). (Intial render() get executed regardless).

Manually updating DOM changes directly by accessing the native DOM API is obviously more performant than a render() based virtual-DOM approach. Set this.$ references at render() to access the native Nodes directly. Refer this.$ below for details.

Also, update() is useful to update existing non-javascript originated(.html file based) HTML structures reactively.

If the update() returns true, CalDom will also execute render() and proceed with virtual-real DOM comparison and apply subsequent changes.

update(

 state: any,

 component: CalDom,

 state_changed_keys: Object,

 state_change_count: Number

);

Arguments are state, component(this CalDom instance) and batched and changed state key names & change count since the last render()/update().

state_changed_keys & state_change_count is useful to do select direct DOM changes or fall back to render() by returning true if the changes are complex.

state_changed_keys is an Object. Eg: { key_name: String, value_is_available: Boolean }. If the state change is a deletion, value_is_available is set to false.

state_changed_keys is one-dimentional. If the same key_name is used more than once at deeper levels of state object, only the last key-value change is represented here. Use this.state for deeper analysis.

If the same key change multiple times, state_change_count is increased accordingly. state_changed_keys & state_change_count are only populated in watched = true mode.

All CalDom methods & properties (find(), text(), css(), etc,) can be accessed via component. Eg: component.css( "color", "green" )

(Optional) True by default. If false, CalDom will not react to state changes automatically. Call react() manually after changing state.

CalDom is using Javascript Proxies to detect state changes. Browser versions released before 2016 may not support it natively. Implement a pollyfil for older browsers or you can call react() manually after state changes.

(Note that Proxy pollyfils require variable to be defined in advance.)

If Proxy is not supported caldom.watched will set to false despite initially setting config.watched = true.

If you chose not to use the Proxy for some reason, you can call .react() after state changes. There is no performance hit by calling it repetedly because CalDom is using requestAnimationFrame to batch DOM updates efficiently.

Also, calling react() manually immediately after state changes does not cause a re-render even when Proxy is supported.

(Optional) Called before the Component is mounted(appended) into a parent Node. Receives current CalDom instance as the only argument.

(Optional) Called after the Component is mounted(appended) into a parent Node. Receives current CalDom instance as the only argument.

(Optional) Called before the Component is removed.

Callback receives two argument as callback( component: CalDom, [directly_removed: Boolean] ). directly_removed is set to true if removed directly by calling .remove().

Otherwise, set to undefined if removed while applying virtual-DOM changes to the real DOM. The removed component might get re-connected at a different position in the DOM tree.

(Optional) Called after the Component is removed.

Callback receives two argument as callback( component: CalDom, [directly_removed: Boolean] ). directly_removed is set to true if removed directly by calling .remove().

Otherwise, set to undefined if removed while applying virtual-DOM changes to the real DOM. The removed component might get re-connected at a different position in the DOM tree.

(Optional) Called after the Component is updated and/or rendered and all virtual-DOM changes applied to the real DOM. Receives current CalDom instance as the only argument.

"+tag" creates a new Element. '<tag></tag>' creates specified HTML structure. ~svg_tag" creates a SVG element. Otherwise it can be a CSS Selector or an XPath query starting with "$"

Treated as the parent node for CSS selector or XPath query. Otherwise, default to window.document