index.mustache revision fb1ecdf65fd4106deb62da339763f2e7670ca0f6
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <div class="intro">
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney{{>getting-started}}
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h2 id="node-using">Using Node</h2>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h3 id="using-node">Getting a Node</h3>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney `Node` is the interface for DOM operations in YUI 3.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney The Node API is based on the standard DOM API, and provides additional sugar
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney properties and methods that make common operations easier, and implementation
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney code more concise. Developers familiar with the standard DOM API will find Node
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney instances to be very familiar.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney The simplest way to get a `Node` instance is using your YUI instance's `one` method.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney `Y.one` accepts either an existing DOM element or a selector query. If a selector query is used,
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney the first matching element is used.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney This example demonstrates two ways to get a node instance.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var node1 = Y.one('#main');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h3 id="node-properties">Accessing Node Properties</h3>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney This is an example of getting and setting various properties.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var node = Y.one('#foo');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var parent = node.get('parentNode'); // Node instance
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var html = 'I am "' + node.get('id') + '".';
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney html += 'My parent is "' + parent.get('id') + '"';
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney node.set('innerHTML', html);
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h3 id="node-events">DOM Events</h3>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <p>Use the `on` method to add an event listener to a `Node` instance.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney The event object passed as the first argument to each listener is an event facade
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney that, like the Node API, normalizes browser differences and provides a standard API for
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney working with DOM events based on the W3C standard. All properties of the event object
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney that would normally return DOM elements return `Y.Node` instances.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney Y.one('#demo').on('click', function(e) {
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney alert('event: ' + e.type + ' target: ' + e.target.get('tagName'));
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h3 id="node-methods">DOM Methods</h3>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <p>The `Y.Node` API provides all of the DOM methods you would expect, plus a few extras to help with common tasks.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney As with properties and events, any methods that would normally return DOM nodes instead return `Y.Node` instances.</p>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var node = Y.one('#demo');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h3 id="nodelist">Using NodeList</h3>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <p>The `Y.all` method is the simplest way to get a `NodeList`.</p>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney Y.all('#demo li').addClass('bar');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <p>The `Y.Node` api returns `NodeList` instances when the DOM would normally return a collection of elements.</p>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney Y.one('#demo').get('children').addClass('bar');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h3 id="node-query">Node Queries</h3>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <p>Selector queries are a powerful way to test and manipulate nodes. All `Y.Node` instances support `one`, `all`, and `test`.</p>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var node = Y.one('#demo');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var node2 = node.one('p');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney if (node2) { // might be null
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney node2.addClass('bar'); // adds "bar" to the first paragraph descendant of #demo
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney node.all('p').addClass('bar'); // adds "bar" to all paragraph descendants of #demo
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney if (node.test('.foo.bar')) { // "if node has both foo and bar classNames"
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <p>For more information on selector queries, see the following W3C specifications:</p>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <li><a href="http://www.w3.org/TR/css3-selectors/">CSS Level 3 Selectors</a></li>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <li><a href="http://www.w3.org/TR/selectors-API/">Selectors API</a></li>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h2 id="node-aria">ARIA Support</h2>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney The Node interface has support for
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <a href="http://www.w3.org/TR/wai-aria/">ARIA</a>.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney When used with Node's built-in support for CSS selector
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney queries, it is easy to both apply and manage a Node's
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <a href="http://www.w3.org/TR/wai-aria/#roles">roles</a>,
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <a href="http://www.w3.org/TR/wai-aria/#supportedState">states and properties</a>.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney The ARIA Roles, States and Properties enhance
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney the semantics of HTML, allowing developers to more
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney accurately describe the intended purpose of a region of a
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney page, or a DHTML widget, thereby improving the user
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney experience for users of assistive technology, such as
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney screen readers.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney Apply any of the ARIA Roles, States and Properties via
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney the `set` method. For example, to apply the
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <a href="http://www.w3.org/TR/wai-aria/#toolbar">`toolbar`</a>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney to a `<div>` with an id of "toolbar":
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney var node = Y.one('#toolbar').set('role', 'toolbar');
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney Node's built-in support for CSS selector queries,
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney method chaining, and ability to set multiple attributes
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney on a single Node instance makes it especially easy to apply
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney the ARIA Roles, States, and Properties when building
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney DHTML widgets with a large subtree. For example, when
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney building a menubar widget it is necessary to apply a role
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <a href="http://www.w3.org/TR/wai-aria/#menubar">`menubar`</a>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney to the root DOM element representing the menubar, and the
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <a href="http://www.w3.org/TR/wai-aria/#menu">`menu`</a>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney to the root DOM element representing each submenu.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney Additionally, as each submenu is hidden by
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney default, the <a href="http://www.w3.org/TR/wai-aria/#aria-">`aria-hidden`</a>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney state will need to be applied to each submenu as well.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney The Node interface makes it possible to do all of this in
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney one line of code:
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney Y.one('#rootmenu').set('role', 'menubar').all('.menu').setAttrs({ role: 'menu', 'aria-hidden': true });
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <h2 id="node-migration">Migration Table</h2>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <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>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <table class="yui-table">
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <th>3.0</th>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>addClass</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>batch</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>NodeList[methodName], NodeList.each, or Y.each</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>generateId</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>get</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>Y.one <strong>Note</strong> strings are now treated as selectors (e.g. "Y.one('#foo')" vs. "YAHOO.util.Dom.get('foo')")</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getAncestorBy</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getAncestorByClassName</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getAncestorByTagName</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getChildren</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('children')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getChildrenBy</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getClientRegion</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('viewportRegion')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getDocumentHeight</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('docHeight')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getDocumentScrollLeft</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('docScrollX')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getDocumentScrollTop</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('docscrollY')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getDocumentWidth</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('docWidth')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getElementsBy</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getElementsByClassName</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getFirstChild</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getFirstChildBy</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getLastChild</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getLastChildBy</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getNextSibling</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getNextSiblingBy</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getPreviousSibling</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getPreviousSiblingBy</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getRegion</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('region')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getStyle</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getViewportHeight</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('winHeight')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getViewportWidth</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.get('winWidth')</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getX</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getY</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>getXY</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>hasClass</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>inDocument</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>insertAfter</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>insertBefore</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>isAncestor</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>myNode.contains (<strong>Note</strong> myNode.contains(myNode) === true)</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>removeClass</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>replaceClass</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>setStyle</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>setX</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>setY</td>
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney <td>setXY</td>