Namespace: dom

Members

NodesObject.<string, number>

Numeric codes that represent the type of DOM interface node types.

Properties:

Name	Type	Default	Description
ELEMENT	Object.<string, number>	1
ATTR	Object.<string, number>	2
TEXT	Object.<string, number>	3
CDATA_SECTION	Object.<string, number>	4
ENTITY_REFERENCE	Object.<string, number>	5
ENTITY	Object.<string, number>	6
PROCESSING_INSTRUCTION	Object.<string, number>	7
COMMENT	Object.<string, number>	8
DOCUMENT	Object.<string, number>	9
DOCUMENTTYPE	Object.<string, number>	10
DOCUMENT_FRAGMENT	Object.<string, number>	11
NOTATION	Object.<string, number>	12

Methods

absoluteLeft(element){integer}

dom.js, line 292

Calculates the absolute left position
of an element

Name	Type	Description
element	Element

absoluteTop(element){integer}

dom.js, line 280

Calculates the absolute top position
of an element

Name	Type	Description
element	Element

addClass(elem, className)

dom/classes.js, line 43

Adds one or more classes to current classes of the given Element.

Name	Type	Description
elem	Element
className	string	repeatable

append(node, destination)

dom/mutation.js, line 73

Insert node at end of destination.

Name	Type	Description
node	Node
destination	Element

attrs(elem){Map.<string, string>}

dom/attributes.js, line 31

Gets the attributes of the given element.

Correctly handles the case that IE7 and IE8 have approx 70-90
default attributes on each and every element.

Attribute values will always be strings, but possibly empty Strings.

Name	Type	Description
elem	Element

backward(node){Node}

dom/traversing.js, line 126

Given a node, will return the node that preceeds it in the document
order.

This backwards depth-first in-order traversal:
https://en.wikipedia.org/wiki/Tree_traversal#In-order

For example, if this function is called recursively, starting from the
DIV root node in the DOM tree below:

<div>
    "one"
    <b>
        "two"
        <u>
            <i>
                "three"
            </i>
        </u>
        "four"
    </b>
    "five"
</div>

backward() will return nodes in the following order:

"five", "four", "three", <i>, <u>, "two", <b>, "one"

        <div>
        / | \
      /   |   \
    one  <b>  five
        / | \
      /   |   \
    two  <u>  four
          |
         <i>
          |
        three

Name	Type	Description
node	Node

childAndParentsUntil(node, pred){Array.<Node>}

dom/traversing.js, line 538

Collects all ancestors of the given node until the first ancestor that
causes the given predicate function to return true.

Name	Type	Description
node	Node
pred	function	Predicate function which will receive nodes as they are traversed. This function returns `true`, it will terminate the traversal.

Returns:

set of parent element of the given node.

childAndParentsUntilIncl(node, pred){Array.<Node>}

dom/traversing.js, line 559

Collects the given node, and all its ancestors until the first ancestor
that causes the given predicate function to return true.

Name	Type	Description
node	Node
pred	function	Predicate function which will receive nodes as they are traversed. This function returns `true`, it will terminate the traversal.

Returns:

set of parent element of the given node.

childAndParentsUntilInclNode(node, untilInclNode){Array.<Node>}

dom/traversing.js, line 593

Collects the given node, and all its ancestors until `untilInclNode` is
reached.

Name	Type	Description
node	Node
untilInclNode	Node	Terminal ancestor. Will be included in results.

Returns:

set of parent element of the given node.

childAndParentsUntilNode(node, untilNode){Array.<Node>}

dom/traversing.js, line 576

Collects all ancestors of the given node until `untilNode` is reached.

Name	Type	Description
node	Node
untilNode	Node	Terminal ancestor.

Returns:

set of parent element of the given node.

children(elem){Array.<Node>}

dom/nodes.js, line 93

Returns a non-live array of all child nodes belonging to `elem`.

Name	Type	Description
elem	Element

climbUntil(node, func, until, arg)

dom/traversing.js, line 421

Climbs up the given node's ancestors until the predicate until() returns
true. Starting with the given node, applies func() to each node in the
traversal.

Name	Type	Description
node	Node
func	function
until	function
arg	*	A value that will be passed to `func()` as the second argument.

clone(node, deeply){Node}

dom/nodes.js, line 380

Returns a deep clone of the given node.

Name	Type	Description
node	Node
deeply	boolean	Whether or not to do a deep clone

cloneShallow(node){Node}

dom/nodes.js, line 391

Returns a shallow clone of the given node.

Name	Type	Description
node	Node

