Global

Methods

addEventListenerFor(element, selector, types, listener, optionsopt) → {undefined}

This method adds a listener callback for an Element that is triggered when a containing target matching the selector is fired. Sets event.delegateTarget to the element that matches to selector, while target remains as element that fired the event.

Parameters
Name Type Attributes Default Description
element Element

An Element to add the event listener to
selector string

A valid CSS selector string
types Array.<string> | string

An Array of String or String representing the event type to listen for
listener function | Object

An Object with a handleEvent() method or a function. Receives an Event as the param. Event has attribute delegateTarget added that is the element that matches the selector.
options Object <optional>
 {}

An Object with options for addEventListener
Returns
undefined
Example
addEventListenerFor(el, 'checkbox', 'change', e => {
    console.log(e.delegateTarget.value)
}, {once: true})
Source: addEventListenerFor.js, line 17

ancestors(element, selectoropt) → {Array.<Element>}

This method traverses the element and it's parents returning all ancestor elements until the selector is matched.

Parameters
Name Type Attributes Description
element Element

An Element to add the event listener to
selector string <optional>

A valid CSS selector string
Returns
Array.<Element> -

An Array of Element ordered by closest first
Example
ancestors(el, '.container')
Source: ancestors.js, line 12

append(element, content, escapeopt, contextopt, methodopt) → {undefined}

This method adds a listener callback for an Element that is triggered when a containing target matching the selector is fired. Sets event.delegateTarget to the element that matches to selector, while target remains as element that fired the event.

Parameters
Name Type Attributes Default Description
element Element

An Element to add the event listener to
content Element | NodeList | HTMLCollection | Array | Promise | string | Object

A Element, NodeList, HTMLCollection, Array, Promise, String of text or html, Object passed to dolla's createElement
escape boolean <optional>

A Boolean directing method to escape or not escape content that is a string
context * <optional>

The value to be passed as the this parameter if content is a method
method string <optional>
 "append"

A String stating which method of Element instance to use to add content
Returns
undefined
Example
append(el, el2)
append(el, [el2, el3, el4])
append(el, el2.children)
append(el, el2.childNodes)
append(el, new Promise(resolve => {
    records.load().then(records => {
        resolve(records.map(record => {
            template(record)
        }))
    })
}))
append(el, {
    class: 'label',
    content: "Hello World"
})
append(el, "<span>Hello World</span>")
Source: append.js, line 34

bury(object, …keys) → {Object}

Set a value of an object following a chain of nested keys.

Parameters
Name Type Attributes Description
object Object

An Object to receive keys/value
keys string <repeatable>

An array of Strings to use as a chain to bury the value
Returns
Object -

object
Example
bury({foo: 1}, 'alpha', 'beta', 'charlie', 'Hello World')
// => {
    foo: 1,
    alpha: {
        beta: {
            charlie: "Hello World"
        }
    }
}
Source: bury.js, line 22

cloneNode(node, deep) → {Node}

Mimics the functionality of Node.prototype.cloneNode, but calls each element's cloneNode, which allows developer to extend cloneNode for Custom Elements

Parameters
Name Type Description
node Node

A Node
deep boolean

A Boolean
Returns
Node -

Node
Source: cloneNode.js, line 11

cloneUp(element, selector, optionsopt) → {Element}

Clones an element and its ancestor chain up to and including the first ancestor that matches the given selector. Optionally includes siblings of each cloned ancestor.

Parameters
Name Type Attributes Default Description
element Element

An Element to start cloning from
selector string

A String CSS selector that determines where to stop cloning ancestors
options Object <optional>
 {}

An Object with optional configuration:

  • siblings.exclude: A CSS selector string to exclude matching sibling elements from being cloned
Returns
Element -

The cloned element with its ancestor chain
Source: cloneUp.js, line 13

content(element, content) → {undefined}

This method replaces the content of an element with new content.

Parameters
Name Type Description
element Element

An Element
content Element | NodeList | HTMLCollection | Array | Promise | string | Object

A Element, NodeList, HTMLCollection, Array, Promise, String of text or html, Object passed to dolla's createElement
Returns
undefined
Source: content.js, line 11

createElement(tagNameopt, attributesopt, namespaceopt) → {Element}

This method mirrors document.createElement, but adds the ability to include attributes and content for the initialized Element

Parameters
Name Type Attributes Default Description
tagName string <optional>
 "div"

A String declaring what type of HTML tag to create
attributes Object <optional>
 {}

