460N/A<div class="intro">

460N/A <p>

460N/A The Node Utility provides an expressive way to collect, create, and

460N/A manipulate DOM nodes. Each `Node` instance represents an underlying

460N/A DOM node, and each `NodeList` represents a collection of DOM nodes.

460N/A With `Node`, you can manage classNames

460N/A </p>

460N/A

460N/A ```

460N/A myNode.addClass('highlight');

460N/A ```

460N/A

460N/A <p>styles</p>

460N/A

460N/A ```

460N/A myNode.setStyle('opacity', 0.5);

460N/A ```

460N/A

460N/A <p>create elements</p>

460N/A

460N/A ```

460N/A Y.Node.create('<li id="item3" class="highlight"><em>Profit</em></li>');

783N/A ```

460N/A

460N/A <p>and much more.</p>

460N/A

460N/A <p>

783N/A <strong>Note:</strong> The <em>`Y.get()`, `node.query()`, and

783N/A `node.queryAll()` methods have been removed. Use `Y.one()`,

460N/A `node.one()`, and `node.all()` or include the

460N/A "<a href="{{apiDocs}}/modules/node-deprecated.html">node-deprecated</a>"

618N/A module in your `use()` statement to restore them</em>.

460N/A </p>

460N/A

844N/A</div>

844N/A

460N/A{{>getting-started}}

460N/A

460N/A<h2 id="node-using">Using Node</h2>

460N/A

460N/A<h3 id="using-node">Getting a Node</h3>

460N/A

460N/A<p>

460N/A `Node` is the interface for DOM operations in YUI 3. The Node API is

460N/A based on the standard DOM API, and provides additional sugar properties

460N/A and methods that make common operations easier, and implementation code

460N/A more concise. Developers familiar with the standard DOM API will find

460N/A Node instances to be very familiar.

460N/A</p>

460N/A

460N/A<p>

460N/A The simplest way to get a `Node` instance is using your YUI instance's

460N/A `one` method. `Y.one` accepts either an existing DOM element or a selector

460N/A query. If a selector query is used, the first matching element is used.

460N/A</p>

460N/A

460N/A<p>

460N/A <strong>Note:</strong> CSS3 selector support is not included by default

460N/A with Node, you will need to include the "selector-css3" module for CSS3

460N/A support.

460N/A</p>

460N/A

460N/A<p>This example demonstrates two ways to get a node instance.</p>

460N/A

460N/A```

460N/Avar node1 = Y.one('#main');

460N/Avar node2 = Y.one(document.body);

460N/A```

460N/A

460N/A<h3 id="node-properties">Accessing Node Properties</h3>

460N/A

460N/A<p>

460N/A Properties of the underlying DOM node are accessed via the `Y.Node`

460N/A instance's `set` and `get` methods. For simple property types (strings,

460N/A numbers, booleans), these pass directly to/from the underlying node, but

460N/A properties that normally return DOM nodes return `Y.Node` instances

460N/A instead.

460N/A</p>

460N/A

460N/A<p>This is an example of getting and setting various properties.</p>

460N/A

460N/A```

460N/Avar node = Y.one('#foo');

460N/Avar parent = node.get('parentNode'); // Node instance

460N/A

460N/Avar html = 'I am "' + node.get('id') + '".';

460N/Ahtml += 'My parent is "' + parent.get('id') + '"';

460N/A

460N/Anode.set('innerHTML', html);

460N/A```

460N/A

460N/A<h3 id="node-events">DOM Events</h3>

460N/A

460N/A<p>

460N/A Use the `on` method to add an event listener to a `Node` instance. The

460N/A event object passed as the first argument to each listener is an event

460N/A facade that, like the Node API, normalizes browser differences and provides

460N/A a standard API for working with DOM events based on the W3C standard. All

460N/A properties of the event object that would normally return DOM elements

460N/A return `Y.Node` instances.

</p>

```

Y.one('#demo').on('click', function(e) {

e.preventDefault();

alert('event: ' + e.type + ' target: ' + e.target.get('tagName'));

});

```

<p>

For more details, check out <a href="../event/index.html">the Event user

guide</a>.

</p>

<h3 id="node-methods">DOM Methods</h3>

<p>

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.

</p>

```

var node = Y.one('#demo');

var node2 = node.appendChild(Y.one('#foo p'));

node2.addClass('bar');

```

<h3 id="nodelist">Using NodeList</h3>

<p>

The `Y.NodeList` provides a node-like interface for manipulating multiple

nodes through a single interface. The `NodeList` API is a pared-down