contains(a, b){boolean}

dom/nodes.js, line 291

Returns `true` if node `b` is a descendant of node `a`, `false`
otherwise.

Name	Type	Description
a	Node
b	Node

See:

• http://ejohn.org/blog/comparing-document-position/
• http://www.quirksmode.org/blog/archives/2006/01/contains_for_mo.html

TODO

• Contains seems to be problematic on Safari, is this an issue for us?
  Should we just use compareDocumentPosition() since we only need IE > 9 anyway?
  https://code.google.com/p/google-web-toolkit/issues/detail?id=1218

copy(nodes, destination, until){Array.<Nodes>}

dom/mutation.js, line 119

Copies the list of nodes into a destination element, until `until`
returns true.

Name	Type	Description
nodes	Array.<Nodes>
destination	Element
until	function

Returns:

nodes that were not copied

documentWindow(doc){Window}

dom.js, line 215

Gets the window to which the given document belongs.

Name	Type	Description
doc	Document

editableParent(node){Element}

dom.js, line 148

Finds the nearest editable ancestor of the given node.

Name	Type	Description
node	Node

editingHost(node){boolean}

dom.js, line 127

Gets the given node's editing host.

Name	Type	Description
node	Node

equals(node, other){boolean}

dom/nodes.js, line 368

Checks whether two nodes are equal.

Name	Type	Description
node	Node
other	Node

findBackward(node, match, until){Node}

dom/traversing.js, line 187

Finds the first DOM object, behind the given node which matches the
predicate `match`. If `until` returns true the given node, for any other
node during traversal, null is returned.

Name	Type	Description
node	Node
match	function
until	function

findForward(node, match, until){Node}

dom/traversing.js, line 172

Finds the first DOM object, ahead of the given node which matches the
predicate `match` but before `until` returns true for any node that is
traversed during the search, in which case null is returned.

Name	Type	Description
node	Node
match	function
until	function

followedBy(node, other){boolean}

dom/nodes.js, line 313

Checks whether node `other` comes after `node` in the document order.

Name	Type	Description
node	Node
other	Node

forward(node){Node}

dom/traversing.js, line 69

Given a node, will return the node that succeeds it in the document order.

For example, if this function is called recursively, starting from the
DIV root node in the following DOM tree:

<div>
    "one"
    <b>
        "two"
        <u>
            <i>
                "three"
            </i>
        </u>
        "four"
    </b>
    "five"
</div>

forward() will return nodes in the following order:

"one" <b>, "two", <u>, <i>, "three", "four", "five"

This is depth-first pre-order traversal:
https://en.wikipedia.org/wiki/Tree_traversal#Pre-order

        <div>
        / | \
      /   |   \
    one  <b>  five
        / | \
      /   |   \
    two  <u>  four
          |
         <i>
          |
        three

Name	Type	Description
node	Node

getAttr()

dom/attributes.js, line 83

This function is missing documentation.

TODO

• Complete documentation.

getAttrNS()

dom/attributes.js, line 93

This function is missing documentation.

TODO

• Complete documentation.

getComputedStyle(elem, name){string}

dom/style.js, line 82

Gets the computed/inherited style of the given node.

Name	Type	Description
elem	Element
name	string	Style property name.

Returns:

style, or `null` if no such style is set

getComputedStyles(elem, names){Object.<string, string>}

dom/style.js, line 56

Gets a style from the given element's style attribute.
Note that this is different from the computed/inherited style.

The return value will be an object of computed style values mapped
agains their name.

Name	Type	Description
elem	Element
names	Array.<string>

getStyle(elem, name){string}

dom/style.js, line 38

Gets a style from the given element's style attribute.
Note that this is different from the computed/inherited style.

Name	Type	Description
elem	Element
name	string	Style property

Returns:

value or null if none is found

hasAttrs(node){boolean}

dom/attributes.js, line 140

Checks whether or not the given node contains one or more
attributes non-empty attributes.

Name	Type	Description
node	Node

hasChildren(element){boolean}

dom/nodes.js, line 136

Checks is `element` has children

Name	Type	Description
element	Element

hasClass(node, value){boolean}

dom/classes.js, line 69

Checks whether the given node has the specified class.

Name	Type	Description
node	Node
value	string

hasText(element){boolean}

dom/nodes.js, line 356

Checks the givne element has any textContent.

Name	Type	Description
element	Element

insert(node, ref, atEnd)

dom/mutation.js, line 28

Inserts the given node before `ref`, unless `atEnd` is true, in which
case `node` is inserted at the end of `ref` children nodes.

