Namespace YAHOO.util.Dom

YAHOO.util Provides helper methods for DOM elements.
Defined in: dom.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	YAHOO.util.Dom Provides helper methods for DOM elements.

Method Summary
Method Attributes	Method Name and Description
<static>	YAHOO.util.Dom.addClass(el, className) Adds a class name to a given element or collection of elements.
<static>	YAHOO.util.Dom.batch(el, method, o, override) Returns an array of elements that have had the supplied method applied.
<static>	YAHOO.util.Dom.generateId(el, prefix) Generates a unique ID
<static>	YAHOO.util.Dom.get(el) Returns an HTMLElement reference.
<static>	YAHOO.util.Dom.getClientHeight() Returns the height of the client (viewport).
<static>	YAHOO.util.Dom.getClientWidth() Returns the width of the client (viewport).
<static>	YAHOO.util.Dom.getDocumentHeight() Returns the height of the document.
<static>	YAHOO.util.Dom.getDocumentWidth() Returns the width of the document.
<static>	YAHOO.util.Dom.getElementsBy(method, tag, root) Returns a array of HTMLElements that pass the test applied by supplied boolean method.
<static>	YAHOO.util.Dom.getElementsByClassName(className, tag, root) Returns a array of HTMLElements with the given class.
<static>	YAHOO.util.Dom.getRegion(el) Returns the region position of the given element.
<static>	YAHOO.util.Dom.getStyle(el, property) Normalizes currentStyle and ComputedStyle.
<static>	YAHOO.util.Dom.getViewportHeight() Returns the current height of the viewport.
<static>	YAHOO.util.Dom.getViewportWidth() Returns the current width of the viewport.
<static>	YAHOO.util.Dom.getX(el) Gets the current X position of an element based on page coordinates.
<static>	YAHOO.util.Dom.getXY(el) Gets the current position of an element based on page coordinates.
<static>	YAHOO.util.Dom.getY(el) Gets the current Y position of an element based on page coordinates.
<static>	YAHOO.util.Dom.hasClass(el, className) Determines whether an HTMLElement has the given className.
<static>	YAHOO.util.Dom.inDocument(el) Determines whether an HTMLElement is present in the current document.
<static>	YAHOO.util.Dom.isAncestor(haystack, needle) Determines whether an HTMLElement is an ancestor of another HTML element in the DOM hierarchy.
<static>	YAHOO.util.Dom.removeClass(el, className) Removes a class name from a given element or collection of elements.
<static>	YAHOO.util.Dom.replaceClass(el, oldClassName, newClassName) Replace a class with another class for a given element or collection of elements.
<static>	YAHOO.util.Dom.setStyle(el, property, val) Wrapper for setting style properties of HTMLElements.
<static>	YAHOO.util.Dom.setX(el, x) Set the X position of an html element in page coordinates, regardless of how the element is positioned.
<static>	YAHOO.util.Dom.setXY(el, pos, noRetry) Set the position of an html element in page coordinates, regardless of how the element is positioned.
<static>	YAHOO.util.Dom.setY(el, x) Set the Y position of an html element in page coordinates, regardless of how the element is positioned.

Namespace Detail

YAHOO.util.Dom

Provides helper methods for DOM elements.

Method Detail

<static> YAHOO.util.Dom.addClass(el, className)

Adds a class name to a given element or collection of elements.

Parameters:
{String | HTMLElement | Array} el: The element or collection to add the class to
{String} className: the class name to add to the class attribute

<static> {HTMLElement | Array} YAHOO.util.Dom.batch(el, method, o, override)

Returns an array of elements that have had the supplied method applied. The method is called with the element(s) as the first arg, and the optional param as the second ( method(el, o) ).

Parameters:
{String | HTMLElement | Array} el: (optional) An element or array of elements to apply the method to
{Function} method: The method to apply to the element(s)
{Any} o: (optional) An optional arg that is passed to the supplied method
{Boolean} override: (optional) Whether or not to override the scope of "method" with "o"

Returns:: {HTMLElement | Array} The element(s) with the method applied

<static> {String | Array} YAHOO.util.Dom.generateId(el, prefix)

Generates a unique ID

Parameters:
{String | HTMLElement | Array} el: (optional) An optional element array of elements to add an ID to (no ID is added if one is already present).
{String} prefix: (optional) an optional prefix to use (defaults to "yui-gen").

Returns:: {String | Array} The generated ID, or array of generated IDs (or original ID if already present on an element)

<static> {HTMLElement | Array} YAHOO.util.Dom.get(el)

Returns an HTMLElement reference.

Parameters:
{String | HTMLElement |Array} el: Accepts a string to use as an ID for getting a DOM reference, an actual DOM reference, or an Array of IDs and/or HTMLElements.

Returns:: {HTMLElement | Array} A DOM reference to an HTML element or an array of HTMLElements.

<static> {Int} YAHOO.util.Dom.getClientHeight()

Returns the height of the client (viewport).

Deprecated:
Now using getViewportHeight. This interface left intact for back compat.

Returns:: {Int} The height of the viewable area of the page.

<static> {Int} YAHOO.util.Dom.getClientWidth()

