dom-core-debug.js revision 1d333b733400efc53b37b082c38679927b539b2f
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass COMPARE_DOCUMENT_POSITION = 'compareDocumentPosition',
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * The DOM utility provides a cross-browser abtraction layer
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * normalizing DOM tasks, and adds extra helper functionality
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * for other common tasks.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @module dom
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @submodule dom-base
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Provides DOM helper methods.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @class DOM
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Returns the HTMLElement with the given ID (Wrapper for document.getElementById).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method byId
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String} id the id attribute
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Object} doc optional The document to search. Defaults to current document
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {HTMLElement | null} The HTMLElement with the id, or null if none found.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // handle dupe IDs and IE name collision
1d333b733400efc53b37b082c38679927b539b2fMatt Sweeney // HTMLElement returned from FORM when INPUT name === "id"
1d333b733400efc53b37b082c38679927b539b2fMatt Sweeney // IE < 8: HTMLCollection returned when INPUT id === "id"
1d333b733400efc53b37b082c38679927b539b2fMatt Sweeney // via both getAttribute and form.id
1d333b733400efc53b37b082c38679927b539b2fMatt Sweeney if (node.id && !node.id.tagName && !node.id.item) {
1d333b733400efc53b37b082c38679927b539b2fMatt Sweeney } else if (node.attributes && node.attributes.id) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Finds the ancestor of the element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method ancestor
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element The html element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Function} fn optional An optional boolean test to apply.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * The optional function is passed the current DOM node being tested as its only argument.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * If no function is given, the parentNode is returned.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Boolean} testSelf optional Whether or not to include the element in the scan
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {HTMLElement | null} The matching DOM node or null if none found.
deb3172da8a688abb44a22d5b084c4dd0437df89Matt Sweeney ancestor: function(element, fn, testSelf, stopFn) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass var ret = null;
deb3172da8a688abb44a22d5b084c4dd0437df89Matt Sweeney return ret || Y_DOM.elementByAxis(element, PARENT_NODE, fn, null, stopFn);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Finds the ancestors of the element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method ancestors
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element The html element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Function} fn optional An optional boolean test to apply.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * The optional function is passed the current DOM node being tested as its only argument.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * If no function is given, all ancestors are returned.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Boolean} testSelf optional Whether or not to include the element in the scan
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Array} An array containing all matching DOM nodes.
deb3172da8a688abb44a22d5b084c4dd0437df89Matt Sweeney ancestors: function(element, fn, testSelf, stopFn) {
deb3172da8a688abb44a22d5b084c4dd0437df89Matt Sweeney while ((ancestor = Y_DOM.ancestor(ancestor, fn, testSelf, stopFn))) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Searches the element by the given axis for the first matching element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method elementByAxis
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element The html element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String} axis The axis to search (parentNode, nextSibling, previousSibling).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Function} fn optional An optional boolean test to apply.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Boolean} all optional Whether all node types should be returned, or just element nodes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * The optional function is passed the current HTMLElement being tested as its only argument.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * If no function is given, the first element is returned.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {HTMLElement | null} The matching element or null if none found.
80d53e62b2ae5fa5ab6ae4fbcfcbfd8ef5764dd7Matt Sweeney elementByAxis: function(element, axis, fn, all, stopAt) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass while (element && (element = element[axis])) { // NOTE: assignment
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass if ( (all || element[TAG_NAME]) && (!fn || fn(element)) ) {
80d53e62b2ae5fa5ab6ae4fbcfcbfd8ef5764dd7Matt Sweeney return null;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return null;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Determines whether or not one HTMLElement is or contains another HTMLElement.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method contains
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element The containing html element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} needle The html element that may be contained.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Boolean} Whether or not the element is or contains the needle.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass var ret = false;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass if ( !needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass if (Y.UA.opera || needle[NODE_TYPE] === 1) { // IE & SAF contains fail if needle not an ELEMENT_NODE
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass } else if (element[COMPARE_DOCUMENT_POSITION]) { // gecko
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass if (element === needle || !!(element[COMPARE_DOCUMENT_POSITION](needle) & 16)) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Determines whether or not the HTMLElement is part of the document.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method inDoc
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element The containing html element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} doc optional The document to check.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Boolean} Whether or not the element is attached to the document.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass var ret = false,
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // contains only works with HTML_ELEMENT
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass if (rootNode && rootNode.contains && element.tagName) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // root.all may return HTMLElement or HTMLCollection.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // some elements are also HTMLCollection (FORM, SELECT).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass if (nodes.id === id) { // avoid false positive on name
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass } else { // prep for filtering
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // filter out matches on node.name
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // and element.id as reference to element with id === 'id'
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Brute force version of contains.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Used for browsers without contains support for non-HTMLElement Nodes (textNodes, etc).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method _bruteContains
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element The containing html element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} needle The html element that may be contained.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Boolean} Whether or not the element is or contains the needle.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return true;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return false;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass// TODO: move to Lang?
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Memoizes dynamic regular expressions to boost runtime performance.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method _getRegExp
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String} str The string to convert to a regular expression.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String} flags optional An optinal string of flags.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {RegExp} An instance of RegExp
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Y_DOM._regexCache[str + flags] = new RegExp(str, flags);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass// TODO: make getDoc/Win true privates?
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * returns the appropriate document.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method _getDoc
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element optional Target element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Object} The document for the given element or the default document.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass doc = (element[NODE_TYPE] === 9) ? element : // element === document
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass element[OWNER_DOCUMENT] || // element === DOM node
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * returns the appropriate window.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method _getWin
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {HTMLElement} element optional Target element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Object} The window for the given element or the default window.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return doc[DEFAULT_VIEW] || doc[PARENT_WINDOW] || Y.config.win;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass _batch: function(nodes, fn, arg1, arg2, arg3, etc) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass result = result = fn.call(Y_DOM, node, arg1, arg2, arg3, etc);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return (typeof ret !== 'undefined') ? ret : nodes;