Name	Type	Description
node	Node
ref	Node
atEnd	boolean

insertAfter(node, ref)

dom/mutation.js, line 43

Inserts the given node after `ref`.

Name	Type	Description
node	Node
ref	Node

isContentEditable(node){boolean}

dom.js, line 68

Check if the given node's contentEditable attribute is `true`.

Name	Type	Description
node	Element

isEditable(node){boolean}

dom.js, line 85

Checks whether the given element is editable.

An element with the class "aloha-editable" is considered editable.

Name	Type	Description
node	Node

isEditableNode()

dom.js, line 116

This function is missing documentation.

TODO

• Complete documentation.

isEditingHost(node){boolean}

dom.js, line 42

Checks whether the given node is content editable. An editing host is a
node that is either an Element with a contenteditable attribute set to
the true state, or the Element child of a Document whose designMode is
enabled.

An element with the class "aloha-editable" is considered an editing host.

Name	Type	Description
node	Node

Returns:

if `node` is content editable.

isElementNode(node){boolean}

dom/nodes.js, line 57

Checks whether the given node is an Element.

Name	Type	Description
node	Node

isEmptyTextNode(node){boolean}

dom/nodes.js, line 178

Checks whether the given node is an empty text node, conveniently.

Name	Type	Description
node	Node

isFragmentNode(node){boolean}

dom/nodes.js, line 68

Checks whether the given node is an document fragment element.

Name	Type	Description
node	Node

isSameNode(node1, node2){boolean}

dom/nodes.js, line 189

Checks is `node1` is the same as `node2`.

Name	Type	Description
node1	Node
node2	Node

isTextNode(node){boolean}

dom/nodes.js, line 46

Returns `true` if `node` is a text node.

Name	Type	Description
node	Node

merge(left, right)

dom/mutation.js, line 255

Merges all contents of `right` into `left` by appending them to the end
of `left`, and then removing `right`.

Will not merge text nodes since this would require that ranges be
preserved.

Name	Type	Description
left	Node
right	Node

move(nodes, destination, until){Array.<Nodes>}

dom/mutation.js, line 103

Moves the list of nodes into the end of destination element, until
`until` returns true.

Name	Type	Description
nodes	Array.<Nodes>
destination	Element
until	function

Returns:

nodes that were not moved

moveAfter(nodes, reference, until){Array.<Nodes>}

dom/mutation.js, line 151

Moves the list of nodes after the reference element, until `until`
returns true.

Name	Type	Description
nodes	Array.<Nodes>
reference	Element
until	function

Returns:

nodes that were not moved

moveBefore(nodes, reference, until){Array.<Nodes>}

dom/mutation.js, line 135

Moves the list of nodes before the reference element, until `until`
returns true.

Name	Type	Description
nodes	Array.<Nodes>
reference	Element
until	function

Returns:

nodes that were not moved

moveNextAll(parent, first, reference)

dom/mutation.js, line 57

Like insertBefore, inserts node `first` into `parent` before
`reference`, except that it also inserts all the following siblings of
`first`.

Name	Type	Description
parent	Element
first	Node
reference	Node

nextNonAncestor(start, previous, match, until){Node}

dom/traversing.js, line 615

Returns the nearest node (in the document order) to the given node that
is not an ancestor.

Name	Type	Description
start	Node
previous	boolean	If true, will look for the nearest preceding node, otherwise the nearest subsequent node.
match	function
until	function	(Optional) Predicate, which will be applied to each node in the traversal step. If this function returns true, traversal will terminal and will return null.

nextSibling(node){Node}

dom/traversing.js, line 255

Returns the given node's next sibling.

Name	Type	Description
node	Node

nextSiblings(node, until){Array.<Node>}

dom/traversing.js, line 683

Returns a non-live list of the given node's subsequent siblings until the
predicate returns true. The node one which `until` terminates is not
included.

Name	Type	Description
node	Node
until	function

nextUntil(node, func, until, arg)

dom/traversing.js, line 397

Applies the given function `func()`, to the the given node `node` and
it's next siblings, until the given `until()` function retuns `true` or
all next siblings have been walked.

Name	Type	Description
node	Node
func	function	Callback function to apply to the traversed nodes. Will receive the each node as the first argument, and the value of `arg` as the second argument.
until	function	Predicate function to test each traversed nodes. Walking will be terminated when this function returns `true`. Will receive the each node as the first argument, and the value of `arg` as the second argument.
arg	*	A value that will be passed to `func()` as the second argument.

nextWhile(node, cond, arg){Node}