version of the `Node` API, allowing for batching of common tasks.

</p>

<p>The `Y.all` method is the simplest way to get a `NodeList`.</p>

```

Y.all('#demo li').addClass('bar');

```

<p>

The `Y.Node` api returns `NodeList` instances when the DOM would normally

return a collection of elements.

</p>

```

Y.one('#demo').get('children').addClass('bar');

```

<h3 id="node-query">Node Queries</h3>

<p>

Selector queries are a powerful way to test and manipulate nodes. All

`Y.Node` instances support `one`, `all`, and `test`.

</p>

```

var node = Y.one('#demo');

var node2 = node.one('p');

if (node2) { // might be null

node2.addClass('bar'); // adds "bar" to the first paragraph descendant of #demo

}

node.all('p').addClass('bar'); // adds "bar" to all paragraph descendants of #demo

if (node.test('.foo.bar')) { // "if node has both foo and bar classNames"

node.removeClass('bar');

}

```

<p>

For more information on selector queries, see the following W3C

specifications:

</p>

<ul>

<li><a href="http://www.w3.org/TR/css3-selectors/">CSS Level 3 Selectors</a></li>

<li><a href="http://www.w3.org/TR/selectors-API/">Selectors API</a></li>

</ul>

<p>

<strong>Note:</strong> CSS3 selector support is not included by default

with Node, you will need to include the "selector-css3" module for CSS3

support.

</p>

<h2 id="node-aria">ARIA Support</h2>

<p>

The Node interface has support for <a

href="http://www.w3.org/TR/wai-aria/">ARIA</a>. When used with Node's

built-in support for CSS selector queries, it is easy to both apply and

manage a Node's <a href="http://www.w3.org/TR/wai-aria/#roles">roles</a>,

<a href="http://www.w3.org/TR/wai-aria/#supportedState">states and

properties</a>.

<p>

<p>

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.

</p>

<p>

Apply any of the ARIA Roles, States and Properties via the `set` method.

For example, to apply the role of <a

href="http://www.w3.org/TR/wai-aria/#toolbar">`toolbar`</a> to a `<div>`

with an id of "toolbar":

</p>

```

var node = Y.one('#toolbar').set('role', 'toolbar');

```

<p>

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

<a href="http://www.w3.org/TR/wai-aria/#menubar">`menubar`</a> to the root

DOM element representing the menubar, and the role of

<a href="http://www.w3.org/TR/wai-aria/#menu">`menu`</a> to the root DOM

element representing each submenu. Additionally, as each submenu is hidden

by default, the

<a href="http://www.w3.org/TR/wai-aria/#aria-">`aria-hidden`</a> 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:

</p>

```

Y.one('#root').set('role', 'menubar').all('.menu').setAttrs({ role: 'menu', 'aria-hidden': true });

```

<h2 id="node-migration">Migration Table</h2>

<p>

The following table is included to help users migrating from YUI 2. Most

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

</p>

<p>

<strong>Note</strong> In the snippets below, `myNode` is an instance of

`Node`. Methods that normally would return DOM nodes now return Node

instances.

</p>

<table class="yui-table">

<thead>

<tr>

<th>2.x `YAHOO.util.???`</th>

<th>3.0</th>

</tr>

</thead>

<tbody>

<tr>

<td>

```

Dom.get('elementId');

```

</td>

<td>

```

Y.one('#elementId');

```

</td>

</tr>

<tr>

<td>

```

Dom.getElementsBy(someFilterFunction);

```

</td>

<td>

```

myNode.all('selectorString');

```

</td>

</tr>

<tr>

<td>

```

Dom.getElementsByClassName('highlight');

```

</td>

<td>

```

myNode.all('.highlight');

```

</td>

</tr>

<tr>

<td>

```

Dom.getChildren(el);

```

</td>

<td>

```

myNode.get('children');

```

</td>

</tr>

<tr>

<td>

```

Dom.getChildrenBy(someFilterFunction);

```

</td>

<td>

```

myNode.all('selectorString');

```

</td>

</tr>

<tr>

<td>

```

Dom.getFirstChild(parentEl);

```

</td>

<td>

```

myNode.one('*');

```

</td>

</tr>

<tr>

<td>

```

Dom.getFirstChildBy(someFilterFunction);

```

</td>

<td>

```

myNode.one('> selectorString');

```

</td>

</tr>

<tr>

<td>

```

Dom.getLastChild(el);

Dom.getLastChildBy(someFilterFunction);

```

</td>

<td>

