# Yahoo! UI Library

### event-custom 3.0.0b1

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

    (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, full_t;

            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);
            }

            // parts = t.split(DETACH_PREFIX_SPLITTER);
            // if (parts.length > 1) {
            //     detachcategory = parts[0];
            //     t = parts[1];
            //     if (t == '*') {
            //          t = null;
            //     }
            // }

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

            full_t = _getType(t, pre);

            return [detachcategory, full_t, after, t];
        }),

        ET = function(opts) {

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

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

            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;

            if (L.isObject(type, true)) {

                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 : ret;

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

            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));
                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;
                // check for the existance of an event adaptor
                if (adapt && adapt.on) {
                    n = args[2];
                    Y.log('Using adaptor for ' + shorttype + ', ' + n, 'info', 'event');
                    if (Node && n && (n instanceof Node)) {
                        args[2] = Node.getDOMNode(n);
                    }
                    handle = adapt.on.apply(Y, args);
                // check to see if the target is an EventTarget.  If so,
                // delegate to it (the EventTarget should handle whether
                // or not the prefix was included);
                // } else if (o && !(o instanceof YUI) && o.getEvent) {
                //     a = Y.Array(arguments, 0, true);
                //     a.splice(2, 1);
                //     return o.on.apply(o, a);
                // } else if ((!type) || (!adapt && type.indexOf(':') == -1)) {
                } else if ((!type) || (!adapt && Node && (shorttype in Node.DOM_EVENTS))) {
                    handle = Y.Event._attach(args);
                }

            }

            if (!handle) {

                // Y.log('parts: ' + parts);
                ce     = this._yuievt.events[type] || this.publish(type);
                // args   = Y.Array(arguments, 1, true);
                // f = (after) ? ce.after : ce.on;
                // handle = f.apply(ce, args);

                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);

                // Y.log('storing: ' + key);
            }

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

        },

        /**
         * subscribe to an event
         * @method subscribe
         * @deprecated use on
         */
        subscribe: function() {
            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 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,
            evts = this._yuievt.events, ce, i, ret = true,

            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 : true;
            // extra redirection so we catch adaptor events too.  take a look at this.
            } else if (Y.Node && (this instanceof Y.Node) && ((!shorttype) || (shorttype in Y.Node.DOM_EVENTS))) {
                args = Y.Array(arguments, 0, true);
                args[2] = Y.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 && type.indexOf(':') == -1)) {
                    args[0] = type;
                    return Y.Event.detach.apply(Y.Event, args);
                }
            }

            if (type) {
                ce = evts[type];
                if (ce) {
                    return ce.detach(fn, context);
                }
            } else {
                for (i in evts) {
                    if (evts.hasOwnProperty(i)) {
                        ret = ret && evts[i].detach(fn, context);
                    }
                }
                return ret;
            }

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

        /**
         * 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) {
            type = _getType(type, this._yuievt.config.prefix);
            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) {
            // this._yuievt.config.prefix

            type = _getType(type, this._yuievt.config.prefix);

            var events, ce, ret, o;

            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.configured) {
            if (ce) {
    // ce.log("publish applying new config to published event: '"+type+"' exists", 'info', 'event');
                if (opts) {
                    ce.applyConfig(opts, true);
                }

            } else {
                o = (opts) ?  Y.mix(opts, this._yuievt.defaults) : this._yuievt.defaults;
                // apply defaults

                ce = new Y.CustomEvent(type, o);

                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.
         *
         * @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.
         * @return {boolean} the return value from Event.Custom.fire
         *
         */
        fire: function(type) {

            var typeIncluded = L.isString(type),
                t = (typeIncluded) ? type : (type && type.type),
                ce, a, ret;

            t = _getType(t, this._yuievt.config.prefix);
            ce = this.getEvent(t);

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

                // if this object has bubble targets, we need to publish the
                // event in order for it to bubble.
                if (this._yuievt.hasTargets) {
                    // ce = this.publish(t);
                    // ce.details = Y.Array(arguments, (typeIncluded) ? 1 : 0, true);

                    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
         * @return {Event.Custom} the custom event or null
         */
        getEvent: function(type) {
            type = _getType(type, this._yuievt.config.prefix);
            var e = this._yuievt.events;
            return (e && type in e) ? e[type] : null;
        },

        /**
         * Propagate an event
         * @method bubble
         * @param evt {Event.Custom} the custom event to propagate
         * @return {boolean} the aggregated return value from Event.Custom.fire
         */
        bubble: function(evt, args, target) {

            var targs = this._yuievt.targets, ret = true,
                t, type, ce, i;

            if (!evt || ((!evt.stopped) && targs)) {

                // Y.log('Bubbling ' + evt.type);
                for (i in targs) {
                    if (targs.hasOwnProperty(i)) {
                        t = targs[i];
                        type = evt && evt.type;
                        ce = t.getEvent(type);

                        // if this event was not published on the bubble target,
                        // publish it with sensible default properties
                        if (!ce) {

                            // publish the event on the bubble target using this event
                            // for its configuration
                            // ce = t.publish(type, evt);

                            // set the host and context appropriately
                            // ce.context = (evt.host === evt.context) ? t : evt.context;
                            // ce.host = t;

                            // clear handlers if specified on this event
                            // ce.defaultFn = null;
                            // ce.preventedFn = null;
                            // ce.stoppedFn = null;

                            if (t._yuievt.hasTargets) {
                                t.bubble.call(t, evt, args, target);
                            }

                        } else {

                            ce.target = target || (evt && evt.target) || this;

                            ce.currentTarget = t;

                            ret = ret && ce.fire.apply(ce, args || evt.details);

                            // stopPropagation() was called
                            if (ce.stopped) {
                                break;
                            }
                        }
                    }
                }
            }

            return ret;
        },

        /**
         * 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, 1-n arguments
         *
         * For methods:
         * callback, object (method host), methodName, context, 1-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?

    })();

Copyright © 2009 Yahoo! Inc. All rights reserved.