index.mustache revision 61d056e25c884bc5635cfe38d3c4a1099977644e
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<div class="intro">
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The Node Utility provides an expressive way to collect, create, and
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith manipulate DOM nodes. Each `Node` instance represents an underlying
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith DOM node, and each `NodeList` represents a collection of DOM nodes.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith With `Node`, you can manage classNames
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <p>styles</p>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith myNode.setStyle('opacity', 0.5);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <p>create elements</p>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Y.Node.create('<li id="item3" class="highlight"><em>Profit</em></li>');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <p>and much more.</p>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <strong>Note:</strong> The <em>`Y.get()`, `node.query()`, and
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith `node.queryAll()` methods have been removed. Use `Y.one()`,
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith "<a href="{{apiDocs}}/modules/node-deprecated.html">node-deprecated</a>"
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith module in your `use()` statement to restore them</em>.
fb1ecdf65fd4106deb62da339763f2e7670ca0f6Matt Sweeney{{>getting-started}}
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h2 id="node-using">Using Node</h2>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h3 id="using-node">Getting a Node</h3>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith `Node` is the interface for DOM operations in YUI 3. The Node API is
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith based on the standard DOM API, and provides additional sugar properties
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith and methods that make common operations easier, and implementation code
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith more concise. Developers familiar with the standard DOM API will find
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Node instances to be very familiar.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The simplest way to get a `Node` instance is using your YUI instance's
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith `one` method. `Y.one` accepts either an existing DOM element or a selector
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith query. If a selector query is used, the first matching element is used.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <strong>Note:</strong> CSS3 selector support is not included by default
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith with Node, you will need to include the "selector-css3" module for CSS3
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<p>This example demonstrates two ways to get a node instance.</p>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar node1 = Y.one('#main');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h3 id="node-properties">Accessing Node Properties</h3>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Properties of the underlying DOM node are accessed via the `Y.Node`
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith instance's `set` and `get` methods. For simple property types (strings,
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith numbers, booleans), these pass directly to/from the underlying node, but
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith properties that normally return DOM nodes return `Y.Node` instances
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<p>This is an example of getting and setting various properties.</p>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar node = Y.one('#foo');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar parent = node.get('parentNode'); // Node instance
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar html = 'I am "' + node.get('id') + '".';
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithhtml += 'My parent is "' + parent.get('id') + '"';
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithnode.set('innerHTML', html);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h3 id="node-events">DOM Events</h3>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Use the `on` method to add an event listener to a `Node` instance. The
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith event object passed as the first argument to each listener is an event
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith facade that, like the Node API, normalizes browser differences and provides
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith a standard API for working with DOM events based on the W3C standard. All
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith properties of the event object that would normally return DOM elements
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith return `Y.Node` instances.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke SmithY.one('#demo').on('click', function(e) {
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith alert('event: ' + e.type + ' target: ' + e.target.get('tagName'));
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith For more details, check out <a href="../event/index.html">the Event user
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h3 id="node-methods">DOM Methods</h3>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The `Y.Node` API provides all of the DOM methods you would expect, plus a
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith few extras to help with common tasks. As with properties and events, any
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith methods that would normally return DOM nodes instead return `Y.Node`
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar node = Y.one('#demo');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h3 id="nodelist">Using NodeList</h3>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The `Y.NodeList` provides a node-like interface for manipulating multiple
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith nodes through a single interface. The `NodeList` API is a pared-down
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith version of the `Node` API, allowing for batching of common tasks.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<p>The `Y.all` method is the simplest way to get a `NodeList`.</p>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke SmithY.all('#demo li').addClass('bar');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The `Y.Node` api returns `NodeList` instances when the DOM would normally
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith return a collection of elements.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke SmithY.one('#demo').get('children').addClass('bar');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h3 id="node-query">Node Queries</h3>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Selector queries are a powerful way to test and manipulate nodes. All
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith `Y.Node` instances support `one`, `all`, and `test`.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar node = Y.one('#demo');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar node2 = node.one('p');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithif (node2) { // might be null
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith node2.addClass('bar'); // adds "bar" to the first paragraph descendant of #demo
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithnode.all('p').addClass('bar'); // adds "bar" to all paragraph descendants of #demo
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithif (node.test('.foo.bar')) { // "if node has both foo and bar classNames"
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith For more information on selector queries, see the following W3C
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith specifications:
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <li><a href="http://www.w3.org/TR/css3-selectors/">CSS Level 3 Selectors</a></li>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <li><a href="http://www.w3.org/TR/selectors-API/">Selectors API</a></li>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <strong>Note:</strong> CSS3 selector support is not included by default
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith with Node, you will need to include the "selector-css3" module for CSS3
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h2 id="node-aria">ARIA Support</h2>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The Node interface has support for <a
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith href="http://www.w3.org/TR/wai-aria/">ARIA</a>. When used with Node's
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith built-in support for CSS selector queries, it is easy to both apply and
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith manage a Node's <a href="http://www.w3.org/TR/wai-aria/#roles">roles</a>,
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <a href="http://www.w3.org/TR/wai-aria/#supportedState">states and
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith properties</a>.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The ARIA Roles, States and Properties enhance the semantics of HTML,
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith allowing developers to more accurately describe the intended purpose of a
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith region of a page, or a DHTML widget, thereby improving the user experience
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith for users of assistive technology, such as screen readers.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Apply any of the ARIA Roles, States and Properties via the `set` method.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith For example, to apply the role of <a
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith href="http://www.w3.org/TR/wai-aria/#toolbar">`toolbar`</a> to a `<div>`
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith with an id of "toolbar":
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smithvar node = Y.one('#toolbar').set('role', 'toolbar');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Node's built-in support for CSS selector queries, method chaining, and
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith ability to set multiple attributes on a single Node instance makes it
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith especially easy to apply the ARIA Roles, States, and Properties when
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith building DHTML widgets with a large subtree. For example, when building a
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith menubar widget it is necessary to apply a role of
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <a href="http://www.w3.org/TR/wai-aria/#menubar">`menubar`</a> to the root
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith DOM element representing the menubar, and the role of
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <a href="http://www.w3.org/TR/wai-aria/#menu">`menu`</a> to the root DOM
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith element representing each submenu. Additionally, as each submenu is hidden
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith by default, the
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <a href="http://www.w3.org/TR/wai-aria/#aria-">`aria-hidden`</a> state will
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith need to be applied to each submenu as well. The Node interface makes it
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith possible to do all of this in one line of code:
33ba1088378b236bdb1ccdb65751b072eb5d4b60Luke SmithY.one('#root').set('role', 'menubar').all('.menu').setAttrs({ role: 'menu', 'aria-hidden': true });
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<h2 id="node-migration">Migration Table</h2>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith The following table is included to help users migrating from YUI 2. Most
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith of the functionality from `YAHOO.util.Dom` is available via `Node`.
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <strong>Note</strong> In the snippets below, `myNode` is an instance of
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith `Node`. Methods that normally would return DOM nodes now return Node
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith<table class="yui-table">
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith <th>3.0</th>
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el = Dom.get('elementId');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node = Y.one('#elementId');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var els = Dom.getElementsBy(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var nodelist = myNode.all('selectorString');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var els = Dom.getElementsByClassName('highlight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var nodelist = myNode.all('.highlight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var elementArray = Dom.getChildren(el);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var nodelist = myNode.get('children');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var els1 = Dom.getChildrenBy(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var nodelist = myNode.all('selectorString');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el = Dom.getFirstChild(parentEl);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node = myNode.one('*');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el = Dom.getFirstChildBy(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node = myNode.one('> selectorString');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el2 = Dom.getLastChildBy(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node1 = myNode.get('children').slice(-1).item(0);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith // OR target the node with a selector
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node2 = myNode.one('> selector:last-of-type');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el2 = Dom.getNextSiblingBy(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el4 = Dom.getPreviousSiblingBy(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node1 = myNode.next();
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node2 = myNode.next('selectorString');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node4 = myNode.previous('selectorString');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el1 = Dom.getAncestorBy(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el2 = Dom.getAncestorByClassName('highlight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var el3 = Dom.getAncestorByTagName('pre');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node1 = myNode.ancestor(someFilterFunction);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node2 = myNode.ancestor('.highlight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var node3 = myNode.ancestor('pre');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.isAncestor(ancestorEl, el);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.insertBefore(el, beforeNode);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith afterNode.insert(myNode, 'after');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith beforeNode.insert(myNode, 'before');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.removeClass(el, 'highlight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.replaceClass(el, 'highlight', 'selected');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith myNode.replaceClass('highlight', 'selected');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.hasClass(el, 'highlight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var val = Dom.getStyle(el, 'backgroundColor');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var val = myNode.getStyle('backgroundColor');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.setStyle(el, 'backgroundColor', '#C0FFEE');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith myNode.setStyle('backgroundColor', '#C0FFEE');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var xy = Dom.getXY(el);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.setXY(el, [ 500, 300 ]);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith myNode.setXY([ 500, 300 ]);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Dom.batch(elementArray, Dom.addClass, 'highlight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith myNodelist.each(function (node) {
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith Y.Array.each(myNodelist, function (node) {
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var height = myNode.get('winHeight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var width = myNode.get('winWidth');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var height = myNode.get('docHeight');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var width = myNode.get('docWidth');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var region = myNode.get('viewportRegion');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var region = Dom.getRegion(el);
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var region = myNode.get('region');
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith var left = myNode.get('docScrollX'),
61d056e25c884bc5635cfe38d3c4a1099977644eLuke Smith top = myNode.get('docScrollY');