# Yahoo! UI Library

### event-custom 3.0.0

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

    /**
     * Custom event engine, DOM event listener abstraction layer, synthetic DOM
     * events.
     * @module event-custom
     * @submodule event-custom-base
     */
    (function() {

    /**
     * EventTarget provides the implementation for any object to
     * publish, subscribe and fire to custom events, and also
     * alows other EventTargets to target the object with events
     * sourced from the other object.
     * EventTarget is designed to be used with Y.augment to wrap
     * EventCustom in an interface that allows events to be listened to
     * and fired by name.  This makes it possible for implementing code to
     * subscribe to an event that either has not been created yet, or will
     * not be created at all.
     * @class EventTarget
     * @param opts a configuration object
     * @config emitFacade {boolean} if true, all events will emit event
     * facade payloads by default (default false)
     * @config prefix {string} the prefix to apply to non-prefixed event names
     * @config chain {boolean} if true, on/after/detach return the host to allow
     * chaining, otherwise they return an EventHandle (default false)
     */

    var L = Y.Lang,
        PREFIX_DELIMITER = ':',
        CATEGORY_DELIMITER = '|',
        AFTER_PREFIX = '~AFTER~',

        /**
         * If the instance has a prefix attribute and the
         * event type is not prefixed, the instance prefix is
         * applied to the supplied type.
         * @method _getType
         * @private
         */
        _getType = Y.cached(function(type, pre) {

            if (!pre || !L.isString(type) || type.indexOf(PREFIX_DELIMITER) > -1) {
                return type;
            }

            return pre + PREFIX_DELIMITER + type;
        }),

        /**
         * Returns an array with the detach key (if provided),
         * and the prefixed event name from _getType
         * Y.on('detachcategory, menu:click', fn)
         * @method _parseType
         * @private
         */
        _parseType = Y.cached(function(type, pre) {

            var t = type, detachcategory, after, i;

            if (!L.isString(t)) {
                return t;
            }

            i = t.indexOf(AFTER_PREFIX);

            if (i > -1) {
                after = true;
                t = t.substr(AFTER_PREFIX.length);
                // Y.log(t);
            }

            i = t.indexOf(CATEGORY_DELIMITER);

            if (i > -1) {
                detachcategory = t.substr(0, (i));
                t = t.substr(i+1);
                if (t == '*') {
                    t = null;
                }
            }

            // detach category, full type with instance prefix, is this an after listener, short type
            return [detachcategory, (pre) ? _getType(t, pre) : t, after, t];
        }),

        ET = function(opts) {

            // Y.log('EventTarget constructor executed: ' + this._yuid);

            var o = (L.isObject(opts)) ? opts : {};

            this._yuievt = this._yuievt || {

                id: Y.guid(),

                events: {},

                targets: {},

                config: o,

                chain: ('chain' in o) ? o.chain : Y.config.chain,

                defaults: {
                    context: o.context || this,
                    host: this,
                    emitFacade: o.emitFacade,
                    fireOnce: o.fireOnce,
                    queuable: o.queuable,
                    broadcast: o.broadcast,
                    bubbles: ('bubbles' in o) ? o.bubbles : true
                }
            };

        };

    ET.prototype = {

        /**
         * Subscribe to a custom event hosted by this object
         * @method on
         * @param type    {string}   The type of the event
         * @param fn {Function} The callback
         * @return the event target or a detach handle per 'chain' config
         */
        on: function(type, fn, context, x) {

            var parts = _parseType(type, this._yuievt.config.prefix), f, c, args, ret, ce,
                detachcategory, handle, store = Y.Env.evt.handles, after, adapt, shorttype,
                Node = Y.Node, n, domevent;

            if (L.isObject(type)) {

                if (L.isFunction(type)) {
                    return Y.Do.before.apply(Y.Do, arguments);
                }

                f = fn;
                c = context;
                args = Y.Array(arguments, 0, true);
                ret = {};
                after = type._after;
                delete type._after;

                Y.each(type, function(v, k) {

                    if (v) {
                        f = v.fn || ((Y.Lang.isFunction(v)) ? v : f);
                        c = v.context || c;
                    }

                    args[0] = (after) ? AFTER_PREFIX + k : k;
                    args[1] = f;
                    args[2] = c;

                    ret[k] = this.on.apply(this, args);

                }, this);

                return (this._yuievt.chain) ? this : new Y.EventHandle(ret);

            }

            detachcategory = parts[0];
            after = parts[2];
            shorttype = parts[3];

            // extra redirection so we catch adaptor events too.  take a look at this.
            if (Node && (this instanceof Node) && (shorttype in Node.DOM_EVENTS)) {
                args = Y.Array(arguments, 0, true);
                args.splice(2, 0, Node.getDOMNode(this));
                // Y.log("Node detected, redirecting with these args: " + args);
                return Y.on.apply(Y, args);
            }

            type = parts[1];

            if (this instanceof YUI) {

                adapt = Y.Env.evt.plugins[type];
                args  = Y.Array(arguments, 0, true);
                args[0] = shorttype;

                if (Node) {
                    n = args[2];

                    if (n instanceof Y.NodeList) {
                        n = Y.NodeList.getDOMNodes(n);
                    } else if (n instanceof Node) {
                        n = Node.getDOMNode(n);
                    }

                    domevent = (shorttype in Node.DOM_EVENTS);

                    // Captures both DOM events and event plugins.
                    if (domevent) {
                        args[2] = n;
                    }
                }

                // check for the existance of an event adaptor
                if (adapt) {
                    Y.log('Using adaptor for ' + shorttype + ', ' + n, 'info', 'event');
                    handle = adapt.on.apply(Y, args);
                } else if ((!type) || domevent) {
                    handle = Y.Event._attach(args);
                }

            }

            if (!handle) {
                ce = this._yuievt.events[type] || this.publish(type);
                handle = ce._on(fn, context, (arguments.length > 3) ? Y.Array(arguments, 3, true) : null, (after) ? 'after' : true);
            }

            if (detachcategory) {
                store[detachcategory] = store[detachcategory] || {};
                store[detachcategory][type] = store[detachcategory][type] || [];
                store[detachcategory][type].push(handle);
            }

            return (this._yuievt.chain) ? this : handle;

        },

        /**
         * subscribe to an event
         * @method subscribe
         * @deprecated use on
         */
        subscribe: function() {
            Y.log('EventTarget subscribe() is deprecated, use on()', 'warn', 'deprecated');
            return this.on.apply(this, arguments);
        },

        /**
         * Detach one or more listeners the from the specified event
         * @method detach
         * @param type {string|Object}   Either the handle to the subscriber or the
         *                        type of event.  If the type
         *                        is not specified, it will attempt to remove
         *                        the listener from all hosted events.
         * @param fn   {Function} The subscribed function to unsubscribe, if not
         *                          supplied, all subscribers will be removed.
         * @param context  {Object}   The custom object passed to subscribe.  This is
         *                        optional, but if supplied will be used to
         *                        disambiguate multiple listeners that are the same
         *                        (e.g., you subscribe many object using a function
         *                        that lives on the prototype)
         * @return {EventTarget} the host
         */
        detach: function(type, fn, context) {
            var evts = this._yuievt.events, i, ret,
                Node = Y.Node, isNode = (this instanceof Node);

            // detachAll disabled on the Y instance.
            if (!type && (this !== Y)) {
                for (i in evts) {
                    if (evts.hasOwnProperty(i)) {
                        ret = evts[i].detach(fn, context);
                    }
                }
                if (isNode) {

                    Y.Event.purgeElement(Node.getDOMNode(this));
                }

                return ret;
            }

            var parts = _parseType(type, this._yuievt.config.prefix),
            detachcategory = L.isArray(parts) ? parts[0] : null,
            shorttype = (parts) ? parts[3] : null,
            handle, adapt, store = Y.Env.evt.handles, cat, args,
            ce,

            keyDetacher = function(lcat, ltype) {
                var handles = lcat[ltype];
                if (handles) {
                    while (handles.length) {
                        handle = handles.pop();
                        handle.detach();
                    }
                }
            };

            if (detachcategory) {

                cat = store[detachcategory];
                type = parts[1];

                if (cat) {
                    if (type) {
                        keyDetacher(cat, type);
                    } else {
                        for (i in cat) {
                            if (cat.hasOwnProperty(i)) {
                                keyDetacher(cat, i);
                            }
                        }
                    }

                    return (this._yuievt.chain) ? this : true;
                }

            // If this is an event handle, use it to detach
            } else if (L.isObject(type) && type.detach) {
                ret = type.detach();
                return (this._yuievt.chain) ? this : ret;
            // extra redirection so we catch adaptor events too.  take a look at this.
            } else if (isNode && ((!shorttype) || (shorttype in Node.DOM_EVENTS))) {
                args = Y.Array(arguments, 0, true);
                args[2] = Node.getDOMNode(this);
                return Y.detach.apply(Y, args);
            }

            adapt = Y.Env.evt.plugins[shorttype];

            // The YUI instance handles DOM events and adaptors
            if (this instanceof YUI) {
                args = Y.Array(arguments, 0, true);
                // use the adaptor specific detach code if
                if (adapt && adapt.detach) {
                    return adapt.detach.apply(Y, args);
                // DOM event fork
                } else if (!type || (!adapt && Node && (type in Node.DOM_EVENTS))) {
                    args[0] = type;
                    return Y.Event.detach.apply(Y.Event, args);
                }
            }

            ce = evts[type];
            if (ce) {
                ret = ce.detach(fn, context);
            }

            return (this._yuievt.chain) ? this : ret;
        },

        /**
         * detach a listener
         * @method unsubscribe
         * @deprecated use detach
         */
        unsubscribe: function() {
            return this.detach.apply(this, arguments);
        },

        /**
         * Removes all listeners from the specified event.  If the event type
         * is not specified, all listeners from all hosted custom events will
         * be removed.
         * @method detachAll
         * @param type {string}   The type, or name of the event
         */
        detachAll: function(type) {
            return this.detach(type);
        },

        /**
         * Removes all listeners from the specified event.  If the event type
         * is not specified, all listeners from all hosted custom events will
         * be removed.
         * @method unsubscribeAll
         * @param type {string}   The type, or name of the event
         * @deprecated use detachAll
         */
        unsubscribeAll: function() {
            return this.detachAll.apply(this, arguments);
        },

        /**
         * Creates a new custom event of the specified type.  If a custom event
         * by that name already exists, it will not be re-created.  In either
         * case the custom event is returned.
         *
         * @method publish
         *
         * @param type {string} the type, or name of the event
         * @param opts {object} optional config params.  Valid properties are:
         *
         *  <ul>
         *    <li>
         *   'broadcast': whether or not the YUI instance and YUI global are notified when the event is fired (false)
         *    </li>
         *    <li>
         *   'bubbles': whether or not this event bubbles (true)
         *    </li>
         *    <li>
         *   'context': the default execution context for the listeners (this)
         *    </li>
         *    <li>
         *   'defaultFn': the default function to execute when this event fires if preventDefault was not called
         *    </li>
         *    <li>
         *   'emitFacade': whether or not this event emits a facade (false)
         *    </li>
         *    <li>
         *   'prefix': the prefix for this targets events, e.g., 'menu' in 'menu:click'
         *    </li>
         *    <li>
         *   'fireOnce': if an event is configured to fire once, new subscribers after
         *   the fire will be notified immediately.
         *    </li>
         *    <li>
         *   'preventable': whether or not preventDefault() has an effect (true)
         *    </li>
         *    <li>
         *   'preventedFn': a function that is executed when preventDefault is called
         *    </li>
         *    <li>
         *   'queuable': whether or not this event can be queued during bubbling (false)
         *    </li>
         *    <li>
         *   'silent': if silent is true, debug messages are not provided for this event.
         *    </li>
         *    <li>
         *   'stoppedFn': a function that is executed when stopPropagation is called
         *    </li>
         *    <li>
         *   'type': the event type (valid option if not provided as the first parameter to publish)
         *    </li>
         *  </ul>
         *
         *  @return {Event.Custom} the custom event
         *
         */
        publish: function(type, opts) {
            var events, ce, ret, pre = this._yuievt.config.prefix;

            type = (pre) ? _getType(type, pre) : type;

            if (L.isObject(type)) {
                ret = {};
                Y.each(type, function(v, k) {
                    ret[k] = this.publish(k, v || opts);
                }, this);

                return ret;
            }

            events = this._yuievt.events;
            ce = events[type];

            if (ce) {
    // ce.log("publish applying new config to published event: '"+type+"' exists", 'info', 'event');
                if (opts) {
                    ce.applyConfig(opts, true);
                }
            } else {
                // apply defaults
                ce = new Y.CustomEvent(type, (opts) ? Y.mix(opts, this._yuievt.defaults) : this._yuievt.defaults);
                events[type] = ce;
            }

            // make sure we turn the broadcast flag off if this
            // event was published as a result of bubbling
            // if (opts instanceof Y.CustomEvent) {
              //   events[type].broadcast = false;
            // }

            return events[type];
        },

        /**
         * Registers another EventTarget as a bubble target.  Bubble order
         * is determined by the order registered.  Multiple targets can
         * be specified.
         * @method addTarget
         * @param o {EventTarget} the target to add
         */
        addTarget: function(o) {
            this._yuievt.targets[Y.stamp(o)] = o;
            this._yuievt.hasTargets = true;
        },

        /**
         * Removes a bubble target
         * @method removeTarget
         * @param o {EventTarget} the target to remove
         */
        removeTarget: function(o) {
            delete this._yuievt.targets[Y.stamp(o)];
        },

       /**
         * Fire a custom event by name.  The callback functions will be executed
         * from the context specified when the event was created, and with the
         * following parameters.
         *
         * If the custom event object hasn't been created, then the event hasn't
         * been published and it has no subscribers.  For performance sake, we
         * immediate exit in this case.  This means the event won't bubble, so
         * if the intention is that a bubble target be notified, the event must
         * be published on this object first.
         *
         * The first argument is the event type, and any additional arguments are
         * passed to the listeners as parameters.  If the first of these is an
         * object literal, and the event is configured to emit an event facade,
         * that object is mixed into the event facade and the facade is provided
         * in place of the original object.
         *
         * @method fire
         * @param type {String|Object} The type of the event, or an object that contains
         * a 'type' property.
         * @param arguments {Object*} an arbitrary set of parameters to pass to
         * the handler.  If the first of these is an object literal and the event is
         * configured to emit an event facade, the event facade will replace that
         * parameter after the properties the object literal contains are copied to
         * the event facade.
         * @return {Event.Target} the event host
         *
         */
        fire: function(type) {

            var typeIncluded = L.isString(type),
                t = (typeIncluded) ? type : (type && type.type),
                ce, a, ret, pre=this._yuievt.config.prefix;

            t = (pre) ? _getType(t, pre) : t;
            ce = this.getEvent(t, true);

            // this event has not been published or subscribed to
            if (!ce) {

                if (this._yuievt.hasTargets) {
                    a = (typeIncluded) ? arguments : Y.Array(arguments, 0, true).unshift(t);
                    return this.bubble(null, a, this);
                }

                // otherwise there is nothing to be done
                ret = true;

            } else {

                a = Y.Array(arguments, (typeIncluded) ? 1 : 0, true);
                ret = ce.fire.apply(ce, a);

                // clear target for next fire()
                ce.target = null;
            }

            return (this._yuievt.chain) ? this : ret;
        },

        /**
         * Returns the custom event of the provided type has been created, a
         * falsy value otherwise
         * @method getEvent
         * @param type {string} the type, or name of the event
         * @param prefixed {string} if true, the type is prefixed already
         * @return {Event.Custom} the custom event or null
         */
        getEvent: function(type, prefixed) {
            var pre, e;
            if (!prefixed) {
                pre = this._yuievt.config.prefix;
                type = (pre) ? _getType(type, pre) : type;
            }
            e = this._yuievt.events;
            return (e && type in e) ? e[type] : null;
        },

        /**
         * Subscribe to a custom event hosted by this object.  The
         * supplied callback will execute after any listeners add
         * via the subscribe method, and after the default function,
         * if configured for the event, has executed.
         * @method after
         * @param type    {string}   The type of the event
         * @param fn {Function} The callback
         * @return the event target or a detach handle per 'chain' config
         */
        after: function(type, fn) {

            var a = Y.Array(arguments, 0, true);

            switch (L.type(type)) {
                case 'function':
                    return Y.Do.after.apply(Y.Do, arguments);
                case 'object':
                    a[0]._after = true;
                    break;
                default:
                    a[0] = AFTER_PREFIX + type;
            }

            return this.on.apply(this, a);

        },

        /**
         * Executes the callback before a DOM event, custom event
         * or method.  If the first argument is a function, it
         * is assumed the target is a method.  For DOM and custom
         * events, this is an alias for Y.on.
         *
         * For DOM and custom events:
         * type, callback, context, 0-n arguments
         *
         * For methods:
         * callback, object (method host), methodName, context, 0-n arguments
         *
         * @method before
         * @return detach handle
         * @deprecated use the on method
         */
        before: function() {
            return this.on.apply(this, arguments);
        }

    };

    Y.EventTarget = ET;

    // make Y an event target
    Y.mix(Y, ET.prototype, false, false, {
        bubbles: false
    });

    ET.call(Y);

    YUI.Env.globalEvents = YUI.Env.globalEvents || new ET();

    /**
     * Hosts YUI page level events.  This is where events bubble to
     * when the broadcast config is set to 2.  This property is
     * only available if the custom event module is loaded.
     * @property Global
     * @type EventTarget
     * @for YUI
     */
    Y.Global = YUI.Env.globalEvents;

    // @TODO implement a global namespace function on Y.Global?

    })();

    /**
     * <code>YUI</code>'s <code>on</code> method is a unified interface for subscribing to
     * most events exposed by YUI.  This includes custom events, DOM events, and
     * function events.  <code>detach</code> is also provided to remove listeners
     * serviced by this function.
     *
     * The signature that <code>on</code> accepts varies depending on the type
     * of event being consumed.  Refer to the specific methods that will
     * service a specific request for additional information about subscribing
     * to that type of event.
     *
     * <ul>
     * <li>Custom events.  These events are defined by various
     * modules in the library.  This type of event is delegated to
     * <code>EventTarget</code>'s <code>on</code> method.
     *   <ul>
     *     <li>The type of the event</li>
     *     <li>The callback to execute</li>
     *     <li>An optional context object</li>
     *     <li>0..n additional arguments to supply the callback.</li>
     *   </ul>
     *   Example:
     *   <code>Y.on('domready', function() { // start work });</code>
     * </li>
     * <li>DOM events.  These are moments reported by the browser related
     * to browser functionality and user interaction.
     * This type of event is delegated to <code>Event</code>'s
     * <code>attach</code> method.
     *   <ul>
     *     <li>The type of the event</li>
     *     <li>The callback to execute</li>
     *     <li>The specification for the Node(s) to attach the listener
     *     to.  This can be a selector, collections, or Node/Element
     *     refereces.</li>
     *     <li>An optional context object</li>
     *     <li>0..n additional arguments to supply the callback.</li>
     *   </ul>
     *   Example:
     *   <code>Y.on('click', function(e) { // something was clicked }, '#someelement');</code>
     * </li>
     * <li>Function events.  These events can be used to react before or after a
     * function is executed.  This type of event is delegated to <code>Event.Do</code>'s
     * <code>before</code> method.
     *   <ul>
     *     <li>The callback to execute</li>
     *     <li>The object that has the function that will be listened for.</li>
     *     <li>The name of the function to listen for.</li>
     *     <li>An optional context object</li>
     *     <li>0..n additional arguments to supply the callback.</li>
     *   </ul>
     *   Example <code>Y.on(function(arg1, arg2, etc) { // obj.methodname was executed }, obj 'methodname');</code>
     * </li>
     * </ul>
     *
     * <code>on</code> corresponds to the moment before any default behavior of
     * the event.  <code>after</code> works the same way, but these listeners
     * execute after the event's default behavior.  <code>before</code> is an
     * alias for <code>on</code>.
     *
     * @method on
     * @param type** event type (this parameter does not apply for function events)
     * @param fn the callback
     * @param target** a descriptor for the target (applies to custom events only).
     * For function events, this is the object that contains the function to
     * execute.
     * @param extra** 0..n Extra information a particular event may need.  These
     * will be documented with the event.  In the case of function events, this
     * is the name of the function to execute on the host.  In the case of
     * delegate listeners, this is the event delegation specification.
     * @param context optionally change the value of 'this' in the callback
     * @param args* 0..n additional arguments to pass to the callback.
     * @return the event target or a detach handle per 'chain' config
     * @for YUI
     */

    /**
     * after() is a unified interface for subscribing to
     * most events exposed by YUI.  This includes custom events,
     * DOM events, and AOP events.  This works the same way as
     * the on() function, only it operates after any default
     * behavior for the event has executed. @see <code>on</code> for more
     * information.
     * @method after
     * @param type event type (this parameter does not apply for function events)
     * @param fn the callback
     * @param target a descriptor for the target (applies to custom events only).
     * For function events, this is the object that contains the function to
     * execute.
     * @param extra 0..n Extra information a particular event may need.  These
     * will be documented with the event.  In the case of function events, this
     * is the name of the function to execute on the host.  In the case of
     * delegate listeners, this is the event delegation specification.
     * @param context optionally change the value of 'this' in the callback
     * @param args* 0..n additional arguments to pass to the callback.
     * @return the event target or a detach handle per 'chain' config
     * @for YUI
     */

Copyright © 2009 Yahoo! Inc. All rights reserved.