# Yahoo! UI Library

### dom 3.3.0

Yahoo! UI Library > dom > DOM
Search:
Filters Show Private Show Protected Show Deprecated

## Class DOM

Provides DOM helper methods.

### Methods

#### _bruteContains

`private Boolean _bruteContains ( element , needle )`
Brute force version of contains. Used for browsers without contains support for non-HTMLElement Nodes (textNodes, etc).

Parameters:
  `element <HTMLElement>` The containing html element.
  `needle <HTMLElement>` The html element that may be contained.

Returns: `Boolean`
  Whether or not the element is or contains the needle.

#### _getDoc

`private Object _getDoc ( element )`
returns the appropriate document.

Parameters:
  `element <HTMLElement>` optional Target element.

Returns: `Object`
  The document for the given element or the default document.

#### _getRegExp

`private RegExp _getRegExp ( str , flags )`
Memoizes dynamic regular expressions to boost runtime performance.

Parameters:
  `str <String>` The string to convert to a regular expression.
  `flags <String>` optional An optinal string of flags.

Returns: `RegExp`
  An instance of RegExp

#### _getWin

`private Object _getWin ( element )`
returns the appropriate window.

Parameters:
  `element <HTMLElement>` optional Target element.

Returns: `Object`
  The window for the given element or the default window.

#### addClass

`void addClass ( element , className )`
Adds a class name to a given DOM element.

Parameters:
  `element <HTMLElement>` The DOM element.
  `className <String>` the class name to add to the class attribute

#### addHTML

`void addHTML ( node , content , where )`
Inserts content in a node at the given location

Parameters:
  `node <HTMLElement>` The node to insert into
  `content <HTMLElement | Array | HTMLCollection>` The content to be inserted
  `where <HTMLElement>` Where to insert the content If no "where" is given, content is appended to the node Possible values for "where"
  HTMLElement
    The element to insert before
  "replace"
    Replaces the existing HTML
  "before"
    Inserts before the existing HTML
  "before"
    Inserts content before the node
  "after"
    Inserts content after the node

#### byId

`HTMLElement | null byId ( id , doc )`
Returns the HTMLElement with the given ID (Wrapper for document.getElementById).

Parameters:
  `id <String>` the id attribute
  `doc <Object>` optional The document to search. Defaults to current document

Returns: `HTMLElement | null`
  The HTMLElement with the id, or null if none found.

#### contains

`Boolean contains ( element , needle )`
Determines whether or not one HTMLElement is or contains another HTMLElement.

Parameters:
  `element <HTMLElement>` The containing html element.
  `needle <HTMLElement>` The html element that may be contained.

Returns: `Boolean`
  Whether or not the element is or contains the needle.

#### create

`HTMLElement|DocumentFragment create ( html , doc )`
Creates a new dom node using the provided markup string.

Parameters:
  `html <String>` The markup used to create the element
  `doc <HTMLDocument>` An optional document context

Returns: `HTMLElement|DocumentFragment`
  returns a single HTMLElement when creating one node, and a documentFragment when creating multiple nodes.

#### docHeight

`Number docHeight ( )`
Document height

Returns: `Number`
  The current height of the document.

#### docScrollX

`Number docScrollX ( )`
Amount page has been scroll horizontally

Returns: `Number`
  The current amount the screen is scrolled horizontally.

#### docScrollY

`Number docScrollY ( )`
Amount page has been scroll vertically

Returns: `Number`
  The current amount the screen is scrolled vertically.

#### docWidth

`Number docWidth ( )`
Document width

Returns: `Number`
  The current width of the document.

#### elementByAxis

`HTMLElement | null elementByAxis ( element , axis , fn , all )`
Searches the element by the given axis for the first matching element.

Parameters:
  `element <HTMLElement>` The html element.
  `axis <String>` The axis to search (parentNode, nextSibling, previousSibling).
  `fn <Function>` optional An optional boolean test to apply.
  `all <Boolean>` optional Whether all node types should be returned, or just element nodes. The optional function is passed the current HTMLElement being tested as its only argument. If no function is given, the first element is returned.

Returns: `HTMLElement | null`
  The matching element or null if none found.

#### getAttibute

`String getAttibute ( el , attr )`
Provides a normalized attribute interface.

Parameters:
  `el <HTMLElement>` The target element for the attribute.
  `attr <String>` The attribute to get.

Returns: `String`
  The current value of the attribute.

#### getComputedStyle

`String getComputedStyle ( An , att )`
Returns the computed style for the given node.

Parameters:
  `An <HTMLElement>` HTMLElement to get the style from.
  `att <String>` The style property to get.

Returns: `String`
  The computed value of the style property.

#### getStyle

`void getStyle ( An , att )`
Returns the current style value for the given property.

Parameters:
  `An <HTMLElement>` HTMLElement to get the style from.
  `att <String>` The style property to get.

#### getText

`String getText ( element )`
Returns the text content of the HTMLElement.

Parameters:
  `element <HTMLElement>` The html element.

Returns: `String`
  The text content of the element (includes text of any descending elements).

#### getX

`Int getX ( element )`
Gets the current X position of an element based on page coordinates. Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

Parameters:
  `element <object>` The target element

Returns: `Int`
  The X position of the element

#### getXY

`Array getXY ( element )`
Gets the current position of an element based on page coordinates. Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

Parameters:
  `element <object>` The target element

Returns: `Array`
  The XY position of the element TODO: test inDocument/display?

#### getY

`Int getY ( element )`
Gets the current Y position of an element based on page coordinates. Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

Parameters:
  `element <object>` The target element

Returns: `Int`
  The Y position of the element

#### hasClass

`Boolean hasClass ( element , className )`
Determines whether a DOM element has the given className.

Parameters:
  `element <HTMLElement>` The DOM element.
  `className <String>` the class name to search for

Returns: `Boolean`
  Whether or not the element has the given class.

#### inDoc

`Boolean inDoc ( element , doc )`
Determines whether or not the HTMLElement is part of the document.

Parameters:
  `element <HTMLElement>` The containing html element.
  `doc <HTMLElement>` optional The document to check.

Returns: `Boolean`
  Whether or not the element is attached to the document.

#### inRegion

`Boolean inRegion ( all , altRegion )`
Check if any part of this node is in the passed region

Parameters:
  `all <Object} node2 The node to get the region from or an Object literal of the region $param {Boolean>` Should all of the node be inside the region
  `altRegion <Object>` An object literal containing the region for this node if we already have the data (for performance i.e. DragDrop)

Returns: `Boolean`
  True if in region, false if not.

#### intersect

`Object intersect ( element , element2 , altRegion )`
Find the intersect information for the passes nodes.

Parameters:
  `element <HTMLElement>` The first element
  `element2 <HTMLElement | Object>` The element or region to check the interect with
  `altRegion <Object>` An object literal containing the region for the first element if we already have the data (for performance i.e. DragDrop)

Returns: `Object`
  Object literal containing the following intersection data: (top, right, bottom, left, area, yoff, xoff, inRegion)

#### inViewportRegion

`Boolean inViewportRegion ( element , all , altRegion )`
Check if any part of this element is in the viewport

Parameters:
  `element <HTMLElement>` The DOM element.
  `all <Boolean>` Should all of the node be inside the region
  `altRegion <Object>` An object literal containing the region for this node if we already have the data (for performance i.e. DragDrop)

Returns: `Boolean`
  True if in region, false if not.

#### region

`Object region ( element )`
Returns an Object literal containing the following about this element: (top, right, bottom, left)

Parameters:
  `element <HTMLElement>` The DOM element.

Returns: `Object`
  Object literal containing the following about this element: (top, right, bottom, left)

#### removeClass

`void removeClass ( element , className )`
Removes a class name from a given element.

Parameters:
  `element <HTMLElement>` The DOM element.
  `className <String>` the class name to remove from the class attribute

#### replaceClass

`void replaceClass ( element , oldClassName , newClassName )`
Replace a class with another class for a given element. If no oldClassName is present, the newClassName is simply added.

Parameters:
  `element <HTMLElement>` The DOM element
  `oldClassName <String>` the class name to be replaced
  `newClassName <String>` the class name that will be replacing the old class name

#### setAttibute

`void setAttibute ( el , attr , val )`
Provides a normalized attribute interface.

Parameters:
  `el <HTMLElement>` The target element for the attribute.
  `attr <String>` The attribute to set.
  `val <String>` The value of the attribute.

#### setHeight

`void setHeight ( element , size )`
Sets the height of the element to the given size, regardless of box model, border, padding, etc.

Parameters:
  `element <HTMLElement>` The DOM element.
  `size <String|Int>` The pixel height to size to

#### setStyle

`void setStyle ( An , att , val )`
Sets a style property for a given element.

Parameters:
  `An <HTMLElement>` HTMLElement to apply the style to.
  `att <String>` The style property to set.
  `val <String|Number>` The value.

#### setStyles

`void setStyles ( node , hash )`
Sets multiple style properties.

Parameters:
  `node <HTMLElement>` An HTMLElement to apply the styles to.
  `hash <Object>` An object literal of property:value pairs.

#### setText

`void setText ( element , content )`
Sets the text content of the HTMLElement.

Parameters:
  `element <HTMLElement>` The html element.
  `content <String>` The content to add.

#### setWidth

`void setWidth ( element , size )`
Sets the width of the element to the given size, regardless of box model, border, padding, etc.

Parameters:
  `element <HTMLElement>` The DOM element.
  `size <String|Int>` The pixel height to size to

#### setX

`void setX ( element , x )`
Set the X position of an html element in page coordinates, regardless of how the element is positioned. The element(s) must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

Parameters:
  `element <object>` The target element
  `x <Int>` The X values for new position (coordinates are page-based)

#### setXY

`void setXY ( element , xy , noRetry )`
Set the position of an html element in page coordinates. The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

Parameters:
  `element <object>` The target element
  `xy <Array>` Contains X & Y values for new position (coordinates are page-based)
  `noRetry <Boolean>` By default we try and set the position a second time if the first fails

#### setY

`void setY ( element , y )`
Set the Y position of an html element in page coordinates, regardless of how the element is positioned. The element(s) must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

Parameters:
  `element <object>` The target element
  `y <Int>` The Y values for new position (coordinates are page-based)

#### swapXY

`Node swapXY ( node , otherNode )`
Swap the xy position with another node

Parameters:
  `node <Node>` The node to swap with
  `otherNode <Node>` The other node to swap with

#### toggleClass

`void toggleClass ( element , className , addClass )`
If the className exists on the node it is removed, if it doesn't exist it is added.

Parameters:
  `element <HTMLElement>` The DOM element
  `className <String>` the class name to be toggled
  `addClass <Boolean>` optional boolean to indicate whether class should be added or removed regardless of current state

#### viewportRegion

`Object viewportRegion ( )`
Returns an Object literal containing the following about the visible region of viewport: (top, right, bottom, left)

Returns: `Object`
  Object literal containing the following about the visible region of the viewport: (top, right, bottom, left)

#### winHeight

`Number winHeight ( )`
Returns the inner height of the viewport (exludes scrollbar).

Returns: `Number`
  The current height of the viewport.

#### winWidth

`Number winWidth ( )`
Returns the inner width of the viewport (exludes scrollbar).

Returns: `Number`
  The current width of the viewport.

Copyright © 2011 Yahoo! Inc. All rights reserved.