build

build module provides a helper function to create DOM fragments using a JsonML-like description. This function is inspired by Virtual DOM techniques.

build(vdom, parent, options)

The function builds DOM using vdom description (see below), optionally appending top-level elements to parent. It returns either a DOM tree root, or parent, if it was specified.

vdom parameter

vdom encodes a collection of nodes. Following nodes are recognized:

• a function — called with options as the only parameter. Its result is re-interpreted.
• a DOM node object — used as is.
• a string, a Boolean, a number, a regular expression, or a date — all of them are converted to a string (using .toString()), and used to create a text node.
• a node description encoded as an array.
• all other objects are ignored.

An array is interpreted as follows:

• If the first array item is:
  • a function — called with options as the only parameter. Its result is re-interpreted.
  • a string — a DOM node tag. It is passed directly to create() (see create). It can include a namespace, an id, and/or a list of CSS classes in the CSS selector notation.
  • a DOM node — used as is.
  • an array — no new DOM node is defined. The whole array is assumed to be a list of children for its parent.
• Other elements of an array can be (in any order):
  • a dictionary object — interpreted as an attributes object set by create.setAttrs() on the current node.
  • a child described above in the previous list.

Example of vdom:

['ul', {'data-sort': 'asc'}, ['li', 'one'], ['li.x', 'two'], ['li', 'three']]

It will produce:

<ul data-sort="asc">
  <li>one</li>
  <li class="x">two</li>
  <li>three</li>
</ul>

parent parameter

If parent is truthy:

• As a DOM node: its parent.ownerDocument is used to create other nodes, and top-level nodes will be appended to it.
• As a document: it is used to create other nodes.

If parent is falsy:

• options.document is used to specify a document used to create nodes.
• If options.document is falsy, document is used as a fallback.

If parent is specified, and truthy, it is returned as by build(). Otherwise a top-level node is returned, or a specially created DocumentFragment.

options parameter

If specified it defines a dictionary object. At the moment only one property is understood:

• document — optionally defines a document object to use when creating nodes.

Additionally, it is passed to create(), create.setAttrs(), and when evaluating all functions as the only parameter.

Example

var vdom = [
      ['h1.main', function (options) { return 'Hello, ' + options.name + '!'; }],
      ['p', {style: {'background-color': 'red'}}, 'Today is ', function () {
        var now = new Date();
        return (now.getMonth() + 1) + '/' + now.getDate() + '/' + now.getFullYear();
      }]
    ];

var frag = build(vdom, null, {name: 'Bob'});

The example above can produce HTML like this:

<h1 class="main">Hello, Bob!</h1>
<p style="background-color: red">
  Today is 12/31/2016.
</p>