QuantumJS
Home
Introduction
OverviewQuick StartThe Markup LanguageCore ConceptsUsing the CLI / APIQuantum vs Markdown
Config
quantum.config.js
Core Modules
quantum-corequantum-domquantum-html
Optional Modules
quantum-apiquantum-code-highlightquantum-diagramquantum-docsquantum-markdownquantum-templatequantum-version
Edit Page
quantum-dom
A minimal virtual dom library used by quantum for building html pages.
About
This is a minimal virtual dom library that is used when defining entity transforms which convert entities into snippets of html.
The Quantum DOM library is primarily used when defining custom EntityTransform functions. It provides an api that allows creation of objects that represent elements on a web page (for example a <div> or <span>, or any other dom element).
Api
Prototypes
Assetadded
Represents a file that should be included with the page (css, javascript or other). This protoype should not be used directly, instead use dom.asset()
Example
const dom = require('quantum-dom')

// An asset that is loaded from a file
dom.asset({
  url: "/resources/lib.js",
  filename: 'lib.js'
})

// An anonymous asset that takes a string as the content
dom.asset({
  type: "js",
  content: 'alert("example")'
})
Properties
contentString
The content of this asset (this can be used as an alternative to the filename option)
filenameString
The file to load the asset content from
typeString
The type of asset. Can be 'js' or 'css'. This is required when the url is not provided, otherwise it is ignored.
urlString
The url to load the asset from (when the asset is not embedded in the page)
Elementadded
An object that represents a DOM element. These can be created using dom.create()
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .class('button-container')
  .add(dom.create('button').text('Click me'))

div.stringify()
// '<div class="button-container"><button>Click me</button></div>'
Methods
addelementElementoptionsObjectElement
Adds an element as a child of this Element
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .add(dom.create('div').class('child-1'))
  .add(dom.create('div').class('child-2'))
Arguments
elementElement
The element to add as a child
options
Options that specify how the element is added
Properties
addToEndBoolean
Set to true to keep the child at the end of list of children when it is stringified
Default: false
Returns
Element
Returns the Element instance you are adding to.
addelementsArray[Element / Promise[Element]]optionsObjectElement
Adds multiple elements as a children of this Element
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .add([
    dom.create('div').class('child-1'),
    dom.create('div').class('child-2')
])
Arguments
elementsArray[Element / Promise[Element]]
An array of elements to add as children
options
Options that specify how the elements are added
Properties
addToEndBoolean
Set to true to keep the children at the end of list of children when they are stringified
Default: false
Returns
Element
Returns the Element instance you are adding to.
addelementPromise[Element]optionsObjectElement
Adds an element as a child of this Element
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .add(getName().then(name => dom.create('div').text(name)))
  .add(getAge().then(age => dom.create('div').text(age)))
Arguments
elementPromise[Element]
A promise which yields the element to add as a child
options
Options that specify how the elements are added
Properties
addToEndBoolean
Set to true to keep the child at the end of list of children when it is stringified
Default: false
Returns
Element
Returns the Element instance you are adding to.
attrnameStringString
Gets the value of an element's attribute
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .attr('class', 'my-div')

div.attr('class') // returns 'my-div'
Arguments
nameString
The name of the element's attribute to get
Returns
String
Returns the value of attribute or undefined if no value is set for the attribute
attrnameStringvalueStringElement
Sets the value of an element's attribute
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .attr('class', 'my-div')
  .attr('id', 'div1')
Arguments
nameString
The name of the element's attribute to set
valueString
The value to set the attribute to
Returns
Element
Returns this Element instance
classString
Gets the class attribute for this element
Example
const dom = require('quantum-dom')

const div = dom.create('div').class('my-div')

div.class() // returns 'my-div'
Returns
String
Returns the class attribute of this Element or undefined if no class is set
classvalueStringElement
Sets the class attribute for this element
Example
const dom = require('quantum-dom')

const div = dom.create('div').class('my-div')
Arguments
valueString
The value to set the class to
Returns
Element
Returns this Element instance
classedclassStringBoolean
Checks if the Element has a class
Example
const dom = require('quantum-dom')

const button = dom.create('button')
  .class('button outline danger')

div.classed('button') // returns true
div.classed('outline') // returns true
div.classed('positive') // returns false
Arguments
classString
The class to check existence of
Returns
Boolean
Returns true if the Element has the class supplied
classedclassStringclassedBooleanElement
Adds or removes one or more classes to this Element
Example
const dom = require('quantum-dom')

const button = dom.create('button')
  .class('button outline danger')


button.classed('button') // returns true
button.classed('button', false)
button.classed('button') // returns false

