# Yahoo! UI Library

### event 3.0.0

Yahoo! UI Library > event > event-dom.js (source view)
Search:
Filters Show Private Show Protected Show Deprecated

    (function() {
    /**
     * DOM event listener abstraction layer
     * @module event
     * @submodule event-base
     */

    /**
     * The event utility provides functions to add and remove event listeners,
     * event cleansing.  It also tries to automatically remove listeners it
     * registers during the unload event.
     *
     * @class Event
     * @static
     */

    Y.Env.evt.dom_wrappers = {};
    Y.Env.evt.dom_map = {};

    var _eventenv = Y.Env.evt,
    add = YUI.Env.add,
    remove = YUI.Env.remove,

    onLoad = function() {
        YUI.Env.windowLoaded = true;
        Y.Event._load();
        remove(window, "load", onLoad);
    },

    onUnload = function() {
        Y.Event._unload();
        remove(window, "unload", onUnload);
    },

    EVENT_READY = 'domready',

    COMPAT_ARG = '~yui|2|compat~',

    shouldIterate = function(o) {
        try {
            return (o && typeof o !== "string" && Y.Lang.isNumber(o.length) && !o.tagName && !o.alert);
        } catch(ex) {
            Y.log("collection check failure", "warn", "event");
            return false;
        }

    },

    Event = function() {

        /**
         * True after the onload event has fired
         * @property _loadComplete
         * @type boolean
         * @static
         * @private
         */
        var _loadComplete =  false,

        /**
         * The number of times to poll after window.onload.  This number is
         * increased if additional late-bound handlers are requested after
         * the page load.
         * @property _retryCount
         * @static
         * @private
         */
        _retryCount = 0,

        /**
         * onAvailable listeners
         * @property _avail
         * @static
         * @private
         */
        _avail = [],

        /**
         * Custom event wrappers for DOM events.  Key is
         * 'event:' + Element uid stamp + event type
         * @property _wrappers
         * @type Y.Event.Custom
         * @static
         * @private
         */
        _wrappers = _eventenv.dom_wrappers,

        _windowLoadKey = null,

        /**
         * Custom event wrapper map DOM events.  Key is
         * Element uid stamp.  Each item is a hash of custom event
         * wrappers as provided in the _wrappers collection.  This
         * provides the infrastructure for getListeners.
         * @property _el_events
         * @static
         * @private
         */
        _el_events = _eventenv.dom_map;

        return {

            /**
             * The number of times we should look for elements that are not
             * in the DOM at the time the event is requested after the document
             * has been loaded.  The default is 1000@amp;40 ms, so it will poll
             * for 40 seconds or until all outstanding handlers are bound
             * (whichever comes first).
             * @property POLL_RETRYS
             * @type int
             * @static
             * @final
             */
            POLL_RETRYS: 1000,

            /**
             * The poll interval in milliseconds
             * @property POLL_INTERVAL
             * @type int
             * @static
             * @final
             */
            POLL_INTERVAL: 40,

            /**
             * addListener/removeListener can throw errors in unexpected scenarios.
             * These errors are suppressed, the method returns false, and this property
             * is set
             * @property lastError
             * @static
             * @type Error
             */
            lastError: null,

            /**
             * poll handle
             * @property _interval
             * @static
             * @private
             */
            _interval: null,

            /**
             * document readystate poll handle
             * @property _dri
             * @static
             * @private
             */
             _dri: null,

            /**
             * True when the document is initially usable
             * @property DOMReady
             * @type boolean
             * @static
             */
            DOMReady: false,

            /**
             * @method startInterval
             * @static
             * @private
             */
            startInterval: function() {
                var E = Y.Event;

                if (!E._interval) {
    E._interval = setInterval(Y.bind(E._poll, E), E.POLL_INTERVAL);
                }
            },

            /**
             * Executes the supplied callback when the item with the supplied
             * id is found.  This is meant to be used to execute behavior as
             * soon as possible as the page loads.  If you use this after the
             * initial page load it will poll for a fixed time for the element.
             * The number of times it will poll and the frequency are
             * configurable.  By default it will poll for 10 seconds.
             *
             * <p>The callback is executed with a single parameter:
             * the custom object parameter, if provided.</p>
             *
             * @method onAvailable
             *
             * @param {string||string[]}   id the id of the element, or an array
             * of ids to look for.
             * @param {function} fn what to execute when the element is found.
             * @param {object}   p_obj an optional object to be passed back as
             *                   a parameter to fn.
             * @param {boolean|object}  p_override If set to true, fn will execute
             *                   in the context of p_obj, if set to an object it
             *                   will execute in the context of that object
             * @param checkContent {boolean} check child node readiness (onContentReady)
             * @static
             * @deprecated Use Y.on("available")
             */
            // @TODO fix arguments
            onAvailable: function(id, fn, p_obj, p_override, checkContent, compat) {

                var a = Y.Array(id), i, availHandle;

                // Y.log('onAvailable registered for: ' + id);

                for (i=0; i<a.length; i=i+1) {
                    _avail.push({
                        id:         a[i],
                        fn:         fn,
                        obj:        p_obj,
                        override:   p_override,
                        checkReady: checkContent,
                        compat:     compat
                    });
                }
                _retryCount = this.POLL_RETRYS;

                // We want the first test to be immediate, but async
                setTimeout(Y.bind(Y.Event._poll, Y.Event), 0);

                availHandle = new Y.EventHandle({

                    _delete: function() {
                        // set by the event system for lazy DOM listeners
                        if (availHandle.handle) {
                            availHandle.handle.detach();
    						return;
                        }

                        var i, j;

                        // otherwise try to remove the onAvailable listener(s)
                        for (i = 0; i < a.length; i++) {
                            for (j = 0; j < _avail.length; j++) {
                                if (a[i] === _avail[j].id) {
                                    _avail.splice(j, 1);
                                }
                            }
                        }
                    }

                });

                return availHandle;
            },

            /**
             * Works the same way as onAvailable, but additionally checks the
             * state of sibling elements to determine if the content of the
             * available element is safe to modify.
             *
             * <p>The callback is executed with a single parameter:
             * the custom object parameter, if provided.</p>
             *
             * @method onContentReady
             *
             * @param {string}   id the id of the element to look for.
             * @param {function} fn what to execute when the element is ready.
             * @param {object}   p_obj an optional object to be passed back as
             *                   a parameter to fn.
             * @param {boolean|object}  p_override If set to true, fn will execute
             *                   in the context of p_obj.  If an object, fn will
             *                   exectute in the context of that object
             *
             * @static
             * @deprecated Use Y.on("contentready")
             */
            // @TODO fix arguments
            onContentReady: function(id, fn, p_obj, p_override, compat) {
                return this.onAvailable(id, fn, p_obj, p_override, true, compat);
            },

            /**
             * Adds an event listener
             *
             * @method attach
             *
             * @param {String}   type     The type of event to append
             * @param {Function} fn        The method the event invokes
             * @param {String|HTMLElement|Array|NodeList} el An id, an element
             *  reference, or a collection of ids and/or elements to assign the
             *  listener to.
             * @param {Object}   context optional context object
             * @param {Boolean|object}  args 0..n arguments to pass to the callback
             * @return {EventHandle} an object to that can be used to detach the listener
             *
             * @static
             */

            attach: function(type, fn, el, context) {
                return Y.Event._attach(Y.Array(arguments, 0, true));
            },

    		_createWrapper: function (el, type, capture, compat, facade) {

                var ek = Y.stamp(el),
    	            key = 'event:' + ek + type,
    	            cewrapper;

                if (false === facade) {
                    key += 'native';
                }
                if (capture) {
                    key += 'capture';
                }

                cewrapper = _wrappers[key];

                if (!cewrapper) {
                    // create CE wrapper
                    cewrapper = Y.publish(key, {
                        silent: true,
                        bubbles: false,
                        contextFn: function() {
                            cewrapper.nodeRef = cewrapper.nodeRef || Y.one(cewrapper.el);
                            return cewrapper.nodeRef;
                        }
                    });

                    // for later removeListener calls
                    cewrapper.el = el;
                    cewrapper.key = key;
                    cewrapper.domkey = ek;
                    cewrapper.type = type;
                    cewrapper.fn = function(e) {
                        cewrapper.fire(Y.Event.getEvent(e, el, (compat || (false === facade))));
                    };
    				cewrapper.capture = capture;

                    if (el == Y.config.win && type == "load") {
                        // window load happens once
                        cewrapper.fireOnce = true;
                        _windowLoadKey = key;
                    }

                    _wrappers[key] = cewrapper;
                    _el_events[ek] = _el_events[ek] || {};
                    _el_events[ek][key] = cewrapper;

                    add(el, type, cewrapper.fn, capture);
                }

    			return cewrapper;

    		},

            _attach: function(args, config) {

                var compat, E=Y.Event,
                    handles, oEl, cewrapper, context,
                    fireNow = false, ret,
                    type = args[0],
                    fn = args[1],
                    el = args[2] || Y.config.win,
                    facade = config && config.facade,
                    capture = config && config.capture;

                if (args[args.length-1] === COMPAT_ARG) {
                    compat = true;
                    // trimmedArgs.pop();
                }

                if (!fn || !fn.call) {
    // throw new TypeError(type + " attach call failed, callback undefined");
    Y.log(type + " attach call failed, invalid callback", "error", "event");
                    return false;
                }

                // The el argument can be an array of elements or element ids.
                if (shouldIterate(el)) {

                    handles=[];

                    Y.each(el, function(v, k) {
                        args[2] = v;
                        handles.push(E._attach(args, config));
                    });

                    // return (handles.length === 1) ? handles[0] : handles;
                    return new Y.EventHandle(handles);

                // If the el argument is a string, we assume it is
                // actually the id of the element.  If the page is loaded
                // we convert el to the actual element, otherwise we
                // defer attaching the event until the element is
                // ready
                } else if (Y.Lang.isString(el)) {

                    // oEl = (compat) ? Y.DOM.byId(el) : Y.Selector.query(el);

                    if (compat) {
                        oEl = Y.DOM.byId(el);
                    } else {

                        oEl = Y.Selector.query(el);

                        switch (oEl.length) {
                            case 0:
                                oEl = null;
                                break;
                            case 1:
                                oEl = oEl[0];
                                break;
                            default:
                                args[2] = oEl;
                                return E._attach(args, config);
                        }
                    }

                    if (oEl) {

                        el = oEl;

                    // Not found = defer adding the event until the element is available
                    } else {

                        // Y.log(el + ' not found');
                        ret = this.onAvailable(el, function() {
                            // Y.log('lazy attach: ' + args);

                            ret.handle = E._attach(args, config);

                        }, E, true, false, compat);

                        return ret;

                    }
                }

                // Element should be an html element or node
                if (!el) {
                    Y.log("unable to attach event " + type, "warn", "event");
                    return false;
                }

                if (Y.Node && el instanceof Y.Node) {
                    el = Y.Node.getDOMNode(el);
                }

     			cewrapper = this._createWrapper(el, type, capture, compat, facade);

                if (el == Y.config.win && type == "load") {

                    // if the load is complete, fire immediately.
                    // all subscribers, including the current one
                    // will be notified.
                    if (YUI.Env.windowLoaded) {
                        fireNow = true;
                    }
                }

                if (compat) {
                    args.pop();
                }

                context = args[3];

                // set context to the Node if not specified
                // ret = cewrapper.on.apply(cewrapper, trimmedArgs);
                ret = cewrapper._on(fn, context, (args.length > 4) ? args.slice(4) : null);

                if (fireNow) {
                    cewrapper.fire();
                }

                return ret;

            },

            /**
             * Removes an event listener.  Supports the signature the event was bound
             * with, but the preferred way to remove listeners is using the handle
             * that is returned when using Y.on
             *
             * @method detach
             *
             * @param {String} type the type of event to remove.
             * @param {Function} fn the method the event invokes.  If fn is
             * undefined, then all event handlers for the type of event are
             * removed.
             * @param {String|HTMLElement|Array|NodeList|EventHandle} el An
             * event handle, an id, an element reference, or a collection
             * of ids and/or elements to remove the listener from.
             * @return {boolean} true if the unbind was successful, false otherwise.
             * @static
             */
            detach: function(type, fn, el, obj) {

                var args=Y.Array(arguments, 0, true), compat, i, l, ok,
                    id, ce;

                if (args[args.length-1] === COMPAT_ARG) {
                    compat = true;
                    // args.pop();
                }

                if (type && type.detach) {
                    return type.detach();
                }

                // The el argument can be a string
                if (typeof el == "string") {

                    // el = (compat) ? Y.DOM.byId(el) : Y.all(el);
                    if (compat) {
                        el = Y.DOM.byId(el);
                    } else {
                        el = Y.Selector.query(el);
                        l = el.length;
                        if (l < 1) {
                            el = null;
                        } else if (l == 1) {
                            el = el[0];
                        }
                    }
                    // return Y.Event.detach.apply(Y.Event, args);

                // The el argument can be an array of elements or element ids.
                }

                if (!el) {
                    return false;
                }

                if (shouldIterate(el)) {

                    ok = true;
                    for (i=0, l=el.length; i<l; ++i) {
                        args[2] = el[i];
                        ok = ( Y.Event.detach.apply(Y.Event, args) && ok );
                    }

                    return ok;

                }

                if (!type || !fn || !fn.call) {
                    return this.purgeElement(el, false, type);
                }

                id = 'event:' + Y.stamp(el) + type;
                ce = _wrappers[id];

                if (ce) {
                    return ce.detach(fn);
                } else {
                    return false;
                }

            },

            /**
             * Finds the event in the window object, the caller's arguments, or
             * in the arguments of another method in the callstack.  This is
             * executed automatically for events registered through the event
             * manager, so the implementer should not normally need to execute
             * this function at all.
             * @method getEvent
             * @param {Event} e the event parameter from the handler
             * @param {HTMLElement} el the element the listener was attached to
             * @return {Event} the event
             * @static
             */
            getEvent: function(e, el, noFacade) {
                var ev = e || window.event;

                return (noFacade) ? ev :
                    new Y.DOMEventFacade(ev, el, _wrappers['event:' + Y.stamp(el) + e.type]);
            },

            /**
             * Generates an unique ID for the element if it does not already
             * have one.
             * @method generateId
             * @param el the element to create the id for
             * @return {string} the resulting id of the element
             * @static
             */
            generateId: function(el) {
                var id = el.id;

                if (!id) {
                    id = Y.stamp(el);
                    el.id = id;
                }

                return id;
            },

            /**
             * We want to be able to use getElementsByTagName as a collection
             * to attach a group of events to.  Unfortunately, different
             * browsers return different types of collections.  This function
             * tests to determine if the object is array-like.  It will also
             * fail if the object is an array, but is empty.
             * @method _isValidCollection
             * @param o the object to test
             * @return {boolean} true if the object is array-like and populated
             * @deprecated was not meant to be used directly
             * @static
             * @private
             */
            _isValidCollection: shouldIterate,

            /**
             * hook up any deferred listeners
             * @method _load
             * @static
             * @private
             */
            _load: function(e) {

                if (!_loadComplete) {

                    // Y.log('Load Complete', 'info', 'event');

                    _loadComplete = true;

                    // Just in case DOMReady did not go off for some reason
                    // E._ready();
                    if (Y.fire) {
                        Y.fire(EVENT_READY);
                    }

                    // Available elements may not have been detected before the
                    // window load event fires. Try to find them now so that the
                    // the user is more likely to get the onAvailable notifications
                    // before the window load notification
                    Y.Event._poll();

                }
            },

            /**
             * Polling function that runs before the onload event fires,
             * attempting to attach to DOM Nodes as soon as they are
             * available
             * @method _poll
             * @static
             * @private
             */
            _poll: function() {

                if (this.locked) {
                    return;
                }

                if (Y.UA.ie && !YUI.Env.DOMReady) {
                    // Hold off if DOMReady has not fired and check current
                    // readyState to protect against the IE operation aborted
                    // issue.
                    this.startInterval();
                    return;
                }

                this.locked = true;

                // Y.log.debug("poll");

                // keep trying until after the page is loaded.  We need to
                // check the page load state prior to trying to bind the
                // elements so that we can be certain all elements have been
                // tested appropriately
                var tryAgain = !_loadComplete, notAvail, executeItem,
                    i, len, item, el;

                if (!tryAgain) {
                    tryAgain = (_retryCount > 0);
                }

                // onAvailable
                notAvail = [];

                executeItem = function (el, item) {

                    var context, ov = item.override;

                    if (item.compat) {

                        if (item.override) {
                            if (ov === true) {
                                context = item.obj;
                            } else {
                                context = ov;
                            }
                        } else {
                            context = el;
                        }

                        item.fn.call(context, item.obj);

                    } else {
                        context = item.obj || Y.one(el);
                        item.fn.apply(context, (Y.Lang.isArray(ov)) ? ov : []);
                    }

                };

                // onAvailable
                for (i=0,len=_avail.length; i<len; ++i) {
                    item = _avail[i];
                    if (item && !item.checkReady) {

                        // el = (item.compat) ? Y.DOM.byId(item.id) : Y.one(item.id);
                        el = (item.compat) ? Y.DOM.byId(item.id) : Y.Selector.query(item.id, null, true);

                        if (el) {
                            // Y.log('avail: ' + el);
                            executeItem(el, item);
                            _avail[i] = null;
                        } else {
                            // Y.log('NOT avail: ' + el);
                            notAvail.push(item);
                        }
                    }
                }

                // onContentReady
                for (i=0,len=_avail.length; i<len; ++i) {
                    item = _avail[i];
                    if (item && item.checkReady) {

                        // el = (item.compat) ? Y.DOM.byId(item.id) : Y.one(item.id);
                        el = (item.compat) ? Y.DOM.byId(item.id) : Y.Selector.query(item.id, null, true);

                        if (el) {
                            // The element is available, but not necessarily ready
                            // @todo should we test parentNode.nextSibling?
                            if (_loadComplete || (el.get && el.get('nextSibling')) || el.nextSibling) {
                                executeItem(el, item);
                                _avail[i] = null;
                            }
                        } else {
                            notAvail.push(item);
                        }
                    }
                }

                _retryCount = (notAvail.length === 0) ? 0 : _retryCount - 1;

                if (tryAgain) {
                    // we may need to strip the nulled out items here
                    this.startInterval();
                } else {
                    clearInterval(this._interval);
                    this._interval = null;
                }

                this.locked = false;

                return;

            },

            /**
             * Removes all listeners attached to the given element via addListener.
             * Optionally, the node's children can also be purged.
             * Optionally, you can specify a specific type of event to remove.
             * @method purgeElement
             * @param {HTMLElement} el the element to purge
             * @param {boolean} recurse recursively purge this element's children
             * as well.  Use with caution.
             * @param {string} type optional type of listener to purge. If
             * left out, all listeners will be removed
             * @static
             */
            purgeElement: function(el, recurse, type) {
                // var oEl = (Y.Lang.isString(el)) ? Y.one(el) : el,
                var oEl = (Y.Lang.isString(el)) ?  Y.Selector.query(el, null, true) : el,
                    lis = this.getListeners(oEl, type), i, len, props;
                if (lis) {
                    for (i=0,len=lis.length; i<len ; ++i) {
                        props = lis[i];
                        props.detachAll();
                        remove(props.el, props.type, props.fn, props.capture);
                        delete _wrappers[props.key];
                        delete _el_events[props.domkey][props.key];
                    }

                }

                if (recurse && oEl && oEl.childNodes) {
                    for (i=0,len=oEl.childNodes.length; i<len ; ++i) {
                        this.purgeElement(oEl.childNodes[i], recurse, type);
                    }
                }

            },

            /**
             * Returns all listeners attached to the given element via addListener.
             * Optionally, you can specify a specific type of event to return.
             * @method getListeners
             * @param el {HTMLElement|string} the element or element id to inspect
             * @param type {string} optional type of listener to return. If
             * left out, all listeners will be returned
             * @return {Y.Custom.Event} the custom event wrapper for the DOM event(s)
             * @static
             */
            getListeners: function(el, type) {
                var ek = Y.stamp(el, true), evts = _el_events[ek],
                    results=[] , key = (type) ? 'event:' + ek + type : null;

                if (!evts) {
                    return null;
                }

                if (key) {
                    if (evts[key]) {
                        results.push(evts[key]);
                    }

                    // get native events as well
                    key += 'native';
                    if (evts[key]) {
                        results.push(evts[key]);
                    }

                } else {
                    Y.each(evts, function(v, k) {
                        results.push(v);
                    });
                }

                return (results.length) ? results : null;
            },

            /**
             * Removes all listeners registered by pe.event.  Called
             * automatically during the unload event.
             * @method _unload
             * @static
             * @private
             */
            _unload: function(e) {
                Y.each(_wrappers, function(v, k) {
                    v.detachAll();
                    remove(v.el, v.type, v.fn, v.capture);
                    delete _wrappers[k];
                    delete _el_events[v.domkey][k];
                });
            },

            /**
             * Adds a DOM event directly without the caching, cleanup, context adj, etc
             *
             * @method nativeAdd
             * @param {HTMLElement} el      the element to bind the handler to
             * @param {string}      type   the type of event handler
             * @param {function}    fn      the callback to invoke
             * @param {boolen}      capture capture or bubble phase
             * @static
             * @private
             */
            nativeAdd: add,

            /**
             * Basic remove listener
             *
             * @method nativeRemove
             * @param {HTMLElement} el      the element to bind the handler to
             * @param {string}      type   the type of event handler
             * @param {function}    fn      the callback to invoke
             * @param {boolen}      capture capture or bubble phase
             * @static
             * @private
             */
            nativeRemove: remove
        };

    }();

    Y.Event = Event;

    if (Y.config.injected || YUI.Env.windowLoaded) {
        onLoad();
    } else {
        add(window, "load", onLoad);
    }

    // Process onAvailable/onContentReady items when when the DOM is ready in IE
    if (Y.UA.ie) {
        Y.on(EVENT_READY, Event._poll, Event, true);
    }

    Y.on("unload", onUnload);

    Event.Custom = Y.CustomEvent;
    Event.Subscriber = Y.Subscriber;
    Event.Target = Y.EventTarget;
    Event.Handle = Y.EventHandle;
    Event.Facade = Y.EventFacade;

    Event._poll();

    })();

Copyright © 2009 Yahoo! Inc. All rights reserved.