node-core.js revision 5ae2ccf01bf2753c8a416210b114a21b1f1fa353
5462N/A * The Node Utility provides a DOM-like interface for interacting with DOM nodes. 5462N/A * The Node class provides a wrapper for manipulating DOM Nodes. 5462N/A * Node properties can be accessed via the set/get methods. 5462N/A * Use `Y.one()` to retrieve Node instances. 5462N/A * <strong>NOTE:</strong> Node properties are accessed using 5462N/A * the <code>set</code> and <code>get</code> methods. 5462N/A * @param {DOMNode} node the DOM node to be mapped to the Node instance. 5462N/A return null;
// NOTE: return 5462N/A node[
UID] =
null;
// unset existing uid to prevent collision (via clone or hack) if (!
uid) {
// stamp failed; likely IE non-HTMLElement * The underlying DOM node bound to the Y.Node instance ret = (
typeof fn ==
'string') ?
}
else if (
node.
indexOf(
'win') ===
0) {
// win OR window * The name of the component * The pattern used to identify ARIA attributes * A list of Node instances that have been created * Retrieves the DOM node bound to a Node instance * @param {Node | HTMLNode} node The Node instance or an HTMLNode * @return {HTMLNode} The DOM node bound to the Node instance. If a DOM node is passed * as the node argument, it is simply returned. * Checks Node return values and wraps DOM Nodes as Y.Node instances * and DOM Collections / Arrays as Y.NodeList instances. * Other return values just pass thru. If undefined is returned (e.g. no return) * then the Node instance is returned for chainability. * @param {any} node The Node instance or an HTMLNode * @return {Node | NodeList | Any} Depends on what is returned from the DOM node. if (
val) {
// only truthy values are risky if (
typeof val ==
'object' ||
typeof val ==
'function') {
// safari nodeList === function }
else if (
typeof val ===
'undefined') {
}
else if (
val ===
null) {
val =
null;
// IE: DOM null not the same as null * Adds methods to the Y.Node prototype, routing through scrubVal. * @param {String} name The name of the method to add * @param {Function} fn The function that becomes the method * @param {Object} context An optional context to call the method with * (defaults to the Node instance) * @return {any} Depends on what is returned from the DOM node. if (
name &&
fn &&
typeof fn ==
'function') {
if (
ret) {
// scrub truthy * Imports utility methods to be added as Y.Node methods. * @param {Object} host The object that contains the method to import. * @param {String} name The name of the method to import * @param {String} altName An optional name to use in place of the host name * @param {Object} context An optional context to call the method with if (
typeof name ==
'string') {
* Retrieves a NodeList based on the given CSS selector. * @param {string} selector The CSS selector to test against. * Returns a single Node instance bound to the node or the * first element matching the given selector. Returns null if no match found. * <strong>Note:</strong> For chaining purposes you may want to * use <code>Y.all</code>, which returns a NodeList when no match is found. * @param {String | HTMLElement} node a node or Selector * @return {Node | null} a Node instance or null if no match found. * Returns a single Node instance bound to the node or the * first element matching the given selector. Returns null if no match found. * <strong>Note:</strong> For chaining purposes you may want to * use <code>Y.all</code>, which returns a NodeList when no match is found. * @param {String | HTMLElement} node a node or Selector * @return {Node | null} a Node instance or null if no match found. if (
typeof node ==
'string') {
return null;
// NOTE: return return node;
// NOTE: return * The default setter for DOM properties * Called with instance context (this === the Node instance) * @param {any} val The value to be set * @return {any} The value // only allow when defined on node }
else if (
typeof node[
name] !=
'undefined') {
// pass thru DOM properties * The default getter for DOM properties * Called with instance context (this === the Node instance) * @return {any} The current value }
else if (
typeof node[
name] !=
'undefined') {
// pass thru from DOM * The method called when outputting Node instances as strings * @return {String} A string representation of the Node instance var str =
this[
UID] +
': not bound to a node',
* Returns an attribute value on the Node instance. * Unless pre-configured (via `Node.ATTRS`), get hands * off to the underlying DOM node. Only valid * @param {String} attr The attribute * @return {any} The current value of the attribute if (
this.
_getAttr) {
// use Attribute imple }
else if (
val ===
null) {
val =
null;
// IE: DOM null is not true null (even though they ===) * @param {String} attr The attribute * @return {any} The current value of the attribute * Sets an attribute on the Node instance. * Unless pre-configured (via Node.ATTRS), set hands * off to the underlying DOM node. Only valid * To set custom attributes use setAttribute. * @param {String} attr The attribute to be set. * @param {any} val The value to set the attribute to. if (
this.
_setAttr) {
// use Attribute imple }
else {
// use setters inline * Sets multiple attributes. * @param {Object} attrMap an object of name/value pairs to set }
else {
// use setters inline * Returns an object containing the values for the requested attributes. * @param {Array} attrs an array of attributes to get values * @return {Object} An object with attribute name/value pairs. }
else {
// use setters inline * Compares nodes to determine if they match. * Node instances can be compared to each other and/or HTMLElements. * @param {HTMLElement | Node} refNode The reference node to compare to the node. * @return {Boolean} True if the nodes match, false if they do not. * Determines whether the node is appended to the document. * @param {Node|HTMLElement} doc optional An optional document to check against. * Defaults to current document. * @return {Boolean} Whether or not this node is appended to the document. * Returns the nearest ancestor that passes the test applied by supplied boolean method. * @param {String | Function} fn A selector string or boolean method for testing elements. * @param {Boolean} testSelf optional Whether or not to include the element in the scan * If a function is used, it receives the current node being tested as the only argument. * @return {Node} The matching Node instance or null if not found * Returns the ancestors that pass the test applied by supplied boolean method. * @param {String | Function} fn A selector string or boolean method for testing elements. * @param {Boolean} testSelf optional Whether or not to include the element in the scan * If a function is used, it receives the current node being tested as the only argument. * @return {NodeList} A NodeList instance containing the matching elements * Returns the previous matching sibling. * Returns the nearest element node sibling if no method provided. * @param {String | Function} fn A selector or boolean method for testing elements. * If a function is used, it receives the current node being tested as the only argument. * @return {Node} Node instance or null if not found * Returns the next matching sibling. * Returns the nearest element node sibling if no method provided. * @param {String | Function} fn A selector or boolean method for testing elements. * If a function is used, it receives the current node being tested as the only argument. * @return {Node} Node instance or null if not found * Returns all matching siblings. * Returns all siblings if no method provided. * @param {String | Function} fn A selector or boolean method for testing elements. * If a function is used, it receives the current node being tested as the only argument. * @return {NodeList} NodeList instance bound to found siblings * Retrieves a Node instance of nodes based on the given CSS selector. * @param {string} selector The CSS selector to test against. * @return {Node} A Node instance for the matching HTMLElement. * Retrieves a NodeList based on the given CSS selector. * @param {string} selector The CSS selector to test against. * Test if the supplied node matches the supplied selector. * @param {string} selector The CSS selector to test against. * @return {boolean} Whether or not the node matches the selector. * Removes the node from its parent. * Shortcut for myNode.get('parentNode').removeChild(myNode); * @param {Boolean} destroy whether or not to call destroy() on the node * Replace the node with the other node. This is a DOM update only * and does not change the node bound to the Node instance. * Shortcut for myNode.get('parentNode').replaceChild(newNode, myNode); * @param {Node | HTMLNode} newNode Node to be inserted * @param {String | HTMLElement | Node} node Node to be inserted * @param {HTMLElement | Node} refNode Node to be replaced * @return {Node} The replaced node if (
typeof node ==
'string') {
* Nulls internal node references, removes any plugins and event listeners * @param {Boolean} recursivePurge (optional) Whether or not to remove listeners from the * node's subtree (default is false) this.
purge();
// TODO: only remove events add via this Node if (
this.
unplug) {
// may not be a PluginHost * Invokes a method on the Node instance * @param {String} method The name of the method to invoke * @param {Any} a, b, c, etc. Arguments to invoke the method with. * @return Whatever the underly method returns. * DOM Nodes and Collections return values * @description Swap DOM locations with the given node. * This does not change which DOM node each Node instance refers to. * @param {Node} otherNode The node to swap with * @description Retrieves arbitrary data stored on a Node instance. * This is not stored with the DOM node. * @param {string} name Optional name of the data field to retrieve. * If no name is given, all data is returned. * @return {any | Object} Whatever is stored at the given field, * or an object hash of all fields. * @description Stores arbitrary data on a Node instance. * This is not stored with the DOM node. * @param {string} name The name of the field to set. If no name * is given, name is treated as the data and overrides any existing data. * @param {any} val The value to be assigned to the field. * @description Clears stored data. * @param {string} name The name of the field to clear. If no name * is given, all data is cleared. String(
node[
method]).
indexOf(
'function') ===
1));
// IE reports as object, prepends space return (
this.
get(
'nodeType') ===
11);
* Removes and destroys all of the nodes within the node. * Returns the DOM node bound to the Node instance * The NodeList module provides support for managing collections of Nodes. * The NodeList class provides a wrapper for manipulating DOM NodeLists. * NodeList properties can be accessed via the set/get methods. * Use Y.all() to retrieve NodeList instances. if (
typeof nodes ===
'string') {
// selector query }
else {
// array of domNodes or domNodeList (no mixed array of Y.Node/domNodes) * The underlying array of DOM nodes bound to the Y.NodeList instance * Retrieves the DOM nodes bound to a NodeList instance * @param {NodeList} nodelist The NodeList instance * @return {Array} The array of DOM nodes bound to the NodeList // TODO: remove tmp pointer if (
typeof name ===
'string') {
* Retrieves the Node instance at the given index. * @param {Number} index The index of the target Node. * @return {Node} The Node instance at the given index. * Applies the given function to each Node in the NodeList. * @param {Function} fn The function to apply. It receives 3 arguments: * the current node instance, the node's index, and the NodeList instance * @param {Object} context optional An optional context to apply the function with * Default context is the current Node instance * Executes the function once for each node until a true value is returned. * @param {Function} fn The function to apply. It receives 3 arguments: * the current node instance, the node's index, and the NodeList instance * @param {Object} context optional An optional context to execute the function from. * Default context is the current Node instance * @return {Boolean} Whether or not the function returned true for any node. * Creates a documenFragment from the nodes bound to the NodeList instance * @return {Node} a Node instance bound to the documentFragment * Returns the index of the node in the NodeList instance * or -1 if the node isn't found. * @param {Node | DOMNode} node the node to search for * @return {Int} the index of the node value or -1 if not found * Filters the NodeList instance down to only nodes matching the given selector. * @param {String} selector The selector to filter against * @return {NodeList} NodeList containing the updated collection * Creates a new NodeList containing all nodes at every n indices, where * remainder n % index equals r. * @param {Int} n The offset to use (return every nth node) * @param {Int} r An optional remainder to use with the modulus operation (defaults to zero) * @return {NodeList} NodeList containing the updated collection * Creates a new NodeList containing all nodes at odd indices * @return {NodeList} NodeList containing the updated collection * Creates a new NodeList containing all nodes at even indices * (zero-based index), including zero. * @return {NodeList} NodeList containing the updated collection * Reruns the initial query, when created using a selector query // map to Y.on/after signature (type, fn, nodes, context, arg1, arg2, etc) if (
args.
length <
2) {
// type only (event hash) just add nodes args[
3] =
context ||
this;
// default to NodeList instance as context * Applies an event listener to each Node bound to the NodeList. * @param {String} type The event being listened for * @param {Function} fn The handler to call when the event fires * @param {Object} context The context to call the handler with. * Default is the NodeList instance. * @param {Object} context The context to call the handler with. * param {mixed} arg* 0..n additional arguments to supply to the subscriber * @return {Object} Returns an event handle that can later be use to detach(). * Applies an one-time event listener to each Node bound to the NodeList. * @param {String} type The event being listened for * @param {Function} fn The handler to call when the event fires * @param {Object} context The context to call the handler with. * Default is the NodeList instance. * @return {Object} Returns an event handle that can later be use to detach(). * Applies an event listener to each Node bound to the NodeList. * The handler is called only after all on() handlers are called * and the event is not prevented. * @param {String} type The event being listened for * @param {Function} fn The handler to call when the event fires * @param {Object} context The context to call the handler with. * Default is the NodeList instance. * @return {Object} Returns an event handle that can later be use to detach(). * Returns the current number of items in the NodeList. * @return {Int} The number of items in the NodeList. * Determines if the instance is bound to any nodes * @return {Boolean} Whether or not the NodeList is bound to any nodes * Returns the DOM node bound to the Node instance /** Called on each Node instance /** Called on each Node instance /** Called on each Node instance /** Called on each Node instance // one-off implementation to convert array of Nodes to NodeList // e.g. Y.all('input').get('parentNode'); /** Called on each Node instance if (!
isNodeList) {
// convert array of Nodes to NodeList /** Returns a new NodeList combining the given NodeList(s) * concatenate to the resulting NodeList * @return {NodeList} A new NodeList comprised of this NodeList joined with the input. /** Removes the last from the NodeList and returns it. * @return {Node} The last item in the NodeList. /** Adds the given Node(s) to the end of the NodeList. * @param {Node | DOMNode} nodes One or more nodes to add to the end of the NodeList. /** Removes the first item from the NodeList and returns it. * @return {Node} The first item in the NodeList. /** Returns a new NodeList comprising the Nodes in the given range. * @param {Number} begin Zero-based index at which to begin extraction. As a negative index, start indicates an offset from the end of the sequence. slice(-2) extracts the second-to-last element and the last element in the sequence. * @param {Number} end Zero-based index at which to end extraction. slice extracts up to but not including end. slice(1,4) extracts the second element through the fourth element (elements indexed 1, 2, and 3). As a negative index, end indicates an offset from the end of the sequence. slice(2,-1) extracts the third element through the second-to-last element in the sequence. If end is omitted, slice extracts to the end of the sequence. * @return {NodeList} A new NodeList comprised of this NodeList joined with the input. /** Changes the content of the NodeList, adding new elements while removing old elements. * @param {Number} index Index at which to start changing the array. If negative, will begin that many elements from the end. * @param {Number} howMany An integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed. In this case, you should specify at least one new element. If no howMany parameter is specified (second syntax above, which is a SpiderMonkey extension), all elements after index are removed. * {Node | DOMNode| element1, ..., elementN The elements to add to the array. If you don't specify any elements, splice simply removes elements from the array. * @return {NodeList} The element(s) removed. /** Adds the given Node(s) to the beginning of the NodeList. * @param {Node | DOMNode} nodes One or more nodes to add to the NodeList. * Passes through to DOM method. * @param {HTMLElement | Node} node Node to be removed * @return {Node} The removed node * Passes through to DOM method. * @return {Boolean} Whether or not the node has any childNodes * Passes through to DOM method. * @param {Boolean} deep Whether or not to perform a deep clone, which includes * @return {Node} The clone * Passes through to DOM method. * @param {String} attribute The attribute to test for * @return {Boolean} Whether or not the attribute is present * Passes through to DOM method. * @method removeAttribute * @param {String} attribute The attribute to be removed * Passes through to DOM method. * Passes through to DOM method. * @method getElementsByTagName * @param {String} tagName The tagName to collect * @return {NodeList} A NodeList representing the HTMLCollection * Passes through to DOM method. * Passes through to DOM method. * Passes through to DOM method. * Only valid on FORM elements * Passes through to DOM method. * Only valid on FORM elements * Passes through to DOM method. * Passes through to DOM method. * Only valid on TABLE elements * Determines whether the node is an ancestor of another HTML element in the DOM hierarchy. * @param {Node | HTMLElement} needle The possible node or descendent * @return {Boolean} Whether or not this node is the needle its ancestor * Allows setting attributes on DOM nodes, normalizing in some cases. * This passes through to the DOM node, allowing for custom attributes. * @param {string} name The attribute name * @param {string} value The value to set * Allows getting attributes on DOM nodes, normalizing in some cases. * This passes through to the DOM node, allowing for custom attributes. * @param {string} name The attribute name * @return {string} The attribute value * Wraps the given HTML around the node. * @param {String} html The markup to wrap around the node. * Removes the node's parent node. * Applies a unique ID to the node if none exists * @return {String} The existing or generated ID * Allows getting attributes on DOM nodes, normalizing in some cases. * This passes through to the DOM node, allowing for custom attributes. * @param {string} name The attribute name * @return {string} The attribute value * Allows setting attributes on DOM nodes, normalizing in some cases. * This passes through to the DOM node, allowing for custom attributes. * @param {string} name The attribute name * @param {string} value The value to set * Allows for removing attributes on DOM nodes. * This passes through to the DOM node, allowing for custom attributes. * @method removeAttribute * @param {string} name The attribute to remove * Removes the parent node from node in the list. * Wraps the given HTML around each node. * @param {String} html The markup to wrap around the node. * Applies a unique ID to each node if none exists * @return {String} The existing or generated ID },
'@VERSION@' ,{
requires:[
'dom-core',
'selector']});