button.classed('positive', true)
button.class() // returns 'danger outline positive'
button.classed('danger outline', false)
button.class() // returns 'positive'
Arguments
classString
The class to add or remove (or multiple space separated classes)
classedBoolean
Supply true to add classes to the element, false to remove.
Returns
Element
Returns this Element instance
idString
Gets the id attribute for this element
Example
const dom = require('quantum-dom')

const div = dom.create('div').id('my-div')

div.id() // returns 'my-div'
Returns
String
Returns the id attribute of this Element or undefined if no id is set
idvalueStringElement
Sets the id attribute for this element
Example
const dom = require('quantum-dom')

const div = dom.create('div').id('my-div')
Arguments
valueString
The value to set the id to
Returns
Element
Returns this Element instance
remove
Removes this element from its parent
Example
const dom = require('quantum-dom')

const child1 = dom.create('div').class('child-1')
const child2 = dom.create('div').class('child-1')

const div = dom.create('div')
  .add([child1, child2])

child1.remove()
// 'div' just has child2 as a child now
removeChildchildElementBoolean
Removes a child from this Element
Example
const dom = require('quantum-dom')

const child1 = dom.create('div')
const child2 = dom.create('div')

const div = dom.create('div')
  .add([child1, child2])

div.removeChild(child1)
// 'div' just has child2 as a child now
Arguments
childElement
The child to remove from this Element
Returns
Boolean
Returns true if the child was successfully removed, false if the element being removed is not a child of this Element
stringifyString
Turns this Element into a html string fragment
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .add(dom.create('div').class('child-1'))
  .add(dom.create('div').class('child-2'))

div.stringify()
// <div><div class="child-1></div><div class="child-2></div></div>
Returns
String
The html string that represents this Element.
texttextStringoptionsObjectElement
Adds text as a child of this Element
Example
const dom = require('quantum-dom')

const div = dom.create('div')
  .text("Some text")
Arguments
textString
The text to add as a child
options
Options that specify how the element is added
Properties
escapeBoolean
Set to true to html escape the added text
Default: true
Returns
Element
Returns this Element instance
HeadWrapperadded
The type returned by head(). Instances of this should be created only using the head() function.
Properties
elementElement
The element to place in the head of the document.
options
Properties
idString
A unique id that can be used for an element. Sometimes you may only want one copy of an element in the head - if you specify an id then any duplicate elements with the same id will be de-duplicated when rendering out to a html string.
Note that this id is different to the id attribute on an element. For setting the element id, see the Element prototype.
PageModifieradded
An object that modifies the page in some way when stringifying. This is returned by the bodyClassed function.
Properties
options
The options used to create the PageModifier
Common Properties
Properties that should exist for all PageModifier objects.
typeString
The type of PageModifier being created.
The bodyClassed function uses type 'body-classed'
bodyClassed properties
Properties that exist within the options when created by the bodyClassed function.
classString
The class to add or remove
classedBoolean
true when adding the class, false when removing
TextNodeadded
An object that represents a HTML text node. Instances of this should be created using the textNode factory function.
Example
const dom = require('quantum-dom')

dom.create('div')
  .add(dom.textNode('hello'))
  // Add html to the page without converting < to &lt; etc.
  .add(dom.textNode('<div id="my-div"></div>', { escape: false }))
Properties
options
The options set by the textNode factory function.
Properties
escapeBoolean
This will be true when the text has been html-escaped and false when it has not.
textString
The text contents of this textNode
Methods
stringifyString
Turns this text node to a string
Example
const dom = require('quantum-dom')

const textNode = dom.textNode('hello')
textNode.stringify() // "hello"
Returns
String
This text node converted to a string
Functions
assetoptionsObjectAssetadded
Creates a new Asset
Example
const dom = require('quantum-dom')

// An asset that is loaded from a file
dom.asset({
  url: "/resources/lib.js",
  filename: 'lib.js'
})

// An anonymous asset that takes a string as the content
dom.asset({
  type: "js",
  content: 'alert("example")'
})
Arguments
options
Properties
contentString
The content of this asset (this can be used as an alternative to the filename option)
filenameString
The file to load the asset content from
typeString
The type of asset. Can be 'js' or 'css'. This is required when the url is not provided, otherwise it is ignored.
urlString
The url to load the asset from (when the asset is not embedded in the page)
Returns
Asset
Returns a new Asset instance
bodyClassedclassStringclassedBooleanPageModifieradded
Adds or removes a class to the body of the page.
Example
const dom = require('quantum-dom')

// Adds the class '.extra-body-class' to the body
const extraBodyClass = dom.bodyClassed('extra-body-class', true)

const div = dom.create('div')

