a93a1f58a8763fa69172980b98e3d24720c1136egm <div class="intro">

a93a1f58a8763fa69172980b98e3d24720c1136egm <p>The Node Utility provides an expressive way to collect, create, and manipulate DOM nodes. Each `Node` instance represents an underlying DOM node, and each `NodeList` represents a collection of DOM nodes. With `Node`, you can manage classNames (`myNode.addClass('foo')`) and styles (`myNode.setStyle('opacity', 0.5)`), create elements (`Y.Node.create('<div id="foo" class="foo"><p>foo</p></div>')`), and much more.</p>

a93a1f58a8763fa69172980b98e3d24720c1136egm <p><strong>Note: </strong><em>The method `Y.get` has been deprecated in favor of `Y.one`. The methods `Node::query` and `Node::queryAll` have been deprecated in favor of `Node::one` and `Node::all` To continue using the deprecated methods, you will need to `use('node-deprecated')`. </em></p>

a93a1f58a8763fa69172980b98e3d24720c1136egm

a93a1f58a8763fa69172980b98e3d24720c1136egm</div>

a93a1f58a8763fa69172980b98e3d24720c1136egm{{>getting-started}}

a93a1f58a8763fa69172980b98e3d24720c1136egm<div>

a93a1f58a8763fa69172980b98e3d24720c1136egm <h2 id="node-using">Using Node</h2>

a93a1f58a8763fa69172980b98e3d24720c1136egm

a93a1f58a8763fa69172980b98e3d24720c1136egm <h3 id="using-node">Getting a Node</h3>

a93a1f58a8763fa69172980b98e3d24720c1136egm <p>

a93a1f58a8763fa69172980b98e3d24720c1136egm `Node` is the interface for DOM operations in YUI 3.

a93a1f58a8763fa69172980b98e3d24720c1136egm The Node API is based on the standard DOM API, and provides additional sugar

a93a1f58a8763fa69172980b98e3d24720c1136egm properties and methods that make common operations easier, and implementation

a93a1f58a8763fa69172980b98e3d24720c1136egm code more concise. Developers familiar with the standard DOM API will find Node

a93a1f58a8763fa69172980b98e3d24720c1136egm instances to be very familiar.

a93a1f58a8763fa69172980b98e3d24720c1136egm </p>

a93a1f58a8763fa69172980b98e3d24720c1136egm <p>

a93a1f58a8763fa69172980b98e3d24720c1136egm The simplest way to get a `Node` instance is using your YUI instance's `one` method.

a93a1f58a8763fa69172980b98e3d24720c1136egm `Y.one` accepts either an existing DOM element or a selector query. If a selector query is used,

a93a1f58a8763fa69172980b98e3d24720c1136egm the first matching element is used.

cd3e933325e68e23516a196a8fea7f49b1e497c3Ali Bahrami </p>

a93a1f58a8763fa69172980b98e3d24720c1136egm <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>

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami <p>

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami This example demonstrates two ways to get a node instance.

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami </p>

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami```

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami var node1 = Y.one('#main');

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami var node2 = Y.one(document.body);

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami```

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami <h3 id="node-properties">Accessing Node Properties</h3>

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami <p>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.</p>

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami

bfed486ad8de8b8ebc6345a8e10accae08bf2f45Ali Bahrami <p>

a93a1f58a8763fa69172980b98e3d24720c1136egm This is an example of getting and setting various properties.

a93a1f58a8763fa69172980b98e3d24720c1136egm </p>

cd3e933325e68e23516a196a8fea7f49b1e497c3Ali Bahrami```

cd3e933325e68e23516a196a8fea7f49b1e497c3Ali Bahrami var node = Y.one('#foo');

cd3e933325e68e23516a196a8fea7f49b1e497c3Ali Bahrami var parent = node.get('parentNode'); // Node instance

a93a1f58a8763fa69172980b98e3d24720c1136egm

a93a1f58a8763fa69172980b98e3d24720c1136egm var html = 'I am "' + node.get('id') + '".';

a93a1f58a8763fa69172980b98e3d24720c1136egm html += 'My parent is "' + parent.get('id') + '"';

a93a1f58a8763fa69172980b98e3d24720c1136egm

a93a1f58a8763fa69172980b98e3d24720c1136egm node.set('innerHTML', html);

a93a1f58a8763fa69172980b98e3d24720c1136egm```

a93a1f58a8763fa69172980b98e3d24720c1136egm <h3 id="node-events">DOM Events</h3>

a93a1f58a8763fa69172980b98e3d24720c1136egm

a93a1f58a8763fa69172980b98e3d24720c1136egm <p>Use the `on` method to add an event listener to a `Node` instance.

a93a1f58a8763fa69172980b98e3d24720c1136egm The event object passed as the first argument to each listener is an event facade

a93a1f58a8763fa69172980b98e3d24720c1136egm that, like the Node API, normalizes browser differences and provides a standard API for

a93a1f58a8763fa69172980b98e3d24720c1136egm working with DOM events based on the W3C standard. All properties of the event object

a93a1f58a8763fa69172980b98e3d24720c1136egm that would normally return DOM elements return `Y.Node` instances.

a93a1f58a8763fa69172980b98e3d24720c1136egm </p>

a93a1f58a8763fa69172980b98e3d24720c1136egm

