Home

# Library goog.dom

Function Summary
| `DomSavedControlRange_(?goog.dom.ControlRange range)` A SavedRange implementation using DOM endpoints.
| `DomSavedMultiRange_(?goog.dom.MultiRange range)` A SavedRange implementation using DOM endpoints.
| `DomSavedTextRange_(?goog.dom.AbstractRange range)` A SavedRange implementation using DOM endpoints.
| `append(!Node parent, (goog.dom.Appendable|null|undefined) var_args)` Appends a node with text or other nodes.
| `appendChild(?Node parent, ?Node child)` Appends a child to a node.
| `append_(!Document doc, !Node parent, !Arguments args, number startIndex)` Appends a node with text or other nodes.

`canHaveChildren(?Node node) ⇒ boolean`

Determines if the given node can contain children, intended to be used for HTML generation. IE natively supports node.canHaveChildren but has inconsistent behavior. Prior to IE8 the base tag allows children and in IE9 all nodes return true for canHaveChildren. In practice all non-IE browsers allow you to add children to any node, but the behavior is inconsistent:

    var a = document.createElement('br');
    a.appendChild(document.createTextNode('foo'));
    a.appendChild(document.createTextNode('bar'));
    console.log(a.childNodes.length);  // 2
    console.log(a.innerHTML);  // Chrome: "", IE9: "foobar", FF3.5: "foobar"

TODO(user): Rename shouldAllowChildren() ?

| `canUseQuerySelector_((Document|Element|null) parent) ⇒ boolean` Prefer the standardized (http://www.w3.org/TR/selectors-api/), native and fast W3C Selectors API. However, the version of WebKit that shipped with Safari 3.1 and Chrome has a bug where it will not correctly match mixed- case class name selectors in quirks mode.
| `compareNodeOrder(?Node node1, ?Node node2) ⇒ number` Compares the document order of two nodes, returning 0 if they are the same node, a negative number if node1 is before node2, and a positive number if node2 is before node1. Note that we compare the order the tags appear in the document so in the tree text the B node is considered to be before the I node.
| `compareParentsDescendantNodeIe_(?Node textNode, ?Node node) ⇒ number` Utility function to compare the position of two nodes, when {@code textNode}'s parent is an ancestor of {@code node}. If this entry condition is not met, this function will attempt to reference a null object.
| `compareSiblingOrder_(?Node node1, ?Node node2) ⇒ number` Utility function to compare the position of two nodes known to be non-equal siblings.
| `contains(?Node parent, ?Node descendant) ⇒ boolean` Whether a node contains another node.

`createDom(string tagName, (Object|null|string=) opt_attributes, (NodeList|Object|null|string|undefined) var_args) ⇒ !Element`

Returns a dom node with a set of attributes. This function accepts varargs for subsequent nodes to be added. Subsequent nodes will be added to the first node as childNodes. So: `createDom('div', null, createDom('p'), createDom('p'));` would return a div with two child paragraphs

| `createDom_(!Document doc, !Arguments args) ⇒ !Element` Helper for {@code createDom}.
| `createElement(string name) ⇒ !Element` Creates a new element.
| `createTable(number rows, number columns, boolean= opt_fillWithNbsp) ⇒ !Element` Create a table.
| `createTable_(!Document doc, number rows, number columns, boolean fillWithNbsp) ⇒ !Element` Create a table.
| `createTextNode(string content) ⇒ !Text` Creates a new text node.
| `findCommonAncestor((Node|null|undefined) var_args) ⇒ ?Node` Find the deepest common ancestor of the given nodes.

`findNode(?Node root, function ((Node|null)): boolean p) ⇒ (Node|null|undefined)`

Finds the first descendant node that matches the filter function, using a depth first search. This function offers the most general purpose way of finding a matching element. You may also wish to consider {@code goog.dom.query} which can express many matching criteria using CSS selector expressions. These expressions often result in a more compact representation of the desired result.

`findNodes(?Node root, function ((Node|null)): boolean p) ⇒ ?Array`

Finds all the descendant nodes that match the filter function, using a a depth first search. This function offers the most general-purpose way of finding a set of matching elements. You may also wish to consider {@code goog.dom.query} which can express many matching criteria using CSS selector expressions. These expressions often result in a more compact representation of the desired result.

| `findNodes_(?Node root, function ((Node|null)): boolean p, ?Array rv, boolean findOne) ⇒ boolean` Finds the first or all the descendant nodes that match the filter function, using a depth first search.
| `flattenElement(?Element element) ⇒ (Element|null|undefined)` Flattens an element. That is, removes it and replace it with its children. Does nothing if the element is not in the document.
| `getActiveElement(?Document doc) ⇒ ?Element` Determines the active element in the given document.
| `getAncestor(?Node element, function ((Node|null)): boolean matcher, boolean= opt_includeNode, number= opt_maxSearchSteps) ⇒ ?Node` Walks up the DOM hierarchy returning the first ancestor that passes the matcher function.
| `getAncestorByClass(?Node element, ?string= opt_class) ⇒ ?Node` Walks up the DOM hierarchy returning the first ancestor that has the passed class name. If the passed element matches the specified criteria, the element itself is returned.
| `getAncestorByTagNameAndClass(?Node element, ?string= opt_tag, ?string= opt_class) ⇒ ?Node` Walks up the DOM hierarchy returning the first ancestor that has the passed tag name and/or class name. If the passed element matches the specified criteria, the element itself is returned.
| `getChildren(?Element element) ⇒ (Array|NodeList|null)` Returns an array containing just the element children of the given element.
| `getCompatMode() ⇒ string` Returns the compatMode of the document.
| `getDocument() ⇒ !Document` Gets the document object being used by the dom library.
| `getDocumentHeight() ⇒ number` Calculates the height of the document.
| `getDocumentHeight_(?Window win) ⇒ number` Calculates the height of the document of the given window. Function code copied from the opensocial gadget api: gadgets.window.adjustHeight(opt_height)
| `getDocumentScroll() ⇒ !goog.math.Coordinate` Gets the document scroll distance as a coordinate object.
| `getDocumentScrollElement() ⇒ ?Element` Gets the document scroll element.
| `getDocumentScrollElement_(!Document doc) ⇒ ?Element` Helper for {@code getDocumentScrollElement}.
| `getDocumentScroll_(!Document doc) ⇒ !goog.math.Coordinate` Helper for {@code getDocumentScroll}.
| `getDomHelper((Node|Window|null=) opt_element) ⇒ !goog.dom.DomHelper` Gets the DomHelper object for the document where the element resides.
| `getElement((Element|null|string) element) ⇒ ?Element` Alias for getElementById. If a DOM node is passed in then we just return that.
| `getElementByClass(string className, (Document|Element|null=) opt_el) ⇒ ?Element` Returns the first element with the provided className.
| `getElementsByClass(string className, (Document|Element|null=) opt_el) ⇒ {length: number}` Returns an array of all the elements with the provided className.

`getElementsByTagNameAndClass(?string= opt_tag, ?string= opt_class, (Document|Element|null=) opt_el) ⇒ {length: number}`

Looks up elements by both tag and class name, using browser native functions ({@code querySelectorAll}, {@code getElementsByTagName} or {@code getElementsByClassName}) where possible. This function is a useful, if limited, way of collecting a list of DOM elements with certain characteristics. {@code goog.dom.query} offers a more powerful and general solution which allows matching on CSS3 selector expressions, but at increased cost in code size. If all you need is particular tags belonging to a single class, this function is fast and sleek.

| `getElementsByTagNameAndClass_(!Document doc, ?string= opt_tag, ?string= opt_class, (Document|Element|null=) opt_el) ⇒ {length: number}` Helper for {@code getElementsByTagNameAndClass}.
| `getFirstElementChild(?Node node) ⇒ ?Element` Returns the first child node that is an element.
| `getFrameContentDocument(?Element frame) ⇒ !Document` Cross-browser function for getting the document element of a frame or iframe.
| `getFrameContentWindow((HTMLFrameElement|HTMLIFrameElement|null) frame) ⇒ ?Window` Cross-browser function for getting the window of a frame or iframe.
| `getLastElementChild(?Node node) ⇒ ?Element` Returns the last child node that is an element.
| `getNextElementNode_(?Node node, boolean forward) ⇒ ?Element` Returns the first node that is an element in the specified direction, starting with {@code node}.
| `getNextElementSibling(?Node node) ⇒ ?Element` Returns the first next sibling that is an element.
| `getNextNode(?Node node) ⇒ ?Node` Returns the next node in source order from the given node.
| `getNodeAtOffset(?Node parent, number offset, ?Object= opt_result) ⇒ ?Node` Returns the node at a given offset in a parent node. If an object is provided for the optional third parameter, the node and the remainder of the offset will stored as properties of this object.
| `getNodeTextLength(?Node node) ⇒ number` Returns the text length of the text contained in a node, without markup. This is equivalent to the selection length if the node was selected, or the number of cursor movements to traverse the node. Images & BRs take one space. New lines are ignored.
| `getNodeTextOffset(?Node node, ?Node= opt_offsetParent) ⇒ number` Returns the text offset of a node relative to one of its ancestors. The text length is the same as the length calculated by goog.dom.getNodeTextLength.
| `getOuterHtml(?Element element) ⇒ string` Gets the outerHTML of a node, which islike innerHTML, except that it actually contains the HTML of the node itself.
| `getOwnerDocument((Node|Window|null) node) ⇒ !Document` Returns the owner document for a node.
| `getPageScroll(?Window= opt_window) ⇒ !goog.math.Coordinate` Gets the page scroll distance as a coordinate object.
| `getParentElement(?Element element) ⇒ ?Element` Returns an element's parent, if it's an Element.
| `getPreviousElementSibling(?Node node) ⇒ ?Element` Returns the first previous sibling that is an element.
| `getPreviousNode(?Node node) ⇒ ?Node` Returns the previous node in source order from the given node.
| `getRawTextContent(?Node node) ⇒ string` Returns the text content of the current node, without markup. Unlike {@code getTextContent} this method does not collapse whitespaces or normalize lines breaks.
| `getTextContent(?Node node) ⇒ string` Returns the text content of the current node, without markup and invisible symbols. New lines are stripped and whitespace is collapsed, such that each character would be visible. In browsers that support it, innerText is used. Other browsers attempt to simulate it via node traversal. Line breaks are canonicalized in IE.
| `getTextContent_(?Node node, ?Array buf, boolean normalizeWhitespace)` Recursive support function for text content retrieval.

`getViewportSize(?Window= opt_window) ⇒ !goog.math.Size`

Gets the dimensions of the viewport. Gecko Standards mode: docEl.clientWidth Width of viewport excluding scrollbar. win.innerWidth Width of viewport including scrollbar. body.clientWidth Width of body element. docEl.clientHeight Height of viewport excluding scrollbar. win.innerHeight Height of viewport including scrollbar. body.clientHeight Height of document. Gecko Backwards compatible mode: docEl.clientWidth Width of viewport excluding scrollbar. win.innerWidth Width of viewport including scrollbar. body.clientWidth Width of viewport excluding scrollbar. docEl.clientHeight Height of document. win.innerHeight Height of viewport including scrollbar. body.clientHeight Height of viewport excluding scrollbar. IE6/7 Standards mode: docEl.clientWidth Width of viewport excluding scrollbar. win.innerWidth Undefined. body.clientWidth Width of body element. docEl.clientHeight Height of viewport excluding scrollbar. win.innerHeight Undefined. body.clientHeight Height of document element. IE5 + IE6/7 Backwards compatible mode: docEl.clientWidth 0. win.innerWidth Undefined. body.clientWidth Width of viewport excluding scrollbar. docEl.clientHeight 0. win.innerHeight Undefined. body.clientHeight Height of viewport excluding scrollbar. Opera 9 Standards and backwards compatible mode: docEl.clientWidth Width of viewport excluding scrollbar. win.innerWidth Width of viewport including scrollbar. body.clientWidth Width of viewport excluding scrollbar. docEl.clientHeight Height of document. win.innerHeight Height of viewport including scrollbar. body.clientHeight Height of viewport excluding scrollbar. WebKit: Safari 2 docEl.clientHeight Same as scrollHeight. docEl.clientWidth Same as innerWidth. win.innerWidth Width of viewport excluding scrollbar. win.innerHeight Height of the viewport including scrollbar. frame.innerHeight Height of the viewport exluding scrollbar. Safari 3 (tested in 522) docEl.clientWidth Width of viewport excluding scrollbar. docEl.clientHeight Height of viewport excluding scrollbar in strict mode. body.clientHeight Height of viewport excluding scrollbar in quirks mode.

| `getViewportSize_(?Window win) ⇒ !goog.math.Size` Helper for {@code getViewportSize}.
| `getWindow(?Document= opt_doc) ⇒ !Window` Gets the window object associated with the given document.
| `getWindow_(!Document doc) ⇒ !Window` Helper for {@code getWindow}.
| `htmlToDocumentFragment(string htmlString) ⇒ !Node` Converts an HTML string into a document fragment.
| `htmlToDocumentFragment_(!Document doc, string htmlString) ⇒ !Node` Helper for {@code htmlToDocumentFragment}.
| `insertChildAt(?Element parent, ?Node child, number index)` Insert a child at a given index. If index is larger than the number of child nodes that the parent currently has, the node is inserted as the last child node.
| `insertSiblingAfter(?Node newNode, ?Node refNode)` Inserts a new node after an existing reference node (i.e. as the next sibling). If the reference node has no parent, then does nothing.
| `insertSiblingBefore(?Node newNode, ?Node refNode)` Inserts a new node before an existing reference node (i.e. as the previous sibling). If the reference node has no parent, then does nothing.
| `isCss1CompatMode() ⇒ boolean` Returns true if the browser is in "CSS1-compatible" (standards-compliant) mode, false otherwise.
| `isCss1CompatMode_(?Document doc) ⇒ boolean` Returns true if the browser is in "CSS1-compatible" (standards-compliant) mode, false otherwise.
| `isElement(<Any Type> obj) ⇒ boolean` Whether the object looks like an Element.
| `isFocusableTabIndex(?Element element) ⇒ boolean` Returns true if the element has a tab index that allows it to receive keyboard focus (tabIndex >= 0), false otherwise. Note that form elements natively support keyboard focus, even if they have no tab index.
| `isNodeLike(<Any Type> obj) ⇒ boolean` Whether the object looks like a DOM node.
| `isNodeList(?Object val) ⇒ boolean` Returns true if the object is a {@code NodeList}. To qualify as a NodeList, the object must have a numeric length property and an item function (which has type 'string' on IE for some reason).
| `isWindow(<Any Type> obj) ⇒ boolean` Returns true if the specified value is a Window object. This includes the global window for HTML pages, and iframe windows.
| `removeChildren(?Node node)` Removes all the child nodes on a DOM node.
| `removeNode(?Node node) ⇒ ?Node` Removes a node from its parent.
| `replaceNode(?Node newNode, ?Node oldNode)` Replaces a node in the DOM tree. Will do nothing if {@code oldNode} has no parent.
| `setFocusableTabIndex(?Element element, boolean enable)` Enables or disables keyboard focus support on the element via its tab index. Only elements for which {@link goog.dom.isFocusableTabIndex} returns true (or elements that natively support keyboard focus, like form elements) can receive keyboard focus. See http://go/tabindex for more info.
| `setProperties(?Element element, ?Object properties)` Sets multiple properties on a node.
| `setTextContent(?Element element, string text)` Cross-browser function for setting the text content of an element.