var NODE_TYPE = 'nodeType',
OWNER_DOCUMENT = 'ownerDocument',
DOCUMENT_ELEMENT = 'documentElement',
DEFAULT_VIEW = 'defaultView',
PARENT_WINDOW = 'parentWindow',
TAG_NAME = 'tagName',
PARENT_NODE = 'parentNode',
PREVIOUS_SIBLING = 'previousSibling',
NEXT_SIBLING = 'nextSibling',
CONTAINS = 'contains',
COMPARE_DOCUMENT_POSITION = 'compareDocumentPosition',
EMPTY_ARRAY = [],
// IE < 8 throws on node.contains(textNode)
supportsContainsTextNode = (function() {
var node = Y.config.doc.createElement('div'),
textNode = node.appendChild(Y.config.doc.createTextNode('')),
result = false;
try {
result = node.contains(textNode);
} catch(e) {}
return result;
})(),
/**
* The DOM utility provides a cross-browser abtraction layer
* normalizing DOM tasks, and adds extra helper functionality
* for other common tasks.
* @module dom
* @main dom
* @submodule dom-base
* @for DOM
*
*/
/**
* Provides DOM helper methods.
* @class DOM
*
*/
Y_DOM = {
/**
* Returns the HTMLElement with the given ID (Wrapper for document.getElementById).
* @method byId
* @param {String} id the id attribute
* @param {Object} doc optional The document to search. Defaults to current document
* @return {HTMLElement | null} The HTMLElement with the id, or null if none found.
*/
byId: function(id, doc) {
// handle dupe IDs and IE name collision
return Y_DOM.allById(id, doc)[0] || null;
},
getId: function(node) {
var id;
// HTMLElement returned from FORM when INPUT name === "id"
// IE < 8: HTMLCollection returned when INPUT id === "id"
// via both getAttribute and form.id
if (node.id && !node.id.tagName && !node.id.item) {
id = node.id;
} else if (node.attributes && node.attributes.id) {
id = node.attributes.id.value;
}
return id;
},
setId: function(node, id) {
if (node.setAttribute) {
node.setAttribute('id', id);
} else {
node.id = id;
}
},
/*
* Finds the ancestor of the element.
* @method ancestor
* @param {HTMLElement} element The html element.
* @param {Function} fn optional An optional boolean test to apply.
* The optional function is passed the current DOM node being tested as its only argument.
* If no function is given, the parentNode is returned.
* @param {Boolean} testSelf optional Whether or not to include the element in the scan
* @return {HTMLElement | null} The matching DOM node or null if none found.
*/
ancestor: function(element, fn, testSelf, stopFn) {
var ret = null;
if (testSelf) {
ret = (!fn || fn(element)) ? element : null;
}
return ret || Y_DOM.elementByAxis(element, PARENT_NODE, fn, null, stopFn);
},
/*
* Finds the ancestors of the element.
* @method ancestors
* @param {HTMLElement} element The html element.
* @param {Function} fn optional An optional boolean test to apply.
* The optional function is passed the current DOM node being tested as its only argument.
* If no function is given, all ancestors are returned.
* @param {Boolean} testSelf optional Whether or not to include the element in the scan
* @return {Array} An array containing all matching DOM nodes.
*/
ancestors: function(element, fn, testSelf, stopFn) {
var ancestor = element,
ret = [];
while ((ancestor = Y_DOM.ancestor(ancestor, fn, testSelf, stopFn))) {
testSelf = false;
if (ancestor) {
ret.unshift(ancestor);
if (stopFn && stopFn(ancestor)) {
return ret;
}
}
}
return ret;
},
/**
* Searches the element by the given axis for the first matching element.
* @method elementByAxis
* @param {HTMLElement} element The html element.
* @param {String} axis The axis to search (parentNode, nextSibling, previousSibling).
* @param {Function} fn optional An optional boolean test to apply.
* @param {Boolean} all optional Whether all node types should be returned, or just element nodes.
* The optional function is passed the current HTMLElement being tested as its only argument.
* If no function is given, the first element is returned.
* @return {HTMLElement | null} The matching element or null if none found.
*/
elementByAxis: function(element, axis, fn, all, stopAt) {
while (element && (element = element[axis])) { // NOTE: assignment
if ( (all || element[TAG_NAME]) && (!fn || fn(element)) ) {
return element;
}
if (stopAt && stopAt(element)) {
return null;
}
}
return null;
},
/**
* Determines whether or not one HTMLElement is or contains another HTMLElement.
* @method contains
* @param {HTMLElement} element The containing html element.
* @param {HTMLElement} needle The html element that may be contained.
* @return {Boolean} Whether or not the element is or contains the needle.
*/
contains: function(element, needle) {
var ret = false;
if ( !needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {
ret = false;
} else if (element[CONTAINS] &&
// IE < 8 throws on node.contains(textNode) so fall back to brute.
// Falling back for other nodeTypes as well.
(needle[NODE_TYPE] === 1 || supportsContainsTextNode)) {
ret = element[CONTAINS](needle);
} else if (element[COMPARE_DOCUMENT_POSITION]) {
// Match contains behavior (node.contains(node) === true).
// Needed for Firefox < 4.
if (element === needle || !!(element[COMPARE_DOCUMENT_POSITION](needle) & 16)) {
ret = true;
}
} else {
ret = Y_DOM._bruteContains(element, needle);
}
return ret;
},
/**
* Determines whether or not the HTMLElement is part of the document.
* @method inDoc
* @param {HTMLElement} element The containing html element.
* @param {HTMLElement} doc optional The document to check.
* @return {Boolean} Whether or not the element is attached to the document.
*/
inDoc: function(element, doc) {
var ret = false,
rootNode;
if (element && element.nodeType) {
(doc) || (doc = element[OWNER_DOCUMENT]);
rootNode = doc[DOCUMENT_ELEMENT];
// contains only works with HTML_ELEMENT
if (rootNode && rootNode.contains && element.tagName) {
ret = rootNode.contains(element);
} else {
ret = Y_DOM.contains(rootNode, element);
}
}
return ret;
},
allById: function(id, root) {
root = root || Y.config.doc;
var nodes = [],
ret = [],
i,
node;
if (root.querySelectorAll) {
ret = root.querySelectorAll('[id="' + id + '"]');
} else if (root.all) {
nodes = root.all(id);
if (nodes) {
// root.all may return HTMLElement or HTMLCollection.
// some elements are also HTMLCollection (FORM, SELECT).
if (nodes.nodeName) {
if (nodes.id === id) { // avoid false positive on name
ret.push(nodes);
nodes = EMPTY_ARRAY; // done, no need to filter
} else { // prep for filtering
nodes = [nodes];
}
}
if (nodes.length) {
// filter out matches on node.name
// and element.id as reference to element with id === 'id'
for (i = 0; node = nodes[i++];) {
if (node.id === id ||
(node.attributes && node.attributes.id &&
node.attributes.id.value === id)) {
ret.push(node);
}
}
}
}
} else {
ret = [Y_DOM._getDoc(root).getElementById(id)];
}
return ret;
},
isWindow: function(obj) {
return !!(obj && obj.scrollTo && obj.document);
},
_removeChildNodes: function(node) {
while (node.firstChild) {
node.removeChild(node.firstChild);
}
},
siblings: function(node, fn) {
var nodes = [],
sibling = node;
while ((sibling = sibling[PREVIOUS_SIBLING])) {
if (sibling[TAG_NAME] && (!fn || fn(sibling))) {
nodes.unshift(sibling);
}
}
sibling = node;
while ((sibling = sibling[NEXT_SIBLING])) {
if (sibling[TAG_NAME] && (!fn || fn(sibling))) {
nodes.push(sibling);
}
}
return nodes;
},
/**
* Brute force version of contains.
* Used for browsers without contains support for non-HTMLElement Nodes (textNodes, etc).
* @method _bruteContains
* @private
* @param {HTMLElement} element The containing html element.
* @param {HTMLElement} needle The html element that may be contained.
* @return {Boolean} Whether or not the element is or contains the needle.
*/
_bruteContains: function(element, needle) {
while (needle) {
if (element === needle) {
return true;
}
needle = needle.parentNode;
}
return false;
},
// TODO: move to Lang?
/**
* Memoizes dynamic regular expressions to boost runtime performance.
* @method _getRegExp
* @private
* @param {String} str The string to convert to a regular expression.
* @param {String} flags optional An optinal string of flags.
* @return {RegExp} An instance of RegExp
*/
_getRegExp: function(str, flags) {
flags = flags || '';
Y_DOM._regexCache = Y_DOM._regexCache || {};
if (!Y_DOM._regexCache[str + flags]) {
Y_DOM._regexCache[str + flags] = new RegExp(str, flags);
}
return Y_DOM._regexCache[str + flags];
},
// TODO: make getDoc/Win true privates?
/**
* returns the appropriate document.
* @method _getDoc
* @private
* @param {HTMLElement} element optional Target element.
* @return {Object} The document for the given element or the default document.
*/
_getDoc: function(element) {
var doc = Y.config.doc;
if (element) {
doc = (element[NODE_TYPE] === 9) ? element : // element === document
element[OWNER_DOCUMENT] || // element === DOM node
element.document || // element === window
Y.config.doc; // default
}
return doc;
},
/**
* returns the appropriate window.
* @method _getWin
* @private
* @param {HTMLElement} element optional Target element.
* @return {Object} The window for the given element or the default window.
*/
_getWin: function(element) {
var doc = Y_DOM._getDoc(element);
return doc[DEFAULT_VIEW] || doc[PARENT_WINDOW] || Y.config.win;
},
_batch: function(nodes, fn, arg1, arg2, arg3, etc) {
fn = (typeof fn === 'string') ? Y_DOM[fn] : fn;
var result,
i = 0,
node,
ret;
if (fn && nodes) {
while ((node = nodes[i++])) {
result = result = fn.call(Y_DOM, node, arg1, arg2, arg3, etc);
if (typeof result !== 'undefined') {
(ret) || (ret = []);
ret.push(result);
}
}
}
return (typeof ret !== 'undefined') ? ret : nodes;
},
generateID: function(el) {
var id = el.id;
if (!id) {
id = Y.stamp(el);
el.id = id;
}
return id;
}
};
Y.DOM = Y_DOM;