```

myNode.get('children').slice(-1).item(0);

// OR target the node with a selector

myNode.one('> selector:last-of-type');

```

</td>

</tr>

<tr>

<td>

```

Dom.getNextSibling(el);

Dom.getNextSiblingBy(someFilterFunction);

Dom.getPreviousSibling(el);

Dom.getPreviousSiblingBy(someFilterFunction);

```

</td>

<td>

```

myNode.next();

myNode.next('selectorString');

myNode.previous();

myNode.previous('selectorString');

```

</td>

</tr>

<tr>

<td>

```

Dom.getAncestorBy(someFilterFunction);

Dom.getAncestorByClassName('highlight');

Dom.getAncestorByTagName('pre');

```

</td>

<td>

```

myNode.ancestor(someFilterFunction);

myNode.ancestor('.highlight');

myNode.ancestor('pre');

```

</td>

</tr>

<tr>

<td>

```

Dom.isAncestor(ancestorEl, el);

```

</td>

<td>

```

ancestorNode.contains(myNode);

```

</td>

</tr>

<tr>

<td>

```

Dom.insertAfter(el, afterEl);

Dom.insertBefore(el, beforeNode);

```

</td>

<td>

```

afterNode.insert(myNode, 'after');

beforeNode.insert(myNode, 'before');

```

</td>

</tr>

<tr>

<td>

```

Dom.addClass('highlight');

```

</td>

<td>

```

myNode.addClass('highlight');

```

</td>

</tr>

<tr>

<td>

```

Dom.removeClass(el, 'highlight');

```

</td>

<td>

```

myNode.removeClass('highlight');

```

</td>

</tr>

<tr>

<td>

```

Dom.replaceClass(el, 'high', 'low');

```

</td>

<td>

```

myNode.replaceClass('high', 'low');

```

</td>

</tr>

<tr>

<td>

```

Dom.hasClass(el, 'highlight');

```

</td>

<td>

```

myNode.hasClass('highlight');

```

</td>

</tr>

<tr>

<td>

```

Dom.getStyle(el, 'backgroundColor');

```

</td>

<td>

```

myNode.getStyle('backgroundColor');

```

</td>

</tr>

<tr>

<td>

```

Dom.setStyle(el, 'borderColor', '#C0FFEE');

```

</td>

<td>

```

myNode.setStyle('borderColor', '#C0FFEE');

```

</td>

</tr>

<tr>

<td>

```

Dom.getXY(el);

Dom.getX(el);

Dom.getY(el);

```

</td>

<td>

```

myNode.getXY();

myNode.getX();

myNode.getY();

```

</td>

</tr>

<tr>

<td>

```

Dom.setXY(el, [ 500, 300 ]);

Dom.setX(el, 500);

Dom.setY(el, 300);

```

</td>

<td>

```

myNode.setXY([ 500, 300 ]);

myNode.setX(500);

myNode.setY(300);

```

</td>

</tr>

<tr>

<td>

```

Dom.inDocument(el);

```

</td>

<td>

```

myNode.inDoc();

```

</td>

</tr>

<tr>

<td>

```

Dom.batch(elementArray,

Dom.addClass, 'highlight');

```

</td>

<td>

```

myNodelist.addClass('highlight');

// OR

myNodelist.each(function (node) {

node.addClass('highlight')

});

// OR

Y.Array.each(myNodelist, function (node) {

node.addClass('highlight');

});

```

</td>

</tr>

<tr>

<td>

```

Dom.generateId();

```

</td>

<td>

```

Y.guid();

```

</td>

</tr>

<tr>

<td>

```

Dom.getViewportHeight();

Dom.getViewportWidth();

```

</td>

<td>

```

myNode.get('winHeight');

myNode.get('winWidth');

```

</td>

</tr>

<tr>

<td>

```

Dom.getDocumentHeight();

Dom.getDocumentWidth();

```

</td>

<td>

```

myNode.get('docHeight');

myNode.get('docWidth');

```

</td>

</tr>

<tr>

<td>

```

Dom.getClientRegion();

```

</td>

<td>

```

myNode.get('viewportRegion');

```

</td>

</tr>

<tr>

<td>

```

Dom.getRegion(el);

```

</td>

<td>

```

myNode.get('region');

```

</td>

</tr>

<tr>

<td>

```

Dom.getDocumentScrollLeft();

Dom.getDocumentScrollTop();

```

</td>

<td>

```

myNode.get('docScrollX');

myNode.get('docScrollY');

```

</td>

</tr>

</tbody>

</table>