dom.js is part of Aloha Editor project http://www.alohaeditor.org
Aloha Editor ● JavaScript Content Editing Library
Copyright (c) 2010-2015 Gentics Software GmbH, Vienna, Austria.
Contributors http://www.alohaeditor.org/docs/contributing.html
Aloha Editor ● JavaScript Content Editing Library
Copyright (c) 2010-2015 Gentics Software GmbH, Vienna, Austria.
Contributors http://www.alohaeditor.org/docs/contributing.html
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
-
Calculates the absolute left position
of an elementName Type Description element
Element -
Calculates the absolute top position
of an elementName Type Description element
Element -
addClass(elem, className)
-
Adds one or more classes to current classes of the given Element.
Name Type Description elem
Element className
string repeatable -
append(node, destination)
-
Insert node at end of destination.
Name Type Description node
Node destination
Element -
attrs(elem){Map.<string, string>}
-
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}
-
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>
|
threeName Type Description node
Node -
childAndParentsUntil(node, pred){Array.<Node>}
-
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>}
-
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>}
-
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>}
-
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>}
-
Returns a non-live array of all child nodes belonging to `elem`.
Name Type Description elem
Element -
climbUntil(node, func, until, arg)
-
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}
-
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}
-
Returns a shallow clone of the given node.
Name Type Description node
Node -
contains(a, b){boolean}
-
Returns `true` if node `b` is a descendant of node `a`, `false`
otherwise.Name Type Description a
Node b
Node - See:
- 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
- Contains seems to be problematic on Safari, is this an issue for us?
-
copy(nodes, destination, until){Array.<Nodes>}
-
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
-
Gets the window to which the given document belongs.
Name Type Description doc
Document -
Finds the nearest editable ancestor of the given node.
Name Type Description node
Node -
Gets the given node's editing host.
Name Type Description node
Node -
equals(node, other){boolean}
-
Checks whether two nodes are equal.
Name Type Description node
Node other
Node -
findBackward(node, match, until){Node}
-
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}
-
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}
-
Checks whether node `other` comes after `node` in the document order.
Name Type Description node
Node other
Node -
forward(node){Node}
-
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>
|
threeName Type Description node
Node -
getAttr()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
getAttrNS()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
getComputedStyle(elem, name){string}
-
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>}
-
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}
-
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}
-
Checks whether or not the given node contains one or more
attributes non-empty attributes.Name Type Description node
Node -
hasChildren(element){boolean}
-
Checks is `element` has children
Name Type Description element
Element -
hasClass(node, value){boolean}
-
Checks whether the given node has the specified class.
Name Type Description node
Node value
string -
hasText(element){boolean}
-
Checks the givne element has any textContent.
Name Type Description element
Element -
insert(node, ref, atEnd)
-
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)
-
Inserts the given node after `ref`.
Name Type Description node
Node ref
Node -
Check if the given node's contentEditable attribute is `true`.
Name Type Description node
Element -
Checks whether the given element is editable.
An element with the class "aloha-editable" is considered editable.Name Type Description node
Node -
This function is missing documentation.
- TODO
-
- Complete documentation.
-
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}
-
Checks whether the given node is an Element.
Name Type Description node
Node -
isEmptyTextNode(node){boolean}
-
Checks whether the given node is an empty text node, conveniently.
Name Type Description node
Node -
isFragmentNode(node){boolean}
-
Checks whether the given node is an document fragment element.
Name Type Description node
Node -
isSameNode(node1, node2){boolean}
-
Checks is `node1` is the same as `node2`.
Name Type Description node1
Node node2
Node -
isTextNode(node){boolean}
-
Returns `true` if `node` is a text node.
Name Type Description node
Node -
merge(left, right)
-
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>}
-
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>}
-
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>}
-
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)
-
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}
-
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}
-
Returns the given node's next sibling.
Name Type Description node
Node -
nextSiblings(node, until){Array.<Node>}
-
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)
-
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}
-
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>}
-
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>}
-
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)
-
This function is missing documentation.
Name Type Description node
if a text node, should have a parent node. - TODO
-
- Complete documentation.
-
nodeIndex(node){number}
-
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}
-
Determines the length of the given DOM node.
Name Type Description node
Node Returns:
of the given node.
-
normalizedNodeIndex()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
normalizedNthChild()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
normalizedNumChildren()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
nthChild(elem, offset){Element}
-
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}
-
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>}
-
Calculates the offset of the given node inside the document.
Name Type Description node
Node -
outerHtml(node){string}
-
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>}
-
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>}
-
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}
-
Returns the given node's previous sibling.
Name Type Description node
Node -
prevSiblings(node, until){Array.<Node>}
-
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()
-
Like nextUntil() but in reverse.
-
prevWhile(node, cond, arg){Node}
-
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>}
-
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()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
remove(node)
-
Detaches the given node.
Name Type Description node
Node -
removeAttr()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
removeAttrNS()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
removeAttrs(element)
-
Removes all attributes from `element`.
Name Type Description element
Element -
removeChildren(node)
-
Removes all children from `node`.
Name Type Description node
Node -
removeClass(elem, className)
-
Removes one or more class names from the given element's
classList.Name Type Description elem
Element className
string repeatable -
removeShallow(node)
-
Removes the given node while keeping it's content intact.
Name Type Description node
Node -
removeStyle(elem, styleName)
-
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}
-
Replaces the given node with `replacement`.
Name Type Description node
Node replacement
Node Returns:
node
-
replaceShallow(element, replacement){Element}
-
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
-
Returns scroll position from left.
Name Type Description doc
Document -
Returns scroll position from top.
Name Type Description doc
Document -
setAttr()
-
This function is missing documentation.
- TODO
-
- Complete documentation.
-
setAttrNS(elem, ns, name, value)
-
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}
-
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}
-
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}
-
Gets the textContent from a node.
Name Type Description node
Node -
upWhile(node, cond){Node}
-
Traverse up node's ancestor chain while the given condition is true.
Name Type Description node
Node cond
function -
walk(node, fn, arg)
-
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){*}
-
Depth-first postwalk of the given DOM node.
Name Type Description node
Node func
function -
walkUntilNode(node, fn, untilNode, arg)
-
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)
-
Wraps `node` in given `wrapper` element.
Name Type Description node
Node wrapper
Element -
wrapWith(node, nodeName){Element}
-
Wrap the node with a `nodeName` element.
Name Type Description node
Element nodeName
string Returns:
wrapper element