An Object whose keys are used to set attributes on the created element. All HTMLElement attributes are accepted including an additional option to define content

  • content: The value of the key content is passed into dolla's append method. Reference the append() documentation for more details about possible content values.
  • tag: A String declaring the type of HTML tag, used as an alternative to the first parameter
namespace string <optional>

A String declaring the namespaceURI
Returns
Element -

Element
Example
createElement('table', {
    class: 'uniformTable',
    cellpadding: 0,
    style: {
        verticalAlign: 'center'
    },
    content: [{
        tag: 'tr'
        content: [{
            tag: 'td',
            content: 'Hello World'
        }]
    }]
})
Source: createElement.js, line 30

css(element, rule) → {string}

Syntax sugar for getComputedStyle

Parameters
Name Type Description
element Element

An Element
rule string

A String of a valid CSS rule
Returns
string -

String representation of rule value
Example
css(el, 'width')
// => "800px"
Source: css.js, line 12

filter(nodes, predicate) → {Array}

This method filters a NodeList with a predicate.

Parameters
Name Type Description
nodes Array | NodeList

An Array or NodeList
predicate function

A function where parameter is each item or node of nodes. The function should return truthy to include
Returns
Array -

Array
Example
filter(el.childNodes, n => n.selected)
Source: filter.js, line 11

getBoundingClientRect(…elements) → {DOMRect}

This method gets the bounding client rectangle of a group of elements. Similar to Element.getBoundingClientRect(), but for n elements.

Parameters
Name Type Attributes Description
elements Element <repeatable>

An Array of Elements
Returns
DOMRect -

DOMRect
Source: getBoundingClientRect.js, line 7

innerHeight(element) → {number}

This method returns an element's height including padding, which is excluded from el.offsetHeight.

Parameters
Name Type Description
element Element

An Element
Returns
number -

Integer
Source: innerHeight.js, line 7

innerWidth(element) → {number}

This method returns an element's width including padding, which is excluded from el.offsetWidth.

Parameters
Name Type Description
element Element

An Element
Returns
number -

Integer
Source: innerWidth.js, line 7

insertAfter(anchor, element) → {Element|number}

This method appends an element after an anchor

Parameters
Name Type Description
anchor Element | Array | NodeList | HTMLCollection

An Element, Array, NodeList, or HTMLCollection
element Element | NodeList | HTMLCollection | Array

An Element, NodeList, HTMLCollection, or Array
Returns
Element | number -

The inserted element or Integer
Example
insertAfter(document.querySelector('#anchor'), document.createElement('button'))
insertAfter(document.querySelector('#anchor'), document.querySelector('#container').children)
insertAfter(document.querySelector('#anchor'), document.querySelector('#container').childNodes)
insertAfter(document.querySelector('#anchor'), [
    document.createElement('label'),
    document.createElement('button')
])
Source: insertAfter.js, line 17

insertBefore(anchor, element) → {Element|number}

This method appends an element before an anchor

Parameters
Name Type Description
anchor Element | Array | NodeList | HTMLCollection

An Element, Array, NodeList, or HTMLCollection
element Element | NodeList | HTMLCollection | Array

An Element, NodeList, HTMLCollection, or Array
Returns
Element | number -

The inserted element or Integer
Example
insertBefore(document.querySelector('#anchor'), document.createElement('button'))
insertBefore(document.querySelector('#anchor'), document.querySelector('#container').children)
insertBefore(document.querySelector('#anchor'), document.querySelector('#container').childNodes)
insertBefore(document.querySelector('#anchor'), [
    document.createElement('label'),
    document.createElement('button')
])
Source: insertBefore.js, line 17

isEmpty(element) → {boolean}

This method returns if an element is empty

Parameters
Name Type Description
element Element

An Element
Returns
boolean -

Boolean
Source: isEmpty.js, line 7

isFocus(element) → {boolean}

This method returns if an element is focused

Parameters
Name Type Description
element Element

An Element
Returns
boolean -

Boolean
Source: isFocus.js, line 7

isVisible(element) → {boolean}

This method returns if an element is visible (attached to the DOM)

Parameters
Name Type Description
element Element

An Element
Returns
boolean -

Boolean
Source: isVisible.js, line 7

listenerElement(tagNameopt, attributesopt, listenerType, listenerCallback) → {Element}

This method returns a HTMLElement with an event listener

Parameters
Name Type Attributes Description
tagName string <optional>

A String for html element
attributes Object <optional>

