DOMBuilder

DOMBuilder takes some of the pain out of dynamically creating HTML content in JavaScript and supports generating multiple types of output from the same inputs.

Quick Guide

DOMBuilder provides a convenient, declarative API for generating HTML elements, via objects which contain functions named for the HTML element they create:

with(DOMBuilder.dom) {
  var article =
    DIV({'class': 'article'}
    , H2('Article title')
    , P('Paragraph one')
    , P('Paragraph two')
    )
}

Every element function also has a map function attached to it which allows you to easily generate content from a list of items:

var el = DOMBuilder.html
function shoppingList(items) {
  return el.OL(el.LI.map(items))
}
>>> shoppingList(['Cheese', 'Bread', 'Butter'])
<ol><li>Cheese</li><li>Bread</li><li>Butter</li></ol>

You can control map output by passing in a callback function:

function opinionatedShoppingList(items) {
  return el.OL(el.LI.map(items, function(item, attrs, loop) {
    if (item == 'Cheese') attrs['class'] = 'eww'
    if (item == 'Butter') return el.EM(item)
    return item
  }))
}
>>> opinionatedShoppingList(['Cheese', 'Bread', 'Butter'])
<ol><li class="eww">Cheese</li><li>Bread</li><li><em>Butter</em></li></ol>

If you want to use this API to go straight to a particular type of output, you can do so using the functions defined in DOMBuilder.dom and DOMBuilder.html, as demonstrated above.

If you want to be able to switch freely between output modes, or you won’t know which kind of output you need until runtime, you can use the same API via DOMBuilder.elements, controlling what it outputs by setting the DOMBuilder.mode flag to 'dom' or 'html', or calling a function which generates content using DOMBuilder.withMode():

var el = DOMBuilder.elements
function shoutThing(thing) {
  return el.STRONG(thing)
}
>>> DOMBuilder.mode = 'html'
>>> shoutThing('Hello!').toString()
<strong>Hello!</strong>
>>> DOMBuilder.withMode('dom', shoutThing, 'Hey there!')
[object HTMLStrongElement]

This is useful for writing libraries which need to support outputting both DOM Elements and HTML Strings, or for unit-testing code which normally generates DOM Elements by flipping the mode in your tests to switch to HTML String output.

DOMBuilder also supports using its output modes with another common means of defining HTML in JavaScript code, using nested lists (representing elements and their contents) and objects (representing attributes), like so:

var article =
  ['div', {'class': 'article'}
  , ['h2', 'Article title']
  , ['p', 'Paragraph one']
  , ['p', 'Paragraph two']
  ]

You can generate output from one of these structures using DOMBuilder.build(), specifying the output mode:

>>> DOMBuilder.build(article, 'html').toString()
<div class="article"><h2>Article title</h2><p>Paragraph one</p><p>Paragraph two</p></div>

>>> DOMBuilder.build(article, 'dom').toString()
[object HTMLDivElement]

You can also generate these kinds of structures using the element functions defined in DOMBuilder.array.

This is just a quick guide to what DOMBuilder can do - dive into the rest of the documentation to find out about the rest of its features, such as:

Installation

Browsers

DOMBuilder is a modular library, which supports adding new output modes and feature modes as plugins.

The available components are:

core.js
Core library
dom.js
DOM output mode - adds DOMBuilder.dom
html.js
HTML output mode - adds DOMBuilder.html
template.js
Template feature mode - adds DOMBuilder.template

Compressed Builds

Compressed builds of DOMBuilder are available to suit various needs:

DOM and HTML
For creation of mixed content, with DOM Mode as the default output format.
DOM only
For creation of DOM Elements, with DOM Mode as the default output format.
HTML only
For creation of HTML Strings, with HTML Mode as the default output format.
Templates
For templating, with mixed output and DOM Mode as the default output format.

Dependencies

All required dependencies from isomorph are bundled into the builds above.

If jQuery (>= 1.4) is available, DOMBuilder will make use of it when creating DOM Elements and setting up their attributes and event handlers. Otherwise, DOMBuilder will fall back to using some less comprehensive workarounds for cross-browser DOM issues and use the traditional event registration model for compatibility.

Changed in version 1.4: jQuery was made optional, with the caveat that cross-browser support will be less robust.

Changed in version 2.1: There are now some required utility dependencies, which are bundled with the browser builds.

Node.js

New in version 1.4.1.

DOMBuilder can be installed as a Node.js module using npm. The Node.js build includes Templates and HTML Mode, and has HTML as the default output format.

Install:

npm install DOMBuilder

Import:

var DOMBuilder = require('DOMBuilder')

Project Versions

Table Of Contents

Next topic

DOMBuilder Core

This Page