YUI 3: The Node Utility

Node Utility

Getting Started

Include Dependencies

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

<!-- Source file --> <script src="http://yui.yahooapis.com/3.0.0b1/build/yui/yui-min.js" type="text/javascript"></script>

Getting a Node

Node is the primary method for interacting with DOM elements in YUI 3. It works much the same as a normal HTMLElement. The simplest way to get a Node instance is using your YUI instance's get method.

Y.get accepts either an existing DOM element or a selector query. If a selector query is used, the first matching element is used.

Note: CSS3 selector support is not included by default with Node, you will need to include the "selector-css3" module for CSS3 support.

This example demonstrates the two ways to get a node.

YUI().use('node', function(Y) { var node1 = Y.get('#main'); var node2 = Y.get(document.body); });

Using Node

This section describes how to use the Node Utility in further detail. It contains these subsections:

• Accessing Node Properties
• DOM Events
• DOM Methods
• NodeList
• Node Queries

Accessing Node Properties

Properties of the underlying DOM node are accessed via the Y.Node instance's set and get methods. For simple property types (strings, numbers, booleans), these pass directly to/from the underlying node, but properties that normally return DOM nodes return Y.Node instances instead.

This is an example of getting and setting various properties.

YUI().use('node', function(Y) { var node = Y.get('#foo'); var parent = node.get('parentNode'); // Node instance var html = 'I am "' + node.get('id') + '".'; html += 'My parent is "' + parent.get('id') + '"'; node.set('innerHTML', html); });

DOM Events

DOM events can be listened for using the on method (an alias for attach).

Event handlers receive a normalized event object as their argument.

Note that all fields of the event object that would normally be DOM elements are now Y.Node instances.

YUI().use('node', function(Y) { Y.get('#demo').on('click', function(e) { e.preventDefault(); alert('event: ' + e.type + ' target: ' + e.target.get('tagName')); }); });

DOM Methods

The Y.Node api provides all of the DOM methods you would expect, plus a few extras to help with common tasks.

As with properties and events, any methods that would normally return DOM nodes instead return Y.Node instances.

YUI().use('node', function(Y) { var node = Y.get('#demo'); var node2 = node.appendChild(Y.get('#foo p')); node2.addClass('bar'); });

Using NodeList

The Y.NodeList provides a node-like interface for manipulating multiple nodes through a single interface. A zero length collection will return null. This, coupled with the fact that all Node instances have the NodeList api applies allows return values from Y.get and Y.all to be consumed by the same code transparently.

The Y.all method is the simplest way to get a NodeList.

YUI().use('node', function(Y) { Y.all('#demo li').addClass('bar'); });

The Y.Node api returns NodeList instances when the DOM would normally return a collection of elements. For symmetry with the Y.Node api, zero length collections return null.

YUI().use('node', function(Y) { Y.get('#demo').get('children').addClass('bar'); });

Node Queries

Selector queries are a powerful way to test and manipulate nodes. All Y.Node instances support query, queryAll, and test.

YUI().use('node', function(Y) { var node = Y.get('#demo'); var node2 = node.query('p'); if (node2) { // might be null node2.addClass('bar'); // adds "bar" to the first P descendant of #demo } node.queryAll('p').addClass('bar'); // adds "bar" to all P descendants of #demo if (node.test('.foo.bar')) { // "if node has both foo and bar classNames" node.removeClass('bar'); } });

For more information on selector queries, see the following W3C specifications:

• CSS Level 3 Selectors
• Selectors API

Note: CSS3 selector support is not included by default with Node, you will need to include the "selector-css3" module for CSS3 support.

ARIA Support

The Node interface has support for ARIA, and when used with Node's built-in support for CSS Selector queries, makes it easy to both apply and manage a Node's roles, states and properties.

The ARIA Roles, States and Properties enhance the semantics of HTML, allowing developers to more accurately describe the intended purpose of a region of a page, or a DHTML widget, thereby improving the user experience for users of assistive technology, such as screen readers.

Apply any of the ARIA Roles, States and Properties via the set method. For example, to apply the role of toolbar to a <div> with an id of "toolbar":

YUI().use('node', function(Y) { var node = Y.get('#toolbar').set('role', 'toolbar'); });

Node's built-in support for CSS selector queries, method chaining, and ability to set multiple attributes on a single Node instance makes it especially easy to apply the ARIA Roles, States, and Properties when building DHTML widgets with a large subtree. For example, when building a menubar widget it is necessary to apply a role of menubar to the root DOM element representing the menubar, and the role of menu to the root DOM element representing each submenu. Additionally, as each submenu is hidden by default, the of aria-hidden state will need to be applied to each submenu as well. The Node interface makes it possible to do all of this in one line of code:

YUI().use('node', function(Y) { Y.get('#rootmenu').set('role', 'menubar').queryAll('.menu').setAttrs({ role: 'menu', 'aria-hidden': true }); });

Migration Table

Most of the functionality from YAHOO.util.Dom is now available via Node

Note In the snippets below, myNode is an instance of Node. Methods that normally would return DOM nodes now return Node instances.

2.x (via YAHOO.util.Dom)	3.0
addClass	myNode.addClass
batch	NodeList[methodName], NodeList.each, or Y.each
generateId	Y.guid
get	Y.get Note strings are now treated as selectors (e.g. "Y.get('#foo')" vs. "YAHOO.util.Dom.get('foo')")
getAncestorBy	myNode.ancestor
getAncestorByClassName	myNode.ancestor
getAncestorByTagName	myNode.ancestor
getChildren	myNode.get('children')
getChildrenBy	myNode.queryAll
getClientRegion	myNode.get('viewportRegion')
getDocumentHeight	myNode.get('docHeight')
getDocumentScrollLeft	myNode.get('docScrollX')
getDocumentScrollTop	myNode.get('docscrollY')
getDocumentWidth	myNode.get('docWidth')
getElementsBy	myNode.queryAll
getElementsByClassName	myNode.queryAll
getFirstChild	myNode.query
getFirstChildBy	myNode.query
getLastChild	myNode.query
getLastChildBy	myNode.query
getNextSibling	myNode.next
getNextSiblingBy	myNode.next
getPreviousSibling	myNode.previous
getPreviousSiblingBy	myNode.previous
getRegion	myNode.get('region')
getStyle	myNode.getStyle
getViewportHeight	myNode.get('winHeight')
getViewportWidth	myNode.get('winWidth')
getX	myNode.getXY
getY	myNode.getXY
getXY	myNode.getXY
hasClass	myNode.hasClass
inDocument	myNode.inDoc
insertAfter	TBD
insertBefore	TBD
isAncestor	myNode.contains (Note myNode.contains(myNode) === true)
removeClass	myNode.removeClass
replaceClass	myNode.replaceClass
setStyle	myNode.setStyle
setX	myNode.setXY
setY	myNode.setXY
setXY	myNode.setXY

Support & Community

Forum & Blog

There is a dedicated mailing list for YUI 3. Click the link to visit the list, or use the form below to subscribe:

You might also be interested in the general YUI list: ydn-javascript.

In addition, please visit the 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.