An Object of attributes for dolla's createElement
listenerType string | Array.<string>

A String or Array representing the event type to listen to
listenerCallback function

A function that receives an Event as a parameter
Returns
Element -

Element
Example
listenerElement('button', {
    class: 'btn',
    content: 'Confirm'
}, 'click', e => {
    console.log(e)
})

listenerElement({
    class: 'btn',
    content: 'Confirm'
}, 'click', e => {
    console.log(e)
})
Source: listenerElement.js, line 28

map(elements, iteratee) → {Array}

This method maps over elements similar to Array.prototype.map

Parameters
Name Type Description
elements Array | HTMLCollection | NodeList

An Array, HTMLCollection, or NodeList
iteratee function

A Function that receives each item in elements as an argument, the return of which is set as the index of the return array
Returns
Array -

Array
Example
map(element.children, el => el.offsetHeight)
map(element.childNodes, el => el.offsetHeight)
map([
    el1,
    el2,
    el3
], el => el.offsetHeight)
Source: map.js, line 18

nextElementSiblings(element, filteropt) → {Array}

This method returns an element's following siblings.

Parameters
Name Type Attributes Description
element Element

An Element
filter function <optional>

A method that receives the next sibling as a parameter, and returns true or false
Returns
Array -

Array of sibling elements
Example
nextElementSiblings(el, sibling => {
    return sibling.tagName == "checkbox"
})
Source: nextElementSiblings.js, line 14

offset(element) → {DOMRect}

This method returns an element's DOMRect in relation to its offsetParent

Parameters
Name Type Description
element Element | HTMLCollection

An Element or HTMLCollection
Returns
DOMRect -

DOMRect
Source: offset.js, line 10

offsetTo(element, target) → {DOMRect}

This method returns an elements position {top, left} in relation to a target element

Parameters
Name Type Description
element Element | HTMLCollection

An Element or HTMLCollection
target Element

An Element
Returns
DOMRect -

DOMRect
Source: offsetTo.js, line 10

offsetToBody(el) → {DOMRect}

This method returns an element's bounding DOMRect in relation to the rootNode (typically document.body)

Parameters
Name Type Description
el Element | HTMLCollection

An Element or HTMLCollection
Returns
DOMRect -

DOMRect
Source: offsetToBody.js, line 9

offsetToViewport(element) → {DOMRect}

This method returns an elements position {top, left} in relation to the viewport

Parameters
Name Type Description
element Element | HTMLCollection

An Element or HTMLCollection
Returns
DOMRect -

DOMRect
Source: offsetToViewport.js, line 9

outerHeight(element) → {number}

This method returns the height of an element including margin

Parameters
Name Type Description
element Element

An Element
Returns
number -

Integer
Source: outerHeight.js, line 7

outerWidth(element) → {number}

This method returns the width of an element including margin

Parameters
Name Type Description
element Element

An Element
Returns
number -

Integer
Source: outerWidth.js, line 7

prepend(element, content, escapeopt, contextopt) → {undefined}

This method is the same as append, but inserts content at the start of an elements children.

Parameters
Name Type Attributes Description
element Element

An Element to add the event listener to
content Element | NodeList | HTMLCollection | Array | Promise | string | Object

A Element, NodeList, HTMLCollection, Array, Promise, String of text or html, Object passed to dolla's createElement
escape boolean <optional>

A Boolean directing method to escape or not escape content that is a string
context * <optional>

The value to be passed as the this parameter if content is a method
Returns
undefined
Example
prepend(el, el2)
prepend(el, [el2, el3, el4])
prepend(el, el2.children)
prepend(el, el2.childNodes)
prepend(el, new Promise(resolve => {
    records.load().then(records => {
        resolve(records.map(record => {
            template(record)
        }))
    })
}))
prepend(el, {
    class: 'label',
    content: "Hello World"
})
prepend(el, "<span>Hello World</span>")
Source: prepend.js, line 30

previousElementSiblings(element, filteropt) → {Array}

This method returns an element's previous siblings.

Parameters
Name Type Attributes Description
element Element

An Element
filter function <optional>

A method that receives the previous sibling as a parameter, and returns true or false
Returns
Array -

Array of previous sibling elements
Example
previousElementSiblings(el, sibling => {
    return sibling.tagName == "checkbox"
})
Source: previousElementSiblings.js, line 13

remove(element) → {Element|NodeList|Array|HTMLCollection}

This method removes an element from the document/fragment to which it is attached

