node-core.js revision 880f76ee227b05b889736151e137e61c7bbf950d
/**
* The Node Utility provides a DOM-like interface for interacting with DOM nodes.
* @module node
* @main node
* @submodule node-core
*/
/**
* The Node class provides a wrapper for manipulating DOM Nodes.
* Use `Y.one()` to retrieve Node instances.
*
* <strong>NOTE:</strong> Node properties are accessed using
* the <code>set</code> and <code>get</code> methods.
*
* @class Node
* @constructor
* @param {DOMNode} node the DOM node to be mapped to the Node instance.
* @uses EventTarget
*/
// "globals"
var DOT = '.',
NODE_NAME = 'nodeName',
NODE_TYPE = 'nodeType',
OWNER_DOCUMENT = 'ownerDocument',
TAG_NAME = 'tagName',
UID = '_yuid',
EMPTY_OBJ = {},
if (!this.getDOMNode) { // support optional "new"
}
if (typeof node == 'string') {
if (!node) {
return null; // NOTE: return
}
}
}
if (!uid) { // stamp failed; likely IE non-HTMLElement
}
/**
* The underlying DOM node bound to the Y.Node instance
* @property _node
* @private
*/
if (this._initPlugins) { // when augmented with Plugin.Host
this._initPlugins();
}
},
var ret = null;
if (fn) {
function(n) {
} :
function(n) {
};
}
return ret;
};
// end "globals"
Y_Node.DOM_EVENTS = {};
if (node) {
} else {
}
}
return node || null;
};
/**
* The name of the component
* @static
* @property NAME
*/
/*
* The pattern used to identify ARIA attributes
*/
/**
* A list of Node instances that have been created
* @private
* @property _instances
* @static
*
*/
Y_Node._instances = {};
/**
* Retrieves the DOM node bound to a Node instance
* @method getDOMNode
* @static
*
* @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.
*/
if (node) {
}
return null;
};
/**
* 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.
* @method scrubVal
* @static
*
* @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
}
}
} else if (typeof val === 'undefined') {
} else if (val === null) {
val = null; // IE: DOM null not the same as null
}
return val;
};
/**
* Adds methods to the Y.Node prototype, routing through scrubVal.
* @method addMethod
* @static
*
* @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.
*/
node = this,
ret;
}
}
if (ret) { // scrub truthy
}
return ret;
};
} else {
}
};
/**
* Imports utility methods to be added as Y.Node methods.
* @method importMethod
* @static
*
* @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') {
} else {
});
}
};
/**
* Retrieves a NodeList based on the given CSS selector.
* @method all
*
* @param {string} selector The CSS selector to test against.
* @return {NodeList} A NodeList instance for the matching HTMLCollection/Array.
* @for YUI
*/
/**
* 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.
* @method one
* @param {String | HTMLElement} node a node or Selector
* @return {Node | null} a Node instance or null if no match found.
* @for YUI
*/
/**
* 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.
* @method one
* @static
* @param {String | HTMLElement} node a node or Selector
* @return {Node | null} a Node instance or null if no match found.
* @for Node
*/
var instance = null,
uid;
if (node) {
if (typeof node == 'string') {
if (!node) {
return null; // NOTE: return
}
} else if (node.getDOMNode) {
return node; // NOTE: return
}
}
}
}
}
return instance;
};
/**
* The default setter for DOM properties
* Called with instance context (this === the Node instance)
* @method DEFAULT_SETTER
* @static
* @param {any} val The value to be set
* @return {any} The value
*/
var node = this._stateProxy,
// only allow when defined on node
}
return val;
};
/**
* The default getter for DOM properties
* Called with instance context (this === the Node instance)
* @method DEFAULT_GETTER
* @static
* @return {any} The current value
*/
var node = this._stateProxy,
val;
}
return val;
};
DATA_PREFIX: 'data-',
/**
* The method called when outputting Node instances as strings
* @method toString
* @return {String} A string representation of the Node instance
*/
toString: function() {
if (node) {
if (id) {
}
if (className) {
}
// TODO: add yuid?
}
return str;
},
/**
* Returns an attribute value on the Node instance.
* Unless pre-configured (via `Node.ATTRS`), get hands
* off to the underlying DOM node. Only valid
* attributes/properties for the node will be queried.
* @method get
* @param {String} attr The attribute
* @return {any} The current value of the attribute
*/
var val;
if (this._getAttr) { // use Attribute imple
} else {
}
if (val) {
} else if (val === null) {
val = null; // IE: DOM null is not true null (even though they ===)
}
return val;
},
/**
* Helper method for get.
* @method _get
* @private
* @param {String} attr The attribute
* @return {any} The current value of the attribute
*/
val;
} else {
}
return val;
},
/**
* Sets an attribute on the Node instance.
* Unless pre-configured (via Node.ATTRS), set hands
* off to the underlying DOM node. Only valid
* attributes/properties for the node will be set.
* To set custom attributes use setAttribute.
* @method set
* @param {String} attr The attribute to be set.
* @param {any} val The value to set the attribute to.
* @chainable
*/
if (this._setAttr) { // use Attribute imple
} else { // use setters inline
} else {
}
}
return this;
},
/**
* Sets multiple attributes.
* @method setAttrs
* @chainable
*/
if (this._setAttrs) { // use Attribute imple
} else { // use setters inline
this.set(n, v);
}, this);
}
return this;
},
/**
* Returns an object containing the values for the requested attributes.
* @method getAttrs
* @param {Array} attrs an array of attributes to get values
*/
var ret = {};
if (this._getAttrs) { // use Attribute imple
} else { // use setters inline
}, this);
}
return ret;
},
/**
* Compares nodes to determine if they match.
* @method compareTo
* @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.
* @method inDoc
* @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.
*/
if (doc.documentElement) {
}
},
} else {
ret = null;
}
return ret;
},
/**
* Returns the nearest ancestor that passes the test applied by supplied boolean method.
* @method ancestor
* @param {String | Function} fn A selector string or boolean method for testing elements.
* If a function is used, it receives the current node being tested as the only argument.
* @param {Boolean} testSelf optional Whether or not to include the element in the scan
* @param {String | Function} stopFn optional A selector string or boolean
* method to indicate when the search should stop. The search bails when the function
* returns true or the selector matches.
* 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
*/
// testSelf is optional, check for stopFn as 2nd arg
}
},
/**
* Returns the ancestors that pass the test applied by supplied boolean method.
* @method ancestors
* @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.
* @method previous
* @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.
* @method next
* @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.
* @method siblings
* @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.
* @method one
*
* @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.
* @method all
*
* @param {string} selector The CSS selector to test against.
* @return {NodeList} A NodeList instance for the matching HTMLCollection/Array.
*/
return nodelist;
},
// TODO: allow fn test
/**
* Test if the supplied node matches the supplied selector.
* @method test
*
* @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);
* @method remove
* @param {Boolean} destroy whether or not to call destroy() on the node
* after removal.
* @chainable
*
*/
}
if (destroy) {
this.destroy();
}
return this;
},
/**
* 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);
* @method replace
* @param {Node | HTMLNode} newNode Node to be inserted
* @chainable
*
*/
if (typeof newNode == 'string') {
}
return this;
},
/**
* @method replaceChild
* @for Node
* @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
* @method destroy
* @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
this.unplug();
}
this.clearData();
if (recursive) {
if (instance) {
}
});
}
this._node = null;
this._stateProxy = null;
},
/**
* Invokes a method on the Node instance
* @method invoke
* @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
*
*/
ret;
if (a && a._node) {
a = a._node;
}
if (b && b._node) {
b = b._node;
}
},
/**
* @method swap
* @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
* @chainable
*/
function(otherNode) {
} :
function(otherNode) {
if (nextSibling === node) {
} else {
}
return this;
},
},
isFragment: function() {
},
/**
* Removes and destroys all of the nodes within the node.
* @method empty
* @chainable
*/
empty: function() {
return this;
},
/**
* Returns the DOM node bound to the Node instance
* @method getDOMNode
* @return {DOMNode}
*/
getDOMNode: function() {
return this._node;
}
}, true);
/**
* The NodeList module provides support for managing collections of Nodes.
* @module node
* @submodule node-core
*/
/**
* The NodeList class provides a wrapper for manipulating DOM NodeLists.
* Use Y.all() to retrieve NodeList instances.
*
* @class NodeList
* @constructor
*/
var tmp = [];
if (nodes) {
}
});
}
}
/**
* The underlying array of DOM nodes bound to the Y.NodeList instance
* @property _nodes
* @private
*/
};
/**
* Retrieves the DOM nodes bound to a NodeList instance
* @method getDOMNodes
* @static
*
* @param {NodeList} nodelist The NodeList instance
* @return {Array} The array of DOM nodes bound to the NodeList
*/
};
} else {
}
};
var ret = [],
ctx,
if (!instance) {
}
}
});
// TODO: remove tmp pointer
};
} else {
}
};
if (typeof name === 'string') {
} else {
});
}
};
if (!tmp) {
}
return tmp;
};
/**
* Retrieves the Node instance at the given index.
* @method item
*
* @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.
* @method each
* @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
* @chainable
*/
var instance = this;
});
return instance;
},
var nodelist = this;
if (!instance) {
}
});
return nodelist;
},
/**
* Executes the function once for each node until a true value is returned.
* @method some
* @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.
*/
var instance = this;
});
},
/**
* Creates a documenFragment from the nodes bound to the NodeList instance
* @method toFrag
* @return {Node} a Node instance bound to the documentFragment
*/
toFrag: function() {
},
/**
* Returns the index of the node in the NodeList instance
* or -1 if the node isn't found.
* @method indexOf
* @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.
* @method filter
* @param {String} selector The selector to filter against
* @return {NodeList} NodeList containing the updated collection
* @see Selector
*/
},
/**
* Creates a new NodeList containing all nodes at every n indices, where
* remainder n % index equals r.
* (zero-based index).
* @method modulus
* @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
*/
modulus: function(n, r) {
r = r || 0;
var nodes = [];
if (i % n === r) {
}
});
},
/**
* Creates a new NodeList containing all nodes at odd indices
* (zero-based index).
* @method odd
* @return {NodeList} NodeList containing the updated collection
*/
odd: function() {
},
/**
* Creates a new NodeList containing all nodes at even indices
* (zero-based index), including zero.
* @method even
* @return {NodeList} NodeList containing the updated collection
*/
even: function() {
return this.modulus(2);
},
destructor: function() {
},
/**
* Reruns the initial query, when created using a selector query
* @method refresh
* @chainable
*/
refresh: function() {
var doc,
root = this._queryRoot;
if (query) {
if (!root) {
}
}
}
return this;
},
} else {
}
return args;
},
/**
* Applies an event listener to each Node bound to the NodeList.
* @method on
* @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
* when the event fires.
* @return {Object} Returns an event handle that can later be use to detach().
* @see Event.on
*/
},
/**
* Applies an one-time event listener to each Node bound to the NodeList.
* @method once
* @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().
* @see Event.on
*/
},
/**
* 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.
* @method after
* @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().
* @see Event.on
*/
},
/**
* Returns the current number of items in the NodeList.
* @method size
* @return {Int} The number of items in the NodeList.
*/
size: function() {
},
/**
* Determines if the instance is bound to any nodes
* @method isEmpty
* @return {Boolean} Whether or not the NodeList is bound to any nodes
*/
isEmpty: function() {
},
toString: function() {
var str = '',
node;
}
}
}
}
},
/**
* Returns the DOM node bound to the Node instance
* @method getDOMNodes
* @return {Array}
*/
getDOMNodes: function() {
return this._nodes;
}
}, true);
/** Called on each Node instance
* @method destroy
* @see Node.destroy
*/
'destroy',
/** Called on each Node instance
* @method empty
* @see Node.empty
*/
'empty',
/** Called on each Node instance
* @method remove
* @see Node.remove
*/
'remove',
/** Called on each Node instance
* @method set
* @see Node.set
*/
'set'
]);
// one-off implementation to convert array of Nodes to NodeList
// e.g. Y.all('input').get('parentNode');
/** Called on each Node instance
* @method get
* @see Node
*/
var ret = [],
isNodeList = false,
val;
if (nodes[0]) {
isNodeList = true;
}
}
if (!instance) {
}
if (!isNodeList) { // convert array of Nodes to NodeList
}
});
};
};
/**
* @module node
* @submodule node-core
*/
var Y_NodeList = Y.NodeList,
ArrayProto = Array.prototype,
ArrayMethods = {
/** Returns a new NodeList combining the given NodeList(s)
* @for NodeList
* @method concat
* concatenate to the resulting NodeList
* @return {NodeList} A new NodeList comprised of this NodeList joined with the input.
*/
'concat': 1,
/** Removes the last from the NodeList and returns it.
* @for NodeList
* @method pop
* @return {Node} The last item in the NodeList.
*/
'pop': 0,
/** Adds the given Node(s) to the end of the NodeList.
* @for NodeList
* @method push
* @param {Node | DOMNode} nodes One or more nodes to add to the end of the NodeList.
*/
'push': 0,
/** Removes the first item from the NodeList and returns it.
* @for NodeList
* @method shift
* @return {Node} The first item in the NodeList.
*/
'shift': 0,
/** Returns a new NodeList comprising the Nodes in the given range.
* @for NodeList
* @method slice
* @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.
*/
'slice': 1,
/** Changes the content of the NodeList, adding new elements while removing old elements.
* @for NodeList
* @method splice
* @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.
*/
'splice': 1,
/** Adds the given Node(s) to the beginning of the NodeList.
* @for NodeList
* @method unshift
* @param {Node | DOMNode} nodes One or more nodes to add to the NodeList.
*/
'unshift': 0
};
var args = [],
i = 0,
arg,
ret;
}
if (returnNodeList) {
} else {
}
return ret;
};
});
/**
* @module node
* @submodule node-core
*/
Y.Array.each([
/**
* Passes through to DOM method.
* @for Node
* @method removeChild
* @param {HTMLElement | Node} node Node to be removed
* @return {Node} The removed node
*/
'removeChild',
/**
* Passes through to DOM method.
* @method hasChildNodes
* @return {Boolean} Whether or not the node has any childNodes
*/
'hasChildNodes',
/**
* Passes through to DOM method.
* @method cloneNode
* @param {Boolean} deep Whether or not to perform a deep clone, which includes
* subtree and attributes
* @return {Node} The clone
*/
'cloneNode',
/**
* Passes through to DOM method.
* @method hasAttribute
* @param {String} attribute The attribute to test for
* @return {Boolean} Whether or not the attribute is present
*/
'hasAttribute',
/**
* Passes through to DOM method.
* @method scrollIntoView
* @chainable
*/
'scrollIntoView',
/**
* Passes through to DOM method.
* @method getElementsByTagName
* @param {String} tagName The tagName to collect
* @return {NodeList} A NodeList representing the HTMLCollection
*/
'getElementsByTagName',
/**
* Passes through to DOM method.
* @method focus
* @chainable
*/
'focus',
/**
* Passes through to DOM method.
* @method blur
* @chainable
*/
'blur',
/**
* Passes through to DOM method.
* Only valid on FORM elements
* @method submit
* @chainable
*/
'submit',
/**
* Passes through to DOM method.
* Only valid on FORM elements
* @method reset
* @chainable
*/
'reset',
/**
* Passes through to DOM method.
* @method select
* @chainable
*/
'select',
/**
* Passes through to DOM method.
* Only valid on TABLE elements
* @method createCaption
* @chainable
*/
'createCaption'
], function(method) {
return ret;
};
});
/**
* Passes through to DOM method.
* @method removeAttribute
* @param {String} attribute The attribute to be removed
* @chainable
*/
// one-off implementation due to IE returning boolean, breaking chaining
if (node) {
}
return this;
};
/**
* Determines whether the node is an ancestor of another HTML element in the DOM hierarchy.
* @method contains
* @param {Node | HTMLElement} needle The possible node or descendent
* @return {Boolean} Whether or not this node is the needle its ancestor
*/
'contains',
/**
* Allows setting attributes on DOM nodes, normalizing in some cases.
* This passes through to the DOM node, allowing for custom attributes.
* @method setAttribute
* @for Node
* @for NodeList
* @chainable
* @param {string} name The attribute name
* @param {string} value The value to set
*/
'setAttribute',
/**
* Allows getting attributes on DOM nodes, normalizing in some cases.
* This passes through to the DOM node, allowing for custom attributes.
* @method getAttribute
* @for Node
* @for NodeList
* @param {string} name The attribute name
* @return {string} The attribute value
*/
'getAttribute',
/**
* Wraps the given HTML around the node.
* @method wrap
* @param {String} html The markup to wrap around the node.
* @chainable
* @for Node
*/
'wrap',
/**
* Removes the node's parent node.
* @method unwrap
* @chainable
*/
'unwrap',
/**
* Applies a unique ID to the node if none exists
* @method generateID
* @return {String} The existing or generated ID
*/
'generateID'
]);
/**
* Allows getting attributes on DOM nodes, normalizing in some cases.
* This passes through to the DOM node, allowing for custom attributes.
* @method getAttribute
* @see Node
* @for NodeList
* @param {string} name The attribute name
* @return {string} The attribute value
*/
'getAttribute',
/**
* Allows setting attributes on DOM nodes, normalizing in some cases.
* This passes through to the DOM node, allowing for custom attributes.
* @method setAttribute
* @see Node
* @for NodeList
* @chainable
* @param {string} name The attribute name
* @param {string} value The value to set
*/
'setAttribute',
/**
* Allows for removing attributes on DOM nodes.
* This passes through to the DOM node, allowing for custom attributes.
* @method removeAttribute
* @see Node
* @for NodeList
* @param {string} name The attribute to remove
*/
'removeAttribute',
/**
* Removes the parent node from node in the list.
* @method unwrap
* @chainable
*/
'unwrap',
/**
* Wraps the given HTML around each node.
* @method wrap
* @param {String} html The markup to wrap around the node.
* @chainable
*/
'wrap',
/**
* Applies a unique ID to each node if none exists
* @method generateID
* @return {String} The existing or generated ID
*/
'generateID'
]);