Returns the width of the client (viewport).

Deprecated:
Now using getViewportWidth. This interface left intact for back compat.

Returns:: {Int} The width of the viewable area of the page.

<static> {Int} YAHOO.util.Dom.getDocumentHeight()

Returns the height of the document.

Returns:: {Int} The height of the actual document (which includes the body and its margin).

<static> {Int} YAHOO.util.Dom.getDocumentWidth()

Returns the width of the document.

Returns:: {Int} The width of the actual document (which includes the body and its margin).

<static> YAHOO.util.Dom.getElementsBy(method, tag, root)

Returns a array of HTMLElements that pass the test applied by supplied boolean method. For optimized performance, include a tag and/or root node when possible.

Parameters:
{Function} method: - A boolean method for testing elements which receives the element as its only argument.
{String} tag: (optional) The tag name of the elements being collected
{String | HTMLElement} root: (optional) The HTMLElement or an ID to use as the starting point

<static> {Array} YAHOO.util.Dom.getElementsByClassName(className, tag, root)

Returns a array of HTMLElements with the given class. For optimized performance, include a tag and/or root node when possible.

Parameters:
{String} className: The class name to match against
{String} tag: (optional) The tag name of the elements being collected
{String | HTMLElement} root: (optional) The HTMLElement or an ID to use as the starting point

Returns:: {Array} An array of elements that have the given class name

<static> {Region | Array} YAHOO.util.Dom.getRegion(el)

Returns the region position of the given element. The element must be part of the DOM tree to have a region (display:none or elements not appended return false).

Parameters:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.

Returns:: {Region | Array} A Region or array of Region instances containing "top, left, bottom, right" member data.

<static> {String | Array} YAHOO.util.Dom.getStyle(el, property)

Normalizes currentStyle and ComputedStyle.

Parameters:
{String | HTMLElement |Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.
{String} property: The style property whose value is returned.

Returns:: {String | Array} The current value of the style property for the element(s).

<static> {Int} YAHOO.util.Dom.getViewportHeight()

Returns the current height of the viewport.

Returns:: {Int} The height of the viewable area of the page (excludes scrollbars).

<static> {Int} YAHOO.util.Dom.getViewportWidth()

Returns the current width of the viewport.

Returns:: {Int} The width of the viewable area of the page (excludes scrollbars).

<static> {String | Array} YAHOO.util.Dom.getX(el)

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

Parameters:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements

Returns:: {String | Array} The X position of the element(s)

<static> {Array} YAHOO.util.Dom.getXY(el)

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:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements

Returns:: {Array} The XY position of the element(s)

<static> {String | Array} YAHOO.util.Dom.getY(el)

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:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements

Returns:: {String | Array} The Y position of the element(s)

<static> {Boolean | Array} YAHOO.util.Dom.hasClass(el, className)

Determines whether an HTMLElement has the given className.

Parameters:
{String | HTMLElement | Array} el: The element or collection to test
{String} className: the class name to search for

Returns:: {Boolean | Array} A boolean value or array of boolean values

<static> {Boolean} YAHOO.util.Dom.inDocument(el)

Determines whether an HTMLElement is present in the current document.

Parameters:
{String | HTMLElement} el: The element to search for

Returns:: {Boolean} Whether or not the element is present in the current document

<static> {Boolean} YAHOO.util.Dom.isAncestor(haystack, needle)

Determines whether an HTMLElement is an ancestor of another HTML element in the DOM hierarchy.

Parameters:
{String | HTMLElement} haystack: The possible ancestor
{String | HTMLElement} needle: The possible descendent

Returns:: {Boolean} Whether or not the haystack is an ancestor of needle

<static> YAHOO.util.Dom.removeClass(el, className)

Removes a class name from a given element or collection of elements.

Parameters:
{String | HTMLElement | Array} el: The element or collection to remove the class from
{String} className: the class name to remove from the class attribute

<static> YAHOO.util.Dom.replaceClass(el, oldClassName, newClassName)

Replace a class with another class for a given element or collection of elements. If no oldClassName is present, the newClassName is simply added.

Parameters:
{String | HTMLElement | Array} el: The element or collection to remove the class from
{String} oldClassName: the class name to be replaced
{String} newClassName: the class name that will be replacing the old class name

<static> YAHOO.util.Dom.setStyle(el, property, val)

Wrapper for setting style properties of HTMLElements. Normalizes "opacity" across modern browsers.

Parameters:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.
{String} property: The style property to be set.
{String} val: The value to apply to the given property.

<static> YAHOO.util.Dom.setX(el, x)

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

Parameters:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.
{Int} x: The value to use as the X coordinate for the element(s).

<static> YAHOO.util.Dom.setXY(el, pos, noRetry)

Set the 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:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements
{Array} pos: Contains X & Y values for new position (coordinates are page-based)
{Boolean} noRetry: By default we try and set the position a second time if the first fails

<static> YAHOO.util.Dom.setY(el, x)

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

Parameters:
{String | HTMLElement | Array} el: Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.
{Int} x: To use as the Y coordinate for the element(s).

Classes

Namespace YAHOO.util.Dom