Print Friendly

# Class YAHOO.util.Dom

Package: | YAHOO.util
Class: | Dom
Extends: | Object
Defined In: | dom.js

Provides helper methods for DOM elements.

## Public Properties

This class has no public properties.

## Public Methods

Method | Defined By
--- | ---
| addClass(`String/HTMLElement/Array el`, `String className`) : void | Dom
Adds a class name to a given element or collection of elements.
| batch([`String/HTMLElement/Array el`], `Function method`, [`Any o`], [`Boolean override`]) : HTMLElement/Array | Dom
Returns an array of elements that have had the supplied method applied. The method is called with the element(s) as t...
| generateId([`String/HTMLElement/Array el`], [`String prefix`]) : String/Array | Dom
Generates a unique ID
| get(`String/HTMLElement |Array}`) : HTMLElement/Array | Dom
Returns an HTMLElement reference.
| getClientHeight() : Int | Dom
Deprecated. Returns the height of the client (viewport).
| getClientWidth() : Int | Dom
Deprecated. Returns the width of the client (viewport).
| getDocumentHeight() : Int | Dom
Returns the height of the document.
| getDocumentWidth() : Int | Dom
Returns the width of the document.
| getElementsBy(`Function method`, [`String tag`], [`String/HTMLElement root`]) : void | Dom
Returns a array of HTMLElements that pass the test applied by supplied boolean method. For optimized performance, inc...
| getElementsByClassName(`String className`, [`String tag`], [`String/HTMLElement root`]) : Array | Dom
Returns a array of HTMLElements with the given class. For optimized performance, include a tag and/or root node when ...
| getRegion(`String/HTMLElement/Array el`) : Region/Array | Dom
Returns the region position of the given element. The element must be part of the DOM tree to have a region (display:...
| getStyle(`String/HTMLElement |Array}`, `String property`) : String/Array | Dom
Normalizes currentStyle and ComputedStyle.
| getViewportHeight() : Int | Dom
Returns the current height of the viewport.
| getViewportWidth() : Int | Dom
Returns the current width of the viewport.
| getX(`String/HTMLElement/Array el`) : String/Array | Dom
Gets the current X position of an element based on page coordinates. The element must be part of the DOM tree to hav...
| getXY(`String/HTMLElement/Array el`) : Array | Dom
Gets the current position of an element based on page coordinates. Element must be part of the DOM tree to have page...
| getY(`String/HTMLElement/Array el`) : String/Array | Dom
Gets the current Y position of an element based on page coordinates. Element must be part of the DOM tree to have pa...
| hasClass(`String/HTMLElement/Array el`, `String className`) : Boolean/Array | Dom
Determines whether an HTMLElement has the given className.
| inDocument(`String/HTMLElement el`) : Boolean | Dom
Determines whether an HTMLElement is present in the current document.
| isAncestor(`String/HTMLElement haystack`, `String/HTMLElement needle`) : Boolean | Dom
Determines whether an HTMLElement is an ancestor of another HTML element in the DOM hierarchy.
| removeClass(`String/HTMLElement/Array el`, `String className`) : void | Dom
Removes a class name from a given element or collection of elements.
| replaceClass(`String/HTMLElement/Array el`, `String oldClassName`, `String newClassName`) : void | Dom
Replace a class with another class for a given element or collection of elements. If no oldClassName is present, the ...
| setStyle(`String/HTMLElement/Array el`, `String property`, `String val`) : void | Dom
Wrapper for setting style properties of HTMLElements. Normalizes "opacity" across modern browsers.
| setX(`String/HTMLElement/Array el`, `Int x`) : void | Dom
Set the X position of an html element in page coordinates, regardless of how the element is positioned. The element m...
| setXY(`String/HTMLElement/Array el`, `Array pos`, `Boolean noRetry`) : void | Dom
Set the position of an html element in page coordinates, regardless of how the element is positioned. The element(s) ...
| setY(`String/HTMLElement/Array el`, `Int x`) : void | Dom
Set the Y position of an html element in page coordinates, regardless of how the element is positioned. The element m...

## Public Events

This class has no public events.

## Method Details

### addClass

`public function addClass(`String/HTMLElement/Array el`, `String className`)`
Adds a class name to a given element or collection of elements.
Parameters:

- `el` : String/HTMLElement/Array
  The element or collection to add the class to
- `className` : String
  the class name to add to the class attribute

Returns:

- `void`

This method is defined by Dom.

### batch

`public function batch([`String/HTMLElement/Array el`], `Function method`, [`Any o`], [`Boolean 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:

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

Returns:

- `HTMLElement/Array`
  The element(s) with the method applied

This method is defined by Dom.

### generateId

`public function generateId([`String/HTMLElement/Array el`], [`String prefix`])`
Generates a unique ID
Parameters:

- `el` : String/HTMLElement/Array
  (optional) An optional element array of elements to add an ID to (no ID is added if one is already present).
- `prefix` : String
  (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)

This method is defined by Dom.

### get

`public function get(`String/HTMLElement |Array}`)`
Returns an HTMLElement reference.
Parameters:

- `|Array}` : String/HTMLElement
  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.

This method is defined by Dom.

### getClientHeight

`public function getClientHeight()`
Deprecated. Returns the height of the client (viewport).
Parameters:

- None.

Returns:

- `Int`
  The height of the viewable area of the page.

This method is defined by Dom.

### getClientWidth

`public function getClientWidth()`
Deprecated. Returns the width of the client (viewport).
Parameters:

- None.

Returns:

- `Int`
  The width of the viewable area of the page.

This method is defined by Dom.

### getDocumentHeight

`public function getDocumentHeight()`
Returns the height of the document.
Parameters:

- None.

Returns:

- `Int`
  The height of the actual document (which includes the body and its margin).

This method is defined by Dom.

### getDocumentWidth

`public function getDocumentWidth()`
Returns the width of the document.
Parameters:

- None.

Returns:

- `Int`
  The width of the actual document (which includes the body and its margin).

This method is defined by Dom.

### getElementsBy

`public function getElementsBy(`Function method`, [`String tag`], [`String/HTMLElement 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:

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

Returns:

- `void`

This method is defined by Dom.

### getElementsByClassName

`public function getElementsByClassName(`String className`, [`String tag`], [`String/HTMLElement root`])`
Returns a array of HTMLElements with the given class. For optimized performance, include a tag and/or root node when possible.
Parameters:

- `className` : String
  The class name to match against
- `tag` : String
  (optional) The tag name of the elements being collected
- `root` : String/HTMLElement
  (optional) The HTMLElement or an ID to use as the starting point

Returns:

- `Array`
  An array of elements that have the given class name

This method is defined by Dom.

### getRegion

`public function getRegion(`String/HTMLElement/Array 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:

- `el` : String/HTMLElement/Array
  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.

This method is defined by Dom.

### getStyle

`public function getStyle(`String/HTMLElement |Array}`, `String property`)`
Normalizes currentStyle and ComputedStyle.
Parameters:

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

Returns:

- `String/Array`
  The current value of the style property for the element(s).

This method is defined by Dom.

### getViewportHeight

`public function getViewportHeight()`
Returns the current height of the viewport.
Parameters:

- None.

Returns:

- `Int`
  The height of the viewable area of the page (excludes scrollbars).

This method is defined by Dom.

### getViewportWidth

`public function getViewportWidth()`
Returns the current width of the viewport.
Parameters:

- None.

Returns:

- `Int`
  The width of the viewable area of the page (excludes scrollbars).

This method is defined by Dom.

### getX

`public function getX(`String/HTMLElement/Array 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:

- `el` : String/HTMLElement/Array
  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)

This method is defined by Dom.

### getXY

`public function getXY(`String/HTMLElement/Array 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:

- `el` : String/HTMLElement/Array
  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)

This method is defined by Dom.

### getY

`public function getY(`String/HTMLElement/Array 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:

- `el` : String/HTMLElement/Array
  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)

This method is defined by Dom.

### hasClass

`public function hasClass(`String/HTMLElement/Array el`, `String className`)`
Determines whether an HTMLElement has the given className.
Parameters:

- `el` : String/HTMLElement/Array
  The element or collection to test
- `className` : String
  the class name to search for

Returns:

- `Boolean/Array`
  A boolean value or array of boolean values

This method is defined by Dom.

### inDocument

`public function inDocument(`String/HTMLElement el`)`
Determines whether an HTMLElement is present in the current document.
Parameters:

- `el` : String/HTMLElement
  The element to search for

Returns:

- `Boolean`
  Whether or not the element is present in the current document

This method is defined by Dom.

### isAncestor

`public function isAncestor(`String/HTMLElement haystack`, `String/HTMLElement needle`)`
Determines whether an HTMLElement is an ancestor of another HTML element in the DOM hierarchy.
Parameters:

- `haystack` : String/HTMLElement
  The possible ancestor
- `needle` : String/HTMLElement
  The possible descendent

Returns:

- `Boolean`
  Whether or not the haystack is an ancestor of needle

This method is defined by Dom.

### removeClass

`public function removeClass(`String/HTMLElement/Array el`, `String className`)`
Removes a class name from a given element or collection of elements.
Parameters:

- `el` : String/HTMLElement/Array
  The element or collection to remove the class from
- `className` : String
  the class name to remove from the class attribute

Returns:

- `void`

This method is defined by Dom.

### replaceClass

`public function replaceClass(`String/HTMLElement/Array el`, `String oldClassName`, `String 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:

- `el` : String/HTMLElement/Array
  The element or collection to remove the class from
- `oldClassName` : String
  the class name to be replaced
- `newClassName` : String
  the class name that will be replacing the old class name

Returns:

- `void`

This method is defined by Dom.

### setStyle

`public function setStyle(`String/HTMLElement/Array el`, `String property`, `String val`)`
Wrapper for setting style properties of HTMLElements. Normalizes "opacity" across modern browsers.
Parameters:

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

Returns:

- `void`

This method is defined by Dom.

### setX

`public function setX(`String/HTMLElement/Array el`, `Int 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:

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

Returns:

- `void`

This method is defined by Dom.

### setXY

`public function setXY(`String/HTMLElement/Array el`, `Array pos`, `Boolean 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:

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

This method is defined by Dom.

### setY

`public function setY(`String/HTMLElement/Array el`, `Int 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:

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

Returns:

- `void`

This method is defined by Dom.

yui-ext - Copyright © 2006 Jack Slocum. | Yahoo! UI - Copyright © 2006 Yahoo! Inc.
All rights reserved.