WB 2.08.x

/*

Copyright (c) 2007, Yahoo! Inc. All rights reserved.

Code licensed under the BSD License:

http://developer.yahoo.net/yui/license.txt

version: 2.4.1

*/

/**

 * The dom module provides helper methods for manipulating Dom elements.

 * @module dom

 *

 */

(function() {

    var Y = YAHOO.util,     // internal shorthand

        getStyle,           // for load time browser branching

        setStyle,           // ditto

        id_counter = 0,     // for use with generateId

        propertyCache = {}, // for faster hyphen converts

        reClassNameCache = {},          // cache regexes for className

        document = window.document;     // cache for faster lookups

    // brower detection

    var isOpera = YAHOO.env.ua.opera,

        isSafari = YAHOO.env.ua.webkit,

        isGecko = YAHOO.env.ua.gecko,

        isIE = YAHOO.env.ua.ie;

    // regex cache

    var patterns = {

        HYPHEN: /(-[a-z])/i, // to normalize get/setStyle

        ROOT_TAG: /^body|html$/i // body for quirks mode, html for standards

    };

    var toCamel = function(property) {

        if ( !patterns.HYPHEN.test(property) ) {

            return property; // no hyphens

        }

        if (propertyCache[property]) { // already converted

            return propertyCache[property];

        }

        var converted = property;

        while( patterns.HYPHEN.exec(converted) ) {

            converted = converted.replace(RegExp.$1,

                    RegExp.$1.substr(1).toUpperCase());

        }

        propertyCache[property] = converted;

        return converted;

        //return property.replace(/-([a-z])/gi, function(m0, m1) {return m1.toUpperCase()}) // cant use function as 2nd arg yet due to safari bug

    };

    var getClassRegEx = function(className) {

        var re = reClassNameCache[className];

        if (!re) {

            re = new RegExp('(?:^|\\s+)' + className + '(?:\\s+|$)');

            reClassNameCache[className] = re;

        }

        return re;

    };

    // branching at load instead of runtime

    if (document.defaultView && document.defaultView.getComputedStyle) { // W3C DOM method

        getStyle = function(el, property) {

            var value = null;

            if (property == 'float') { // fix reserved word

                property = 'cssFloat';

            }

            var computed = document.defaultView.getComputedStyle(el, '');

            if (computed) { // test computed before touching for safari

                value = computed[toCamel(property)];

            }

            return el.style[property] || value;

        };

    } else if (document.documentElement.currentStyle && isIE) { // IE method

        getStyle = function(el, property) {

            switch( toCamel(property) ) {

                case 'opacity' :// IE opacity uses filter

                    var val = 100;

                    try { // will error if no DXImageTransform

                        val = el.filters['DXImageTransform.Microsoft.Alpha'].opacity;

                    } catch(e) {

                        try { // make sure its in the document

                            val = el.filters('alpha').opacity;

                        } catch(e) {

                            YAHOO.log('getStyle: IE filter failed',

                                    'error', 'Dom');

                        }

                    }

                    return val / 100;

                case 'float': // fix reserved word

                    property = 'styleFloat'; // fall through

                default:

                    // test currentStyle before touching

                    var value = el.currentStyle ? el.currentStyle[property] : null;

                    return ( el.style[property] || value );

            }

        };

    } else { // default to inline only

        getStyle = function(el, property) { return el.style[property]; };

    }

    if (isIE) {

        setStyle = function(el, property, val) {

            switch (property) {

                case 'opacity':

                    if ( YAHOO.lang.isString(el.style.filter) ) { // in case not appended

                        el.style.filter = 'alpha(opacity=' + val * 100 + ')';

                        if (!el.currentStyle || !el.currentStyle.hasLayout) {

                            el.style.zoom = 1; // when no layout or cant tell

                        }

                    }

                    break;

                case 'float':

                    property = 'styleFloat';

                default:

                el.style[property] = val;

            }

        };

    } else {

        setStyle = function(el, property, val) {

            if (property == 'float') {

                property = 'cssFloat';

            }

            el.style[property] = val;

        };

    }

    var testElement = function(node, method) {

        return node && node.nodeType == 1 && ( !method || method(node) );

    };

    /**

     * Provides helper methods for DOM elements.

     * @namespace YAHOO.util

     * @class Dom

     */

    YAHOO.util.Dom = {

        /**

         * Returns an HTMLElement reference.

         * @method get

         * @param {String | HTMLElement |Array} el Accepts a string to use as an ID for getting a DOM reference, an actual DOM reference, or an Array of IDs and/or HTMLElements.

         * @return {HTMLElement | Array} A DOM reference to an HTML element or an array of HTMLElements.

         */

        get: function(el) {

            if (el && (el.tagName || el.item)) { // HTMLElement, or HTMLCollection

                return el;

            }

            if (YAHOO.lang.isString(el) || !el) { // HTMLElement or null

                return document.getElementById(el);

            }

            if (el.length !== undefined) { // array-like

                var c = [];

                for (var i = 0, len = el.length; i < len; ++i) {

                    c[c.length] = Y.Dom.get(el[i]);

                }

                return c;

            }

            return el; // some other object, just pass it back

        },

        /**

         * Normalizes currentStyle and ComputedStyle.

         * @method getStyle

         * @param {String | HTMLElement |Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.

         * @param {String} property The style property whose value is returned.

         * @return {String | Array} The current value of the style property for the element(s).

         */

        getStyle: function(el, property) {

            property = toCamel(property);

            var f = function(element) {

                return getStyle(element, property);

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Wrapper for setting style properties of HTMLElements.  Normalizes "opacity" across modern browsers.

         * @method setStyle

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.

         * @param {String} property The style property to be set.

         * @param {String} val The value to apply to the given property.

         */

        setStyle: function(el, property, val) {

            property = toCamel(property);

            var f = function(element) {

                setStyle(element, property, val);

                YAHOO.log('setStyle setting ' + property + ' to ' + val, 'info', 'Dom');

            };

            Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Gets the current position of an element based on page coordinates.  Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

         * @method getXY

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements

         * @return {Array} The XY position of the element(s)

         */

        getXY: function(el) {

            var f = function(el) {

                // has to be part of document to have pageXY

                if ( (el.parentNode === null || el.offsetParent === null ||

                        this.getStyle(el, 'display') == 'none') && el != el.ownerDocument.body) {

                    YAHOO.log('getXY failed: element not available', 'error', 'Dom');

                    return false;

                }

                YAHOO.log('getXY returning ' + getXY(el), 'info', 'Dom');

                return getXY(el);

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Gets the current X position of an element based on page coordinates.  The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

         * @method getX

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements

         * @return {Number | Array} The X position of the element(s)

         */

        getX: function(el) {

            var f = function(el) {

                return Y.Dom.getXY(el)[0];

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Gets the current Y position of an element based on page coordinates.  Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

         * @method getY

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements

         * @return {Number | Array} The Y position of the element(s)

         */

        getY: function(el) {

            var f = function(el) {

                return Y.Dom.getXY(el)[1];

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Set the position of an html element in page coordinates, regardless of how the element is positioned.

         * The element(s) must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

         * @method setXY

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements

         * @param {Array} pos Contains X & Y values for new position (coordinates are page-based)

         * @param {Boolean} noRetry By default we try and set the position a second time if the first fails

         */

        setXY: function(el, pos, noRetry) {

            var f = function(el) {

                var style_pos = this.getStyle(el, 'position');

                if (style_pos == 'static') { // default to relative

                    this.setStyle(el, 'position', 'relative');

                    style_pos = 'relative';

                }

                var pageXY = this.getXY(el);

                if (pageXY === false) { // has to be part of doc to have pageXY

                    YAHOO.log('setXY failed: element not available', 'error', 'Dom');

                    return false;

                }

                var delta = [ // assuming pixels; if not we will have to retry

                    parseInt( this.getStyle(el, 'left'), 10 ),

                    parseInt( this.getStyle(el, 'top'), 10 )

                ];

                if ( isNaN(delta[0]) ) {// in case of 'auto'

                    delta[0] = (style_pos == 'relative') ? 0 : el.offsetLeft;

                }

                if ( isNaN(delta[1]) ) { // in case of 'auto'

                    delta[1] = (style_pos == 'relative') ? 0 : el.offsetTop;

                }

                if (pos[0] !== null) { el.style.left = pos[0] - pageXY[0] + delta[0] + 'px'; }

                if (pos[1] !== null) { el.style.top = pos[1] - pageXY[1] + delta[1] + 'px'; }

                if (!noRetry) {

                    var newXY = this.getXY(el);

                    // if retry is true, try one more time if we miss

                   if ( (pos[0] !== null && newXY[0] != pos[0]) ||

                        (pos[1] !== null && newXY[1] != pos[1]) ) {

                       this.setXY(el, pos, true);

                   }

                }

                YAHOO.log('setXY setting position to ' + pos, 'info', 'Dom');

            };

            Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Set the X position of an html element in page coordinates, regardless of how the element is positioned.

         * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

         * @method setX

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.

         * @param {Int} x The value to use as the X coordinate for the element(s).

         */

        setX: function(el, x) {

            Y.Dom.setXY(el, [x, null]);

        },

        /**

         * Set the Y position of an html element in page coordinates, regardless of how the element is positioned.

         * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).

         * @method setY

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.

         * @param {Int} x To use as the Y coordinate for the element(s).

         */

        setY: function(el, y) {

            Y.Dom.setXY(el, [null, y]);

        },

        /**

         * Returns the region position of the given element.

         * The element must be part of the DOM tree to have a region (display:none or elements not appended return false).

         * @method getRegion

         * @param {String | HTMLElement | Array} el Accepts a string to use as an ID, an actual DOM reference, or an Array of IDs and/or HTMLElements.

         * @return {Region | Array} A Region or array of Region instances containing "top, left, bottom, right" member data.

         */

        getRegion: function(el) {

            var f = function(el) {

                if ( (el.parentNode === null || el.offsetParent === null ||

                        this.getStyle(el, 'display') == 'none') && el != document.body) {

                    YAHOO.log('getRegion failed: element not available', 'error', 'Dom');

                    return false;

                }

                var region = Y.Region.getRegion(el);

                YAHOO.log('getRegion returning ' + region, 'info', 'Dom');

                return region;

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Returns the width of the client (viewport).

         * @method getClientWidth

         * @deprecated Now using getViewportWidth.  This interface left intact for back compat.

         * @return {Int} The width of the viewable area of the page.

         */

        getClientWidth: function() {

            return Y.Dom.getViewportWidth();

        },

        /**

         * Returns the height of the client (viewport).

         * @method getClientHeight

         * @deprecated Now using getViewportHeight.  This interface left intact for back compat.

         * @return {Int} The height of the viewable area of the page.

         */

        getClientHeight: function() {

            return Y.Dom.getViewportHeight();

        },

        /**

         * Returns a array of HTMLElements with the given class.

         * For optimized performance, include a tag and/or root node when possible.

         * @method getElementsByClassName

         * @param {String} className The class name to match against

         * @param {String} tag (optional) The tag name of the elements being collected

         * @param {String | HTMLElement} root (optional) The HTMLElement or an ID to use as the starting point

         * @param {Function} apply (optional) A function to apply to each element when found

         * @return {Array} An array of elements that have the given class name

         */

        getElementsByClassName: function(className, tag, root, apply) {

            tag = tag || '*';

            root = (root) ? Y.Dom.get(root) : null || document;

            if (!root) {

                return [];

            }

            var nodes = [],

                elements = root.getElementsByTagName(tag),

                re = getClassRegEx(className);

            for (var i = 0, len = elements.length; i < len; ++i) {

                if ( re.test(elements[i].className) ) {

                    nodes[nodes.length] = elements[i];

                    if (apply) {

                        apply.call(elements[i], elements[i]);

                    }

                }

            }

            return nodes;

        },

        /**

         * Determines whether an HTMLElement has the given className.

         * @method hasClass

         * @param {String | HTMLElement | Array} el The element or collection to test

         * @param {String} className the class name to search for

         * @return {Boolean | Array} A boolean value or array of boolean values

         */

        hasClass: function(el, className) {

            var re = getClassRegEx(className);

            var f = function(el) {

                YAHOO.log('hasClass returning ' + re.test(el.className), 'info', 'Dom');

                return re.test(el.className);

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Adds a class name to a given element or collection of elements.

         * @method addClass

         * @param {String | HTMLElement | Array} el The element or collection to add the class to

         * @param {String} className the class name to add to the class attribute

         * @return {Boolean | Array} A pass/fail boolean or array of booleans

         */

        addClass: function(el, className) {

            var f = function(el) {

                if (this.hasClass(el, className)) {

                    return false; // already present

                }

                YAHOO.log('addClass adding ' + className, 'info', 'Dom');

                el.className = YAHOO.lang.trim([el.className, className].join(' '));

                return true;

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Removes a class name from a given element or collection of elements.

         * @method removeClass

         * @param {String | HTMLElement | Array} el The element or collection to remove the class from

         * @param {String} className the class name to remove from the class attribute

         * @return {Boolean | Array} A pass/fail boolean or array of booleans

         */

        removeClass: function(el, className) {

            var re = getClassRegEx(className);

            var f = function(el) {

                if (!this.hasClass(el, className)) {

                    return false; // not present

                }

                YAHOO.log('removeClass removing ' + className, 'info', 'Dom');

                var c = el.className;

                el.className = c.replace(re, ' ');

                if ( this.hasClass(el, className) ) { // in case of multiple adjacent

                    this.removeClass(el, className);

                }

                el.className = YAHOO.lang.trim(el.className); // remove any trailing spaces

                return true;

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Replace a class with another class for a given element or collection of elements.

         * If no oldClassName is present, the newClassName is simply added.

         * @method replaceClass

         * @param {String | HTMLElement | Array} el The element or collection to remove the class from

         * @param {String} oldClassName the class name to be replaced

         * @param {String} newClassName the class name that will be replacing the old class name

         * @return {Boolean | Array} A pass/fail boolean or array of booleans

         */

        replaceClass: function(el, oldClassName, newClassName) {

            if (!newClassName || oldClassName === newClassName) { // avoid infinite loop

                return false;

            }

            var re = getClassRegEx(oldClassName);

            var f = function(el) {

                YAHOO.log('replaceClass replacing ' + oldClassName + ' with ' + newClassName, 'info', 'Dom');

                if ( !this.hasClass(el, oldClassName) ) {

                    this.addClass(el, newClassName); // just add it if nothing to replace

                    return true; // NOTE: return

                }

                el.className = el.className.replace(re, ' ' + newClassName + ' ');

                if ( this.hasClass(el, oldClassName) ) { // in case of multiple adjacent

                    this.replaceClass(el, oldClassName, newClassName);

                }

                el.className = YAHOO.lang.trim(el.className); // remove any trailing spaces

                return true;

            };

            return Y.Dom.batch(el, f, Y.Dom, true);

        },

        /**

         * Returns an ID and applies it to the element "el", if provided.

         * @method generateId

         * @param {String | HTMLElement | Array} el (optional) An optional element array of elements to add an ID to (no ID is added if one is already present).

         * @param {String} prefix (optional) an optional prefix to use (defaults to "yui-gen").

         * @return {String | Array} The generated ID, or array of generated IDs (or original ID if already present on an element)

         */

        generateId: function(el, prefix) {

            prefix = prefix || 'yui-gen';

            var f = function(el) {

                if (el && el.id) { // do not override existing ID

                    YAHOO.log('generateId returning existing id ' + el.id, 'info', 'Dom');

                    return el.id;

                }

                var id = prefix + id_counter++;

                YAHOO.log('generateId generating ' + id, 'info', 'Dom');

                if (el) {

                    el.id = id;

                }

                return id;

            };

            // batch fails when no element, so just generate and return single ID

            return Y.Dom.batch(el, f, Y.Dom, true) || f.apply(Y.Dom, arguments);

        },

        /**

         * Determines whether an HTMLElement is an ancestor of another HTML element in the DOM hierarchy.

         * @method isAncestor

         * @param {String | HTMLElement} haystack The possible ancestor

         * @param {String | HTMLElement} needle The possible descendent

         * @return {Boolean} Whether or not the haystack is an ancestor of needle

         */

        isAncestor: function(haystack, needle) {

            haystack = Y.Dom.get(haystack);

            needle = Y.Dom.get(needle);

            if (!haystack || !needle) {

                return false;

            }

            if (haystack.contains && needle.nodeType && !isSafari) { // safari contains is broken

                YAHOO.log('isAncestor returning ' + haystack.contains(needle), 'info', 'Dom');

                return haystack.contains(needle);

            }

            else if ( haystack.compareDocumentPosition && needle.nodeType ) {

                YAHOO.log('isAncestor returning ' + !!(haystack.compareDocumentPosition(needle) & 16), 'info', 'Dom');

                return !!(haystack.compareDocumentPosition(needle) & 16);

            } else if (needle.nodeType) {

                // fallback to crawling up (safari)

                return !!this.getAncestorBy(needle, function(el) {

                    return el == haystack;

                });

            }

            YAHOO.log('isAncestor failed; most likely needle is not an HTMLElement', 'error', 'Dom');

            return false;

        },

        /**

         * Determines whether an HTMLElement is present in the current document.

         * @method inDocument

         * @param {String | HTMLElement} el The element to search for

         * @return {Boolean} Whether or not the element is present in the current document

         */

        inDocument: function(el) {

            return this.isAncestor(document.documentElement, el);

        },

        /**

         * Returns a array of HTMLElements that pass the test applied by supplied boolean method.

         * For optimized performance, include a tag and/or root node when possible.

         * @method getElementsBy

         * @param {Function} method - A boolean method for testing elements which receives the element as its only argument.

         * @param {String} tag (optional) The tag name of the elements being collected

         * @param {String | HTMLElement} root (optional) The HTMLElement or an ID to use as the starting point

         * @param {Function} apply (optional) A function to apply to each element when found

         * @return {Array} Array of HTMLElements

         */

        getElementsBy: function(method, tag, root, apply) {

            tag = tag || '*';

            root = (root) ? Y.Dom.get(root) : null || document;

            if (!root) {

                return [];

            }

            var nodes = [],

                elements = root.getElementsByTagName(tag);

            for (var i = 0, len = elements.length; i < len; ++i) {

                if ( method(elements[i]) ) {

                    nodes[nodes.length] = elements[i];

                    if (apply) {

                        apply(elements[i]);

                    }

                }

            }

            YAHOO.log('getElementsBy returning ' + nodes, 'info', 'Dom');

            return nodes;

        },

        /**

         * Runs the supplied method against each item in the Collection/Array.

         * The method is called with the element(s) as the first arg, and the optional param as the second ( method(el, o) ).

         * @method batch

         * @param {String | HTMLElement | Array} el (optional) An element or array of elements to apply the method to

         * @param {Function} method The method to apply to the element(s)

         * @param {Any} o (optional) An optional arg that is passed to the supplied method

         * @param {Boolean} override (optional) Whether or not to override the scope of "method" with "o"

         * @return {Any | Array} The return value(s) from the supplied method

         */

        batch: function(el, method, o, override) {

            el = (el && (el.tagName || el.item)) ? el : Y.Dom.get(el); // skip get() when possible

            if (!el || !method) {

                YAHOO.log('batch failed: invalid arguments', 'error', 'Dom');

                return false;

            }

            var scope = (override) ? o : window;

            if (el.tagName || el.length === undefined) { // element or not array-like

                return method.call(scope, el, o);

            }

            var collection = [];

            for (var i = 0, len = el.length; i < len; ++i) {

                collection[collection.length] = method.call(scope, el[i], o);

            }

            return collection;

        },

        /**

         * Returns the height of the document.

         * @method getDocumentHeight

         * @return {Int} The height of the actual document (which includes the body and its margin).

         */

        getDocumentHeight: function() {

            var scrollHeight = (document.compatMode != 'CSS1Compat') ? document.body.scrollHeight : document.documentElement.scrollHeight;

            var h = Math.max(scrollHeight, Y.Dom.getViewportHeight());

            YAHOO.log('getDocumentHeight returning ' + h, 'info', 'Dom');

            return h;

        },

        /**