# Yahoo! UI Library

### dom 3.0.0b1

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

Returns: `void`

#### addHTML

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

Parameters:
  `node <HTMLElement>` The node to insert into
  `content <String>` The content to be inserted
  `where <String>` Where to insert the content; default is after lastChild

Returns: `void`

#### 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

`void 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: `void`

#### 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 <String | 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.

Returns: `void`

#### 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.

#### insertAfter

`HTMLElement insertAfter ( newNode , referenceNode )`
Inserts the new node as the next sibling of the reference node

Parameters:
  `newNode <String | HTMLElement>` The node to be inserted
  `referenceNode <String | HTMLElement>` The node to insert the new node after

Returns: `HTMLElement`
  The node that was inserted (or null if insert fails)

#### insertBefore

`HTMLElement insertBefore ( newNode , referenceNode )`
Inserts the new node as the previous sibling of the reference node

Parameters:
  `newNode <String | HTMLElement>` The node to be inserted
  `referenceNode <String | HTMLElement>` The node to insert the new node before

Returns: `HTMLElement`
  The node that was inserted (or null if insert fails)

#### 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

Returns: `void`

#### 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

Returns: `void`

#### setAttibute

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

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

Returns: `void`

#### 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.

Returns: `void`

#### 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.

Returns: `void`

#### setText

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

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

Returns: `void`

#### 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)

Returns: `void`

#### 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

Returns: `void`

#### 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)

Returns: `void`

#### toggleClass

`void toggleClass ( element , className )`
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

Returns: `void`

#### 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 © 2009 Yahoo! Inc. All rights reserved.