dom/traversing.js, line 345

Starting from the given node and moving forward, traverses the set of
`node`'s sibiling nodes until either the predicate `cond` returns false
or the last sibling of `node`'s parent element is reached.

Name	Type	Description
node	Node
cond	function
arg	*	Optional arbitrary value that will be passed to `cond()`

nodeAndNextSiblings(node, until){Array.<Node>}

dom/traversing.js, line 718

Returns a non-live list of any of the given node and it's subsequent
siblings until the predicate returns true. The node one which `until`
terminates is not included.

Name	Type	Description
node	Node
until	function

nodeAndPrevSiblings(node, until){Array.<Node>}

dom/traversing.js, line 704

Returns a non-live list of any of the given node and it's preceeding
siblings until the predicate returns true. The node one which `until`
terminates is not included.

Name	Type	Description
node	Node
until	function

nodeAtOffset(node)

dom/nodes.js, line 162

This function is missing documentation.

Name	Type	Description
node		if a text node, should have a parent node.

TODO

• Complete documentation.

nodeIndex(node){number}

dom/nodes.js, line 105

Calculates the positional index of the given node inside of its parent
element.

Name	Type	Description
node	Node

Returns:

zero-based index of the given node's position.

nodeLength(node){number}

dom/nodes.js, line 120

Determines the length of the given DOM node.

Name	Type	Description
node	Node

Returns:

of the given node.

normalizedNodeIndex()

dom/nodes.js, line 261

This function is missing documentation.

TODO

• Complete documentation.

normalizedNthChild()

dom/nodes.js, line 271

This function is missing documentation.

TODO

• Complete documentation.

normalizedNumChildren()

dom/nodes.js, line 251

This function is missing documentation.

TODO

• Complete documentation.

nthChild(elem, offset){Element}

dom/nodes.js, line 151

Get the nth (zero based) child of the given element.

NB elem.childNodes.length is unreliable because "IE up to 8 does not count
empty text nodes." (http://www.quirksmode.org/dom/w3c_core.html)

Name	Type	Description
elem	Element
offset	number	Offset of the child to return.

Returns:

child node at the given offset.

numChildren(elem){number}

dom/nodes.js, line 82

Calculates the number of child nodes contained in the given DOM element.

NB elem.childNodes.length is unreliable because "IE up to 8 does not count
empty text nodes." (http://www.quirksmode.org/dom/w3c_core.html)

Name	Type	Description
elem	Element

Returns:

of children contained in the given node.

offset(node){Object.<string, number>}

dom/nodes.js, line 324

Calculates the offset of the given node inside the document.

Name	Type	Description
node	Node

outerHtml(node){string}

dom/nodes.js, line 405

Retrieve the HTML of the entire given node.
This is equivalent as outerHTML for element nodes.
This function is an alternative for outerHTML with for document
fragments.

Name	Type	Description
node	Node

parentsUntil(node, pred){Array.<Node>}

dom/traversing.js, line 493

Traverses up the given node's ancestors, collecting all parent nodes,
until the given predicate returns true.

Name	Type	Description
node	Node
pred	function	Predicate function which will receive nodes as they are traversed. This function returns `true`, it will terminate the traversal.

Returns:

set of parent elements of the given node.

parentsUntilIncl(node, pred){Array.<Node>}

dom/traversing.js, line 517

Starting with the given node, traverses up the given node's ancestors,
collecting each parent node, until the first ancestor that causes the
given predicate function to return true. The given node is *not* passed
to the predicate (@see childAndParents).

Name	Type	Description
node	Node
pred	function	Predicate function which will receive nodes as they are traversed. This function returns `true`, it will terminate the traversal.

Returns:

set of parent element of the given node.

prevSibling(node){Node}

dom/traversing.js, line 266

Returns the given node's previous sibling.

Name	Type	Description
node	Node

prevSiblings(node, until){Array.<Node>}

dom/traversing.js, line 662

Returns a non-live list of the given node's preceeding siblings until the
predicate returns true. The node one which `until` terminates is not
included.

Name	Type	Description
node	Node
until	function

prevUntil()

dom/traversing.js, line 405

Like nextUntil() but in reverse.

prevWhile(node, cond, arg){Node}

dom/traversing.js, line 362

Starting from the given node and moving backwards, traverses the set of
`node`'s sibilings until either the predicate `cond` returns false or we
reach the last sibling of `node`'s parent element.

Name	Type	Description
node	Node
cond	function
arg	*	Optional arbitrary value that will be passed to the `cond()` predicate.

