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 |`, `String className`) : void | Dom
Adds a class name to a given element or collection of elements.
| batch([`String |`], `Function method`, [`Any o`], [`Boolean override`]) : HTMLElement | 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 |`], [`String prefix`]) : String | Dom
Generates a unique ID
| get(`String |`) : HTMLElement | 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 |`]) : 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 |`]) : Array | Dom
Returns a array of HTMLElements with the given class. For optimized performance, include a tag and/or root node when ...
| getRegion(`String |`) : Region | 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 |`, `String property`) : String | 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 |`) : String | 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 |`) : 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 |`) : String | 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 |`, `String className`) : Boolean | Dom
Determines whether an HTMLElement has the given className.
| inDocument(`String |`) : Boolean | Dom
Determines whether an HTMLElement is present in the current document.
| isAncestor(`String |`, `String |`) : Boolean | Dom
Determines whether an HTMLElement is an ancestor of another HTML element in the DOM hierarchy.
| removeClass(`String |`, `String className`) : void | Dom
Removes a class name from a given element or collection of elements.
| replaceClass(`String |`, `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 |`, `String property`, `String val`) : void | Dom
Wrapper for setting style properties of HTMLElements. Normalizes "opacity" across modern browsers.
| setX(`String |`, `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 |`, `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 |`, `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 |`, `String 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
- `className` : String
  the class name to add to the class attribute

Returns:

- `void`

This method is defined by Dom.

### batch

`public function batch([`String |`], `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:

- `|` : String
  HTMLElement | Array} el (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 |`], [`String 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).
- `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 |`)`
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.

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 |`])`
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
- `|` : String
  HTMLElement} root (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 |`])`
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
- `|` : 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

This method is defined by Dom.

### getRegion

`public function getRegion(`String |`)`
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.

This method is defined by Dom.

### getStyle

`public function getStyle(`String |`, `String 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.
- `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 |`)`
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)

This method is defined by Dom.

### getXY

`public function getXY(`String |`)`
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)

This method is defined by Dom.

### getY

`public function getY(`String |`)`
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)

This method is defined by Dom.

### hasClass

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

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

This method is defined by Dom.

### isAncestor

`public function isAncestor(`String |`, `String |`)`
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

This method is defined by Dom.

### removeClass

`public function removeClass(`String |`, `String 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
- `className` : String
  the class name to remove from the class attribute

Returns:

- `void`

This method is defined by Dom.

### replaceClass

`public function replaceClass(`String |`, `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:

- `|` : String
  HTMLElement | Array} el 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 |`, `String property`, `String 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.
- `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 |`, `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:

- `|` : String
  HTMLElement | Array} el 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 |`, `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:

- `|` : String
  HTMLElement | Array} el 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 |`, `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:

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

Copyright © 2006 Jack Slocum. All rights reserved.