dom.stringify([
  extraBodyClass,
  div
])
/* Returns a promise with:
{
  html: '<!DOCTYPE html>\n<html>\n<head></head>\n<body class="qm-body-font extra-body-class"><div></div></body></html>',
  assets: []
}
*/
Arguments
classString
The class to add or remove
classedBoolean
true to add the class, false to remove
Returns
PageModifier
A PageModifier instance that adds or removes a class from the body element of a page when stringified.
createtypeStringElementadded
Creates a dom element of the type provided. The type can be any valid dom element type and should be provided lower case. Ie, use dom.create('div') not dom.create('DIV') ). No validation is performed on the type, so custom elements can also be created.
Example
const dom = require('quantum-dom')

const div = dom.create('div') // Creates a <div> element
const span = dom.create('span') // Creates a <span> element
const button = dom.create('button') // Creates a <button> element
const myElement = dom.create('myElement') // Creates a <myElement> custom element
Arguments
typeString
The type of element to create. This should be a valid lower case html element type.
Returns
Element
A newly constructed Element instance.
escapeHTMLstringStringStringadded
Html-escapes the string provided
Example
const dom = require('quantum-dom')

dom.escapeHTML('<div>')
// returns '&lt;div&gt;'
Arguments
stringString
The string to be HTML escaped.
Returns
String
The string with html escaping applied
headelementElementoptionsObjectHeadWrapperadded
Wraps an Element in a new type that causes the wrapped element to be placed in the <head> of the page when the virtual dom is converted to html
Example
const dom = require('quantum-dom')

const root = dom.create('div')
  .add(dom.create('div').class('my-element'))
  .add(dom.head(dom.create('style').text('.my-element { background: red; }', {escape: false})))
Arguments
elementElement
The element to place in the head of the document.
options
Properties
idString
A unique id that can be used for an element. Sometimes you may only want one copy of an element in the head - if you specify an id then any duplicate elements with the same id will be de-duplicated when rendering out to a html string.
Note that this id is different to the id attribute on an element. For setting the element id, see the Element prototype.
Returns
HeadWrapper
A special type of node, the contents of which gets placed in the head element of the document.
randomIdStringadded
Creates a new random id which can be used to identify an element in a page. This is useful when a script needs to be run to initialise a specific element.
Example
const dom = require('quantum-dom')

dom.randomId() // returns a new random id
Returns
String
A random 32 character hex string which can be used to uniquely identify elements in the page.
stringifyelementsArray[Element]optionsObjectObjectadded
Converts an array of elements to a full html page (as a string)
Example
const dom = require('quantum-dom')

const div = dom.create('div').class('button-container').add(dom.create('button').text('Click me'))

dom.stringify([div])
Output
{
  html: '<!DOCTYPE html>\n<html>\n<head></head>\n<body class="qm-body-font"><div class="button-container"><button>Click me</button></div></body></html>',
  assets: []
}
Arguments
elementsArray[Element]
The elements that should form the body of the html page
options
Options that configure how the page is rendered
Properties
assetPathString
The url for the exported assets in the output site.
Default: ''
baseUrlString
The base url for the exported assets. This will be prefixed to the assetPath destination.
E.g. for GitHub Pages (i.e. where the output site is served in a subdirectory) https://username.github.io/project the baseUrl would be "/project"
Default: ''
embedAssetsBoolean
Set to true to embed JavaScript and CSS assets in the page, false to export them as separate files
Default: true
Returns
Object
Properties
assetsArray[Asset]
The assets that were exported when building the page
htmlString
The built html string
textNodetextStringoptionsObjectTextNodeadded
Creates a text node element with the string provided as its contents.
Example
const dom = require('quantum-dom')

dom.create('div')
  .add(dom.textNode('hello'))
  .add(dom.textNode('<div id="my-div"></div>', {escape: false}))
Arguments
textString
The text contents of this textNode
options
Properties
escapeBoolean
Set to true to html-escape the text passed in, false to leave it unescaped.
Default: true
Returns
TextNode
A newly constructed TextNode instance.
Examples
The api allows creation of detached elements. Detached elements can be added to another as children to create small chunks of dom. Here are some examples of how to use the api: 
const dom = require('quantum-dom')

// Creates a <div></div> element
dom.create('div')

// Creates a <div id="my-id"></div> element
dom.create('div').id('my-id')

// Creates a <a href="/link/to/somewhere">Link</a> element
dom.create('a').attr('href', '/link-to-somewhere').text('Link')

// Creates a <span class="my-class"></span> element
dom.create('span').class('my-class')

// Creates an element that will render out to <h1>My Header</h1>
dom.create('h1').text('My Header')

/*
  Creates the following dom structure:

  <div class="outer-div">
    <div class="inner-div"></div>
</div>
*/
dom.create('div').class('outer-div')
  .add(dom.create('div').class('inner-div'))
More info
When a page is rendered with quantum, a virtual dom page is built up as the source file for the page is processed. Once done, the virtual dom is rendererd out to a HTML string and written to a file. This two phase process allows each entity transform to be a pure function which has nice properties for caching and speeding up builds.
See Core Concepts - Entity Transforms for more information.