Parameters
Name Type Description
element Element | NodeList | Array | HTMLCollection

An Element, NodeList, Array, or HTMLCollection to remove
Returns
Element | NodeList | Array | HTMLCollection -

The removed element(s)
Source: remove.js, line 7

replaceContents(element, …nodes) → {undefined}

This method replaces an element's content with new content

Parameters
Name Type Attributes Description
element Element

An Element
nodes Element | NodeList | HTMLCollection | Array | Promise | string | Object <repeatable>

A Element, NodeList, HTMLCollection, Array, Promise, String of text or html, Object passed to dolla's createElement. Checkout append for more details about what content can be used
Returns
undefined
Example
replaceContents(el, anotherElement.children)
replaceContents(el, {
    tag: 'button',
    class: 'btn'
})
Source: replaceContents.js, line 19

serializeForm(form) → {Object}

This method returns object of a form element's key and value pairs

Parameters
Name Type Description
form FormElement

A FormElement
Returns
Object -

Object
Example
// HTML:
// <form>
//     <input name="user[name]" />
//     <input name="user[email_address]" />
//     <input name="team[is_active]" />
// </form>
serializeForm(form)
// => {
//  [user]name: 'Rod Kimble',
//  [user]emailAddress: 'rod.kimble@hot-rod-productions.com',
//  [team][is_active]: true
//}
Source: serializeForm.js, line 22

serializeFormToJSON(form) → {Object}

This method returns JSON of a form element's key and value pairs. This function unlike serializeForm allows the keys to nest keys (see usage)

Parameters
Name Type Description
form FormElement

A FormElement
Returns
Object -

JSON object
Example
// HTML:
// <form>
//     <input name="user[name]">
//     <input name="user[email_address]">
//     <input name="team[is_active]">
// </form>
serializeFormToJSON(form)
// => {
//  user: {
//      name: 'Rod Kimble',
//      emailAddress: 'rod.kimble@hot-rod-productions.com'
//  },
//  team: {
//      is_active: true
//  }
//}
Source: serializeFormToJSON.js, line 29

setAttribute(el, key, value)

Assigns attribute for an Element.

Parameters
Name Type Description
el Element

An Element to assign attributes to
key string

Used to set attribute on the element. All HTMLElement attributes are accepted including additional options:

  • content: The value of the key content is passed into dolla's append method. Reference the append() documentation for more details about possible content values.
  • tag: A String declaring the type of HTML tag, used as an alternative to the first parameter
value *

The value to set for the attribute
Example
setAttribute(el, 'class', new Promise(r => r('text-bold')))
Source: setAttribute.js, line 18

setAttributes(el, attributesopt) → {Element}

Assigns attributes for an Element

Parameters
Name Type Attributes Default Description
el Element

An Element to assign attributes to
attributes Object <optional>
 {}

An Object whose keys are used to set attributes on the element. All HTMLElement attributes are accepted including additional options:

  • content: The value of the key content is passed into dolla's append method. Reference the append() documentation for more details about possible content values.
  • tag: A String declaring the type of HTML tag, used as an alternative to the first parameter
Returns
Element -

Element
Example
setAttributes(el, {
    class: 'uniformTable',
    cellpadding: 0,
    style: {
        verticalAlign: 'center'
    },
    content: [{
        tag: 'tr'
        content: [{
            tag: 'td',
            content: 'Hello World'
        }]
    }]
})
Source: setAttributes.js, line 31

toElements(content) → {NodeList|Array}

This method converts a string of HTML to Elements

Parameters
Name Type Description
content string | function

A String of HTML or a Function that returns a string of HTML
Returns
NodeList | Array -

NodeList or Array of elements
Example
toElements("<div class='container'><label>Label</label><input type='checkbox'></div>")
toElements(() => "<div class='container'><label>Label</label><input type='checkbox'></div>")
Source: toElements.js, line 11

trigger(element, eventName, optionsopt) → {boolean}

This method calls an element's dispatchEvent with a custom event.

Parameters
Name Type Attributes Description
element Element

An Element
eventName string

A String representing the event type
options Object <optional>

Object passed to CustomEvent constructor. Defaults target, bubbles, cancelable
Returns
boolean -

false if event is cancelable, and at least one of the event handlers which received event called Event.preventDefault(). Otherwise true.
Example
el.addEventListener('attachedToDOM', e => el.style.background = 'green')
trigger(el, 'attachedToDOM')
Source: trigger.js, line 13