/**
* The Node Utility provides a DOM-like interface for interacting with DOM nodes.
* @module node
* @submodule node-base
*/
/**
* The Node class provides a wrapper for manipulating DOM Nodes.
* Node properties can be accessed via the set/get methods.
* Use Y.get() to retrieve Node instances.
*
* <strong>NOTE:</strong> Node properties are accessed using
* the <code>set</code> and <code>get</code> methods.
*
* @class Node
* @constructor
* @for Node
*/
// "globals"
var g_nodes = {},
g_nodelists = {},
g_restrict = {},
g_slice = Array.prototype.slice,
DOT = '.',
NODE_NAME = 'nodeName',
NODE_TYPE = 'nodeType',
OWNER_DOCUMENT = 'ownerDocument',
TAG_NAME = 'tagName',
UID = '_yuid',
SuperConstr = Y.Base,
SuperConstrProto = Y.Base.prototype,
Node = function(node, restricted) {
var config = null;
this[UID] = Y.stamp(node);
if (!this[UID]) { // stamp failed; likely IE non-HTMLElement
this[UID] = Y.guid();
}
g_nodes[this[UID]] = node;
Node._instances[this[UID]] = this;
if (restricted) {
config = {
restricted: restricted
};
g_restrict[this[UID]] = true;
}
this._lazyAttrInit = true;
this._silentInit = true;
SuperConstr.call(this, config);
},
// used with previous/next/ancestor tests
_wrapFn = function(fn) {
var ret = null;
if (fn) {
ret = (typeof fn === 'string') ?
function(n) {
return Y.Selector.test(n, fn);
} :
function(n) {
return fn(Node.get(n));
};
}
return ret;
};
// end "globals"
Node.NAME = 'Node';
Node.DOM_EVENTS = {
abort: true,
blur: true,
change: true,
click: true,
close: true,
command: true,
contextmenu: true,
drag: true,
dragstart: true,
dragenter: true,
dragover: true,
dragleave: true,
dragend: true,
drop: true,
dblclick: true,
error: true,
focus: true,
keydown: true,
keypress: true,
keyup: true,
load: true,
mousedown: true,
mousemove: true,
mouseout: true,
mouseover: true,
mouseup: true,
mousemultiwheel: true,
mousewheel: true,
submit: true,
mouseenter: true,
mouseleave: true,
scroll: true,
reset: true,
resize: true,
select: true,
textInput: true,
unload: true
};
// Add custom event adaptors to this list. This will make it so
// that delegate, key, available, contentready, etc all will
// be available through Node.on
Y.mix(Node.DOM_EVENTS, Y.Env.evt.plugins);
Node._instances = {};
/**
* Registers plugins to be instantiated at the class level (plugins
* which should be plugged into every instance of Node by default).
*
* @method Node.plug
* @static
*
* @param {Function | Array} plugin Either the plugin class, an array of plugin classes or an array of objects (with fn and cfg properties defined)
* @param {Object} config (Optional) If plugin is the plugin class, the configuration for the plugin
*/
Node.plug = function() {
var args = g_slice.call(arguments, 0);
args.unshift(Node);
Y.Base.plug.apply(Y.Base, args);
return Node;
};
/**
* Unregisters any class level plugins which have been registered by the Node
*
* @method Node.unplug
* @static
*
* @param {Function | Array} plugin The plugin class, or an array of plugin classes
*/
Node.unplug = function() {
var args = g_slice.call(arguments, 0);
args.unshift(Node);
Y.Base.unplug.apply(Y.Base, args);
return Node;
};
/**
* Retrieves the DOM node bound to a Node instance
* @method Node.getDOMNode
* @static
*
* @param {Y.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.
*/
Node.getDOMNode = function(node) {
if (node) {
if (node instanceof Node) {
node = g_nodes[node[UID]];
} else if (!node[NODE_NAME] || Y.DOM.isWindow(node)) { // must already be a DOMNode
node = null;
}
}
return node || null;
};
Node.scrubVal = function(val, node, depth) {
if (node && val) { // only truthy values are risky
if (typeof val === 'object' || typeof val === 'function') { // safari nodeList === function
if (NODE_TYPE in val || Y.DOM.isWindow(val)) {// node || window
if (g_restrict[node[UID]] && !node.contains(val)) {
val = null; // not allowed to go outside of root node
} else {
val = Node.get(val);
}
} else if (val.item || // dom collection or Node instance // TODO: check each node for restrict? block ancestor?
(val[0] && val[0][NODE_TYPE])) { // array of DOM Nodes
val = Y.all(val);
} else {
depth = (depth === undefined) ? 4 : depth;
if (depth > 0) {
for (var i in val) { // TODO: test this and pull hasOwnProperty check if safe?
if (val.hasOwnProperty && val.hasOwnProperty(i)) {
val[i] = Node.scrubVal(val[i], node, --depth);
}
}
}
}
}
} else if (val === undefined) {
val = node; // for chaining
}
return val;
};
Node.addMethod = function(name, fn, context) {
if (name && fn && typeof fn === 'function') {
Node.prototype[name] = function() {
context = context || this;
var args = g_slice.call(arguments),
ret;
if (args[0] && args[0] instanceof Node) {
args[0] = Node.getDOMNode(args[0]);
}
if (args[1] && args[1] instanceof Node) {
args[1] = Node.getDOMNode(args[1]);
}
args.unshift(g_nodes[this[UID]]);
ret = Node.scrubVal(fn.apply(context, args), this);
return ret;
};
} else {
Y.log('unable to add method: ' + name, 'warn', 'Node');
}
};
Node.importMethod = function(host, name, altName) {
if (typeof name === 'string') {
altName = altName || name;
Node.addMethod(altName, host[name], host);
} else {
Y.each(name, function(n) {
Node.importMethod(host, n);
});
}
};
/**
* Returns a single Node instance bound to the node or the
* first element matching the given selector.
* @method Y.get
* @static
* @param {String | HTMLElement} node a node or Selector
* @param {Y.Node || HTMLElement} doc an optional document to scan. Defaults to Y.config.doc.
* @param {Boolean} restrict Whether or not the Node instance should be restricted to accessing
* its subtree only.
*/
Node.get = function(node, doc, restrict) {
var instance = null;
if (typeof node === 'string') {
if (node.indexOf('doc') === 0) { // doc OR document
node = Y.config.doc;
} else if (node.indexOf('win') === 0) { // doc OR document
node = Y.config.win;
} else {
node = Y.Selector.query(node, doc, true);
}
}
if (node) {
instance = Node._instances[node[UID]]; // reuse exising instances
if (!instance) {
instance = new Node(node, restrict);
} else if (restrict) {
g_restrict[instance[UID]] = true;
instance._set('restricted', true);
}
}
// TODO: restrict on subsequent call?
return instance;
};
/**
* Creates a new dom node using the provided markup string.
* @method create
* @static
* @param {String} html The markup used to create the element
* @param {HTMLDocument} doc An optional document context
*/
Node.create = function() {
return Node.get(Y.DOM.create.apply(Y.DOM, arguments));
};
Node.ATTRS = {
/**
* Allows for getting and setting the text of an element.
* Formatting is preserved and special characters are treated literally.
* @config text
* @type String
*/
text: {
getter: function() {
return Y.DOM.getText(g_nodes[this[UID]]);
},
setter: function(content) {
Y.DOM.setText(g_nodes[this[UID]], content);
return content;
}
},
'options': {
getter: function() {
return this.getElementsByTagName('option');
}
},
/**
* Returns a NodeList instance of all HTMLElement children.
* @readOnly
* @config children
* @type NodeList
*/
'children': {
getter: function() {
var node = g_nodes[this[UID]],
children = node.children,
childNodes, i, len;
if (children === undefined) {
childNodes = node.childNodes;
children = [];
for (i = 0, len = childNodes.length; i < len; ++i) {
if (childNodes[i][TAG_NAME]) {
children[children.length] = childNodes[i];
}
}
}
return Y.all(children);
}
},
value: {
getter: function() {
return Y.DOM.getValue(g_nodes[this[UID]]);
},
setter: function(val) {
Y.DOM.setValue(g_nodes[this[UID]], val);
return val;
}
},
/*
style: {
getter: function(attr) {
return Y.DOM.getStyle(g_nodes[this[UID]].style, attr);
}
},
*/
/**
* Whether or not this Node can traverse outside of its subtree.
* @config restricted
* @writeOnce
* @type Boolean
*/
restricted: {
writeOnce: true,
value: false
}
};
// call with instance context
Node.DEFAULT_SETTER = function(name, val) {
var node = g_nodes[this[UID]],
strPath;
if (name.indexOf(DOT) > -1) {
strPath = name;
name = name.split(DOT);
Y.Object.setValue(node, name, val);
} else if (node[name] !== undefined) { // only set DOM attributes
node[name] = val;
}
return val;
};
// call with instance context
Node.DEFAULT_GETTER = function(name) {
var node = g_nodes[this[UID]],
val;
if (name.indexOf && name.indexOf(DOT) > -1) {
val = Y.Object.getValue(node, name.split(DOT));
} else {
val = node[name];
}
return val ? Y.Node.scrubVal(val, this) : val;
};
Y.extend(Node, Y.Base);
Y.mix(Node.prototype, {
toString: function() {
var str = '',
errorMsg = this[UID] + ': not bound to a node',
node = g_nodes[this[UID]];
if (node) {
str += node[NODE_NAME];
if (node.id) {
str += '#' + node.id;
}
if (node.className) {
str += '.' + node.className.replace(' ', '.');
}
// TODO: add yuid?
str += ' ' + this[UID];
}
return str || errorMsg;
},
_addDOMAttr: function(attr) {
var domNode = g_nodes[this[UID]];
if (domNode && domNode[attr] !== undefined) {
this.addAttr(attr, {
getter: function() {
return Node.DEFAULT_GETTER.call(this, attr);
},
setter: function(val) {
return Node.DEFAULT_SETTER.call(this, attr, val);
}
});
} else {
Y.log('unable to add DOM attribute: ' + attr + ' to node: ' + this, 'warn', 'Node');
}
},
get: function(attr) {
if (!this.attrAdded(attr)) { // use DEFAULT_GETTER for unconfigured attrs
if (Node.re_aria && Node.re_aria.test(attr)) { // except for aria
this._addAriaAttr(attr);
} else {
return Node.DEFAULT_GETTER.apply(this, arguments);
}
}
return SuperConstrProto.get.apply(this, arguments);
},
set: function(attr, val) {
if (!this.attrAdded(attr)) { // use DEFAULT_SETTER for unconfigured attrs
// except for aria
if (Node.re_aria && Node.re_aria.test(attr)) {
this._addAriaAttr(attr);
// or chained properties or if no change listeners
} else if (attr.indexOf(DOT) < 0 && this._yuievt.events['Node:' + attr + 'Change']) {
this._addDOMAttr(attr);
} else {
Node.DEFAULT_SETTER.call(this, attr, val);
return this; // NOTE: return
}
}
SuperConstrProto.set.apply(this, arguments);
return this;
},
/**
* Creates a new Node using the provided markup string.
* @method create
* @param {String} html The markup used to create the element
* @param {HTMLDocument} doc An optional document context
*/
create: Node.create,
/**
* Compares nodes to determine if they match.
* Node instances can be compared to each other and/or HTMLElements.
* @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.
*/
compareTo: function(refNode) {
var node = g_nodes[this[UID]];
if (refNode instanceof Y.Node) {
refNode = Y.Node.getDOMNode(refNode);
}
return node === refNode;
},
/**
* 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.
*/
inDoc: function(doc) {
var node = g_nodes[this[UID]];
doc = (doc) ? Node.getDOMNode(doc) : node[OWNER_DOCUMENT];
if (doc.documentElement) {
return Y.DOM.contains(doc.documentElement, node);
}
},
getById: function(id) {
var node = g_nodes[this[UID]],
ret = Y.DOM.byId(id, node[OWNER_DOCUMENT]);
if (ret && Y.DOM.contains(node, ret)) {
ret = Y.get(ret);
} 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 or boolean method for testing elements.
* 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
*/
ancestor: function(fn) {
return Node.get(Y.DOM.elementByAxis(g_nodes[this[UID]], 'parentNode', _wrapFn(fn)));
},
/**
* 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
*/
previous: function(fn, all) {
return Node.get(Y.DOM.elementByAxis(g_nodes[this[UID]], 'previousSibling', _wrapFn(fn), all));
},
/**
* 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
*/
next: function(node, fn, all) {
return Node.get(Y.DOM.elementByAxis(g_nodes[this[UID]], 'nextSibling', _wrapFn(fn), all));
},
/**
* Retrieves a Node instance of nodes based on the given CSS selector.
* @method query
*
* @param {string} selector The CSS selector to test against.
* @return {Node} A Node instance for the matching HTMLElement.
*/
query: function(selector) {
return Y.get(Y.Selector.query(selector, g_nodes[this[UID]], true));
},
/**
* Retrieves a nodeList based on the given CSS selector.
* @method queryAll
*
* @param {string} selector The CSS selector to test against.
* @return {NodeList} A NodeList instance for the matching HTMLCollection/Array.
*/
queryAll: function(selector) {
return Y.all(Y.Selector.query(selector, g_nodes[this[UID]]));
},
// 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.
*/
test: function(selector) {
return Y.Selector.test(g_nodes[this[UID]], selector);
},
/**
* Removes the node from its parent.
* Shortcut for myNode.get('parentNode').removeChild(myNode);
* @method remove
* @chainable
*
*/
remove: function() {
var node = g_nodes[this[UID]];
node.parentNode.removeChild(node);
return this;
},
/**
* 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
* are converted to Node/NodeList instances.
*
*/
invoke: function(method, a, b, c, d, e) {
var node = g_nodes[this[UID]],
ret;
if (a && a instanceof Y.Node) {
a = Node.getDOMNode(a);
}
if (b && b instanceof Y.Node) {
b = Node.getDOMNode(b);
}
ret = node[method](a, b, c, d, e);
return Y.Node.scrubVal(ret, this);
},
destructor: function() {
// TODO: What about shared instances?
//var uid = this[UID];
//delete g_nodes[uid];
//delete g_restrict[uid];
//delete Node._instances[uid];
},
/**
* Applies the given function to each Node in the NodeList.
* @method each
* @deprecated Use NodeList
* @param {Function} fn The function to apply
* @param {Object} context optional An optional context to apply the function with
* Default context is the NodeList instance
* @chainable
*/
each: function(fn, context) {
context = context || this;
Y.log('each is deprecated on Node', 'warn', 'Node');
return fn.call(context, this);
},
/**
* Retrieves the Node instance at the given index.
* @method item
* @deprecated Use NodeList
*
* @param {Number} index The index of the target Node.
* @return {Node} The Node instance at the given index.
*/
item: function(index) {
Y.log('item is deprecated on Node', 'warn', 'Node');
return this;
},
/**
* Returns the current number of items in the Node.
* @method size
* @deprecated Use NodeList
* @return {Int} The number of items in the Node.
*/
size: function() {
Y.log('size is deprecated on Node', 'warn', 'Node');
return g_nodes[this[UID]] ? 1 : 0;
},
/**
* Inserts the content before the reference node.
* @method insert
* @param {String | Y.Node | HTMLElement} content The content to insert
* @param {Int | Y.Node | HTMLElement | String} where The position to insert at.
* @chainable
*/
insert: function(content, where) {
if (content) {
if (typeof where === 'number') { // allow index
where = g_nodes[this[UID]].childNodes[where];
}
if (typeof content !== 'string') { // pass the DOM node
content = Y.Node.getDOMNode(content);
}
if (!where || // only allow inserting into this Node's subtree
(!g_restrict[this[UID]] ||
(typeof where !== 'string' && this.contains(where)))) {
Y.DOM.addHTML(g_nodes[this[UID]], content, where);
}
}
return this;
},
/**
* Inserts the content as the firstChild of the node.
* @method prepend
* @param {String | Y.Node | HTMLElement} content The content to insert
* @chainable
*/
prepend: function(content) {
return this.insert(content, 0);
},
/**
* Inserts the content as the lastChild of the node.
* @method append
* @param {String | Y.Node | HTMLElement} content The content to insert
* @chainable
*/
append: function(content) {
return this.insert(content, null);
},
/**
* Replaces the node's current content with the content.
* @method setContent
* @param {String | Y.Node | HTMLElement} content The content to insert
* @chainable
*/
setContent: function(content) {
Y.DOM.addHTML(g_nodes[this[UID]], content, 'replace');
return this;
},
// TODO: need this?
hasMethod: function(method) {
var node = g_nodes[this[UID]];
return (node && (typeof node === 'function'));
}
}, true);
Y.Node = Node;
Y.get = Y.Node.get;