Documentation

Class: $Document

$Document

new $Document()

Used to represent a document in better-dom

Extends

Methods

clone(deepCopy)

Clone element

Parameters:
Name Type Description
deepCopy Boolean

true when all children should also be cloned, otherwise false
Inherited From:
Returns:

A clone of the current element

Type
$Node
Example
ul.clone(true);  // => clone of <ul> with all it's children
ul.clone(false); // => clone of <ul> element ONLY

contains(element)

Check if an element is inside of the current context

Parameters:
Name Type Description
element $Node

Element to check
Inherited From:
Returns:

true if success and false otherwise

Type
Boolean
Example
DOM.contains(DOM.find("body")); // => true
DOM.find("body").contains(DOM); // => false

create(content)

Create a new $Element from a HTML string

Parameters:
Name Type Description
content String

HTMLString
Returns:

an element wrapper

Type
$Element
Example
DOM.create("<div>");                // => wrapper of <div>
DOM.create("<a><span></span></a>"); // => wrapper of <a> + innner <span>

createAll(content)

Create a new Array.<$Element> from a HTML string

Parameters:
Name Type Description
content String

HTMLString
Returns:

an array of element wrappers

Type
Array.<$Element>
Example
DOM.createAll("<span></span><b></b>"); // => array with 2 $Elements: <span> and <b>

extend(selector, definition)

Declare a live extension

Parameters:
Name Type Description
selector String

css selector of which elements to capture
definition Object

live extension definition
See:
Example
DOM.extend("selector", {
    constructor: function() {
        // initialize component
    },
    publicMethod: function() {
        // ...
    }
});

find(selector)

Find the first matched element in the current context by a CSS selector

Parameters:
Name Type Description
selector String

CSS selector
Inherited From:
Returns:

The first matched element

Type
$Element
Example
var body = DOM.find("body");  // => <body> wrapper
var foo  = body.find(".foo"); // => the first element with class "foo"
foo.find(".bar>span");        // => the first element that matches ".bar>span"

findAll(selector)

Find all matched elements in the current context by a CSS selector

Parameters:
Name Type Description
selector String

CSS selector
Inherited From:
Returns:

An array of matched elements

Type
Array.<$Element>
Example
DOM.findAll("a");         // => all links in the document
context.findAll("ol>li"); // => all <li> inside of <ol>

fire(type [, detail])

Trigger an event of specific type with optional data

Parameters:
Name Type Argument Description
type String

Type of event
detail Object <optional>

Custom event data
Inherited From:
Returns:

true if default event action was NOT prevented

Type
Boolean
Example
link.fire("click");              // fire click event
link.fire("my:event", {a: "b"}); // fire "my:event" with custom data

get(name [, defaultValue])

Get property or attribute value by name

Parameters:
Name Type Argument Description
name String | Array

Property or attribute name or array of names
defaultValue Object <optional>

Default value if returned is null
Inherited From:
Returns:

Value of property or attribute

Type
Object
Example
link.get("title");       // => property title
link.get("data-custom"); // => custom attribute data-custom

importScripts(url [, callback])

Import external scripts on the page and call optional callback when it will be done

Parameters:
Name Type Argument Description
url String <repeatable>

script file url(s)
callback function <optional>

callback that is triggered when all scripts are loaded
Example
DOM.importScripts("http://cdn/script1.js", function() {
    // do something when the script is loaded
});
// loading several scripts sequentially
DOM.importScripts("http://cdn/script2.js", "http://cdn/script3.js");

importStyles(selector, cssText)

Append global css styles

Parameters:
Name Type Description
selector String

css selector
cssText String

css rules
Example
DOM.importStyles(".foo, .bar", "background: white; color: gray");
// more complex selectors
DOM.importStyles("@keyframes fade", "from {opacity: 0.99} to {opacity: 1}");

mock(content [, varMap])

Return $Element initialized with all existing live extensions. Also exposes private functions that do not usually exist. Accepts the same arguments as DOM.create

Parameters:
Name Type Argument Description
content String

HTMLString
varMap Object | Array <optional>

key/value map of variables
See:
Returns:

a mocked instance

Type
$Element

on(type [, options] [, args], callback)

Bind a DOM event listener

Parameters:
Name Type Argument Description
type String

Event type
options Object | String <optional>

Event options object or css selector to match on
args Array <optional>

Array of handler arguments to pass into the callback
callback function

Event listener callback
Inherited From:
Returns:

Functor to cancel the listener

Type
function
Example
link.on("focus", function() {
    // do something on focus
});

link.on("click", "i", function() {
    // do something on internal <i> click
});

link.on("click", "span", ["currentTarget"], function(span) {
    // <span> is the element was clicked
});

link.on("blur", {once: true}, function() {
    // event fired only once
});

link.on("mousedown", {capture: true}, function() {
    // event fired on capturing phase
});

set(name, value)

Set property/attribute value by name

Parameters:
Name Type Description
name String | Object | Array | function

property/attribute name
value String | function

property/attribute value or functor
Inherited From:
Returns:

Self

Type
$Node
Example
link.set("title", "mytitle");   // set title property
link.set("data-custom", "foo"); // set custom attribute data-custom