YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Dom Collection

YUI 2: Dom Collection

The Dom Collection comprises a family of convenience methods that simplify common DOM-scripting tasks, including element positioning and CSS style management, while normalizing for cross-browser inconsistencies.

Getting Started

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

  1. <!-- Dependencies -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
  4. <!-- Source file -->
  5. <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>

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is dom. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

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

  1. // #test: Find the element with an id of 'test' and store it in a variable
  2. var element = YAHOO.util.Dom.get('test');
  4. // .test: Get all elements with class 'test' (will be an array if there's more than one)
  5. var elements = YAHOO.util.Dom.getElementsByClassName('test');
  7. // div.test: Get all divs with class 'test'
  8. var elements = YAHOO.util.Dom.getElementsByClassName('test', 'div');
  10. // Get the first element with class 'test'
  11. var element = YAHOO.util.Dom.getElementsByClassName('test')[0];
  13. // p: Get all p elements with the native DOM method getElementsByTagName
  14. var elements = document.getElementsByTagName('p');
  16. // Get the first p element
  17. 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":

  1. var pos = YAHOO.util.Dom.getXY('test');
  2. 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".

  1. YAHOO.util.Dom.setStyle(['test', 'test2'], 'opacity', 0.5);
  2. 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:

  1. var viewport = [
  2. YAHOO.util.Dom.getViewportWidth(),
  3. YAHOO.util.Dom.getViewportHeight()
  4. ];
var viewport = [

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":

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

About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:

  • Screen size: You have a much smaller canvas;
  • Input devices: Mobile devices generally do not have mouse input, and therefore are missing some or all mouse events (like mouseover);
  • Processor power: Mobile devices have slower processors that can more easily be saturated by JavaScript and DOM interactions — and processor usage affects things like battery life in ways that don't have analogues in desktop browsers;
  • Latency: Most mobile devices have a much higher latency on the network than do terrestrially networked PCs; this can make pages with many script, css or other types of external files load much more slowly.

There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.

More Information:

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.

Dom Collection Cheat Sheet:

Cheat Sheet for the Dom Colleciton.

Download full set of cheat sheets.

More Reading about the YUI Dom Collection:

YUI Dom Collection on del.icio.us:

bookmark on del.icio.us

be the first to bookmark this page!

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings