Getting Started

To use the Dom Collection, include the following source files in your web page with the script tag:

<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/dom/dom-min.js"></script>
 

<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/dom/dom-min.js"></script>
 

YAHOO.util.Dom is a Singleton class that does not require instantiation. Simply access the methods you need from YAHOO.util.Dom (e.g., YAHOO.util.Dom.getXY("myElementId"), YAHOO.util.Dom.getStyle("myElementId"), etc.)

Using the Dom Collection

This section describes several common uses of the Dom Collection. It contains these subsections:

• Quick Start
• Positioning HTML Elements
• Getting and Setting Styles
• Getting the Viewport Size
• Managing Class Names

Quick Start

// #test: Find the element with an id of 'test' and store it in a variable
var element = YAHOO.util.Dom.get('test');
 
// .test: Get all elements with class 'test' (will be an array if there's more than one)
var elements = YAHOO.util.Dom.getElementsByClassName('test');
 
// div.test: Get all divs with class 'test'
var elements = YAHOO.util.Dom.getElementsByClassName('test', 'div');
 
// Get the first element with class 'test'
var element = YAHOO.util.Dom.getElementsByClassName('test')[0];
 
// p: Get all p elements with the native DOM method getElementsByTagName
var elements = document.getElementsByTagName('p');
 
// Get the first p element
var element = document.getElementsByTagName('p')[0];
 

// #test: Find the element with an id of 'test' and store it in a variable
var element = YAHOO.util.Dom.get('test');
 
// .test: Get all elements with class 'test' (will be an array if there's more than one)
var elements = YAHOO.util.Dom.getElementsByClassName('test');
 
// div.test: Get all divs with class 'test'
var elements = YAHOO.util.Dom.getElementsByClassName('test', 'div');
 
// Get the first element with class 'test'
var element = YAHOO.util.Dom.getElementsByClassName('test')[0];
 
// p: Get all p elements with the native DOM method getElementsByTagName
var elements = document.getElementsByTagName('p');
 
// Get the first p element
var element = document.getElementsByTagName('p')[0];
 

Positioning HTML Elements

Depending on how an HTML element is positioned in the document, getting its current page coordinates can be a challenge. The Dom Collection's positioning methods (setXY(), getXY(), setX(), and so on) can be used to ensure accurate positioning. Page coordinates are defined in the context of the entire HTML document, including the portions beyond the browser chrome.

In the following example, the getXY method returns an array with the X and Y coordinates of the HTML element whose ID attribute is "test". The setXY method takes a second HTML element "target" and sets its coordinates to the coordinates of "test":

var pos = YAHOO.util.Dom.getXY('test');
YAHOO.util.Dom.setXY('target', pos);
 

var pos = YAHOO.util.Dom.getXY('test');
YAHOO.util.Dom.setXY('target', pos);
 

Getting and Setting Styles

The getStyle method allows you to retrieve properties of a given element's style object; the setStyle method allows you to set properties on an element's style object. In CSS, the opacity property is applied in various ways, depending on the browser; setStyle and getStyle normalize this as the opacity property. Note: CSS opacity was not supported in Opera prior to version 9.

In the following example, the setStyle method sets the HTML element with the id "test" and the element with the id "test2" to have an opacity of 0.5 (which is 50%; opacity is defined in the range between 0 and 1). The getStyle method returns the current opacity value of the HTML element with the id "test2".

YAHOO.util.Dom.setStyle(['test', 'test2'], 'opacity', 0.5);
var opacity = YAHOO.util.Dom.getStyle('test2', 'opacity');
 

YAHOO.util.Dom.setStyle(['test', 'test2'], 'opacity', 0.5);
var opacity = YAHOO.util.Dom.getStyle('test2', 'opacity');
 

Note that the above example also demonstrates how Dom Collection methods can be applied to more than one element in a single call.

Getting the Viewport Size

The viewport is defined as the current, visible width and height of the document, irrespective of the absolute document dimensions. Getting the current viewport size can be a bit of a challenge depending on browser and rendering mode. The getViewportWidth and getViewportHeight methods ensure accurate viewport measurements.

This example creates an array called viewport and populates it with the current viewport's dimensions:

var viewport = [
   YAHOO.util.Dom.getViewportWidth(),
   YAHOO.util.Dom.getViewportHeight()
];
 

var viewport = [
   YAHOO.util.Dom.getViewportWidth(),
   YAHOO.util.Dom.getViewportHeight()
];
 

Managing Class Names

The Dom Collection provides a number of methods to dynamically manage class names.

These include:

• getElementsByClassName(className, tagName, rootNode): Returns an array of elements that have the class name applied. Can be optionally scoped by tagName and/or a root node to increase performance.
• hasClass(element, className): Determines whether an element has the provided class name.
• addClass(element, className): Adds the provided class name to the element.
• removeClass(element, className): Removes the provided class name from the element.
• replaceClass(element, oldClassName, newClassName): Replaces one class name with another for the given element.

The following returns an array of div elements that have the class name "test":

var elements = YAHOO.util.Dom.getElementsByClassName('test', 'div');
 

var elements = YAHOO.util.Dom.getElementsByClassName('test', 'div');
 

YUI on Mobile: Using Dom Collection with "A-Grade" Mobile Browsers

Most of the Dom methods work as expected on the iPhone, with the exception of getViewportHeight/Width, which appear to return the size of the entire document rather than viewport.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.