query(selector, context){Array.<Node>}

dom/traversing.js, line 648

Executes a query selection (-all) in the given context and returns a
non-live list of results.

Name	Type	Description
selector	string
context	Element

realFromNormalizedIndex()

dom/nodes.js, line 237

This function is missing documentation.

TODO

• Complete documentation.

remove(node)

dom/mutation.js, line 195

Detaches the given node.

Name	Type	Description
node	Node

removeAttr()

dom/attributes.js, line 49

This function is missing documentation.

TODO

• Complete documentation.

removeAttrNS()

dom/attributes.js, line 103

This function is missing documentation.

TODO

• Complete documentation.

removeAttrs(element)

dom/attributes.js, line 59

Removes all attributes from `element`.

Name	Type	Description
element	Element

removeChildren(node)

dom/mutation.js, line 240

Removes all children from `node`.

Name	Type	Description
node	Node

removeClass(elem, className)

dom/classes.js, line 56

Removes one or more class names from the given element's
classList.

Name	Type	Description
elem	Element
className	string	repeatable

removeShallow(node)

dom/mutation.js, line 205

Removes the given node while keeping it's content intact.

Name	Type	Description
node	Node

removeStyle(elem, styleName)

dom/style.js, line 109

Removes the given style property from the given DOM element.

The style attribute is removed completely if it is left empty
after removing the style.

Name	Type	Description
elem	Element
styleName	string

replace(node, replacement){Node}

dom/mutation.js, line 166

Replaces the given node with `replacement`.

Name	Type	Description
node	Node
replacement	Node

Returns:

node

replaceShallow(element, replacement){Element}

dom/mutation.js, line 184

Replaces the given element while preserving its contents.

This function facilitates re-wrapping of contents from one element to
another.

The element that replaces `element` will receive all of the given
element's content.

Name	Type	Description
element	Element
replacement	Element

Returns:

element

scrollLeft(doc){number}

dom.js, line 243

Returns scroll position from left.

Name	Type	Description
doc	Document

scrollTop(doc){number}

dom.js, line 226

Returns scroll position from top.

Name	Type	Description
doc	Document

setAttr()

dom/attributes.js, line 69

This function is missing documentation.

TODO

• Complete documentation.

setAttrNS(elem, ns, name, value)

dom/attributes.js, line 123

NB: Internet Explorer supports the setAttributeNS method from
version 9, but only for HTML documents, not for XML documents.

Name	Type	Description
elem	Element
ns	string
name	string
value	string

setStyle(elem, name){string}

dom/style.js, line 20

Sets a style on the given element by modifying its style attribute.

Name	Type	Description
elem	Element
name	string	Style property

Returns:

Style property value

stepNextUntil(node, step, next, cond, arg){Node}

dom/traversing.js, line 329

Steps through the node tree acording to `step` and `next` until the
given condition is true.

Name	Type	Description
node	Node
step	function
next	function
cond	function
arg	*

text(node){string}

dom/nodes.js, line 345

Gets the textContent from a node.

Name	Type	Description
node	Node

upWhile(node, cond){Node}

dom/traversing.js, line 374

Traverse up node's ancestor chain while the given condition is true.

Name	Type	Description
node	Node
cond	function

walk(node, fn, arg)

dom/traversing.js, line 438

Applies the given function `func()`, to the the given node `node` and all
it's next siblings.

Name	Type	Description
node	Node
fn	function	Callback function to apply to the traversed nodes. Will receive the each node as the first argument, and the value of `arg` as the second argument.
arg	*	A value that will be passed to `func()` as the second argument.

walkRec(node, func){*}

dom/traversing.js, line 450

Depth-first postwalk of the given DOM node.

Name	Type	Description
node	Node
func	function

walkUntilNode(node, fn, untilNode, arg)

dom/traversing.js, line 475

Applies the given function `func()`, to the the given node `node` and
it's next siblings, until `untilNode` is encountered or the last sibling
is reached.

Name	Type	Description
node	Node
fn	function	Callback function to apply to the traversed nodes. Will receive the each node as the first argument, and the value of `arg` as the second argument.
untilNode	Node	Terminal node.
arg	*	A value that will be passed to `func()` as the second argument.

wrap(node, wrapper)

dom/mutation.js, line 217

Wraps `node` in given `wrapper` element.

Name	Type	Description
node	Node
wrapper	Element

wrapWith(node, nodeName){Element}

dom/mutation.js, line 229

Wrap the node with a `nodeName` element.

Name	Type	Description
node	Element
nodeName	string

Returns:

wrapper element