a93a1f58a8763fa69172980b98e3d24720c1136egm```

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

a93a1f58a8763fa69172980b98e3d24720c1136egm e.preventDefault();

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

a93a1f58a8763fa69172980b98e3d24720c1136egm });

a93a1f58a8763fa69172980b98e3d24720c1136egm```

a93a1f58a8763fa69172980b98e3d24720c1136egm

a93a1f58a8763fa69172980b98e3d24720c1136egm

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

a93a1f58a8763fa69172980b98e3d24720c1136egm <p>The `Y.Node` API provides all of the DOM methods you would expect, plus a few extras to help with common tasks.

a93a1f58a8763fa69172980b98e3d24720c1136egm As with properties and events, any methods that would normally return DOM nodes instead return `Y.Node` instances.</p>

a93a1f58a8763fa69172980b98e3d24720c1136egm```

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

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

a93a1f58a8763fa69172980b98e3d24720c1136egm 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 `&#60;div&#62;` 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('#rootmenu').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 `(via YAHOO.util.Dom)`</th>

<th>3.0</th>

</tr>

</thead>

<tbody>

<tr>

<td>addClass</td>

<td>myNode.addClass</td>

</tr>

<tr>

<td>batch</td>

<td>NodeList[methodName], NodeList.each, or Y.each</td>

</tr>

<tr>

<td>generateId</td>

<td>Y.guid</td>

</tr>

<tr>

<td>get</td>

<td>Y.one <strong>Note</strong> strings are now treated as selectors (e.g. "Y.one('#foo')" vs. "YAHOO.util.Dom.get('foo')")</td>

</tr>

<tr>

<td>getAncestorBy</td>

<td>myNode.ancestor</td>

</tr>

<tr>

<td>getAncestorByClassName</td>

<td>myNode.ancestor</td>

</tr>

<tr>

<td>getAncestorByTagName</td>

<td>myNode.ancestor</td>

</tr>

<tr>

<td>getChildren</td>

<td>myNode.get('children')</td>

</tr>

<tr>

<td>getChildrenBy</td>

<td>myNode.all</td>

</tr>

<tr>

<td>getClientRegion</td>

<td>myNode.get('viewportRegion')</td>

</tr>

<tr>

<td>getDocumentHeight</td>

<td>myNode.get('docHeight')</td>

</tr>

<tr>

<td>getDocumentScrollLeft</td>

<td>myNode.get('docScrollX')</td>

</tr>

<tr>

<td>getDocumentScrollTop</td>

<td>myNode.get('docscrollY')</td>

</tr>

<tr>

<td>getDocumentWidth</td>

<td>myNode.get('docWidth')</td>

</tr>

<tr>

<td>getElementsBy</td>

<td>myNode.all</td>

</tr>

<tr>

<td>getElementsByClassName</td>

<td>myNode.all</td>

</tr>

<tr>

<td>getFirstChild</td>

<td>myNode.one</td>

</tr>

<tr>

<td>getFirstChildBy</td>

<td>myNode.one</td>

</tr>

<tr>

<td>getLastChild</td>

<td>myNode.one</td>

</tr>

<tr>

<td>getLastChildBy</td>

<td>myNode.one</td>

</tr>

<tr>

<td>getNextSibling</td>

<td>myNode.next</td>

</tr>

<tr>

<td>getNextSiblingBy</td>

<td>myNode.next</td>

</tr>

<tr>

<td>getPreviousSibling</td>

<td>myNode.previous</td>

</tr>

<tr>

<td>getPreviousSiblingBy</td>

<td>myNode.previous</td>

</tr>

<tr>

<td>getRegion</td>

<td>myNode.get('region')</td>

</tr>

<tr>

<td>getStyle</td>

<td>myNode.getStyle</td>

</tr>

<tr>

<td>getViewportHeight</td>

<td>myNode.get('winHeight')</td>

</tr>

<tr>

<td>getViewportWidth</td>

<td>myNode.get('winWidth')</td>

</tr>

<tr>

<td>getX</td>

<td>myNode.getXY</td>

</tr>

<tr>

<td>getY</td>

<td>myNode.getXY</td>

</tr>

<tr>

<td>getXY</td>

<td>myNode.getXY</td>

</tr>

<tr>

<td>hasClass</td>

<td>myNode.hasClass</td>

</tr>

<tr>

<td>inDocument</td>

<td>myNode.inDoc</td>

</tr>

<tr>

<td>insertAfter</td>

<td>myNode.insert</td>

</tr>

<tr>

<td>insertBefore</td>

<td>myNode.insert</td>

</tr>

<tr>

<td>isAncestor</td>

<td>myNode.contains (<strong>Note</strong> myNode.contains(myNode) === true)</td>

</tr>

<tr>

<td>removeClass</td>

<td>myNode.removeClass</td>

</tr>

<tr>

<td>replaceClass</td>

<td>myNode.replaceClass</td>

</tr>

<tr>

<td>setStyle</td>

<td>myNode.setStyle</td>

</tr>

<tr>

<td>setX</td>

<td>myNode.setXY</td>

</tr>

<tr>

<td>setY</td>

<td>myNode.setXY</td>

</tr>

<tr>

<td>setXY</td>

<td>myNode.setXY</td>

</tr>

</tbody>

</table>

</div>