#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# File: dom/js/dom-core.js

    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;