#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# File: event-custom/js/event-target.js

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

    /**
     * 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
     */

    var L = Y.Lang,
        PREFIX_DELIMITER = ':',
        CATEGORY_DELIMITER = '|',
        AFTER_PREFIX = '~AFTER~',
        WILD_TYPE_RE = /(.*?)(:)(.*?)/,

        _wildType = Y.cached(function(type) {
            return type.replace(WILD_TYPE_RE, "*$2$3");
        }),

        /**
         * 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 = function(type, pre) {

            if (!pre || 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);
            }

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

            var etState = this._yuievt,
                etConfig;

            if (!etState) {
                etState = this._yuievt = {
                    events: {},    // PERF: Not much point instantiating lazily. We're bound to have events
                    targets: null, // PERF: Instantiate lazily, if user actually adds target,
                    config: {
                        host: this,
                        context: this
                    },
                    chain: Y.config.chain
                };
            }

            etConfig = etState.config;

            if (opts) {
                mixConfigs(etConfig, opts, true);

                if (opts.chain !== undefined) {
                    etState.chain = opts.chain;
                }

                if (opts.prefix) {
                    etConfig.prefix = opts.prefix;
                }
            }
        };

    ET.prototype = {

        constructor: ET,

        /**
         * Listen to a custom event hosted by this object one time.
         * This is the equivalent to <code>on</code> except the
         * listener is immediatelly detached when it is executed.
         * @method once
         * @param {String} type The name of the event
         * @param {Function} fn The callback to execute in response to the event
         * @param {Object} [context] Override `this` object in callback
         * @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
         * @return {EventHandle} A subscription handle capable of detaching the
         *                       subscription
         */
        once: function() {
            var handle = this.on.apply(this, arguments);
            handle.batch(function(hand) {
                if (hand.sub) {
                    hand.sub.once = true;
                }
            });
            return handle;
        },

        /**
         * Listen to a custom event hosted by this object one time.
         * This is the equivalent to <code>after</code> except the
         * listener is immediatelly detached when it is executed.
         * @method onceAfter
         * @param {String} type The name of the event
         * @param {Function} fn The callback to execute in response to the event
         * @param {Object} [context] Override `this` object in callback
         * @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
         * @return {EventHandle} A subscription handle capable of detaching that
         *                       subscription
         */
        onceAfter: function() {
            var handle = this.after.apply(this, arguments);
            handle.batch(function(hand) {
                if (hand.sub) {
                    hand.sub.once = true;
                }
            });
            return handle;
        },

        /**
         * Takes the type parameter passed to 'on' and parses out the
         * various pieces that could be included in the type.  If the
         * event type is passed without a prefix, it will be expanded
         * to include the prefix one is supplied or the event target
         * is configured with a default prefix.
         * @method parseType
         * @param {String} type the type
         * @param {String} [pre=this._yuievt.config.prefix] the prefix
         * @since 3.3.0
         * @return {Array} an array containing:
         *  * the detach category, if supplied,
         *  * the prefixed event type,
         *  * whether or not this is an after listener,
         *  * the supplied event type
         */
        parseType: function(type, pre) {
            return _parseType(type, pre || this._yuievt.config.prefix);
        },

        /**
         * Subscribe a callback function to a custom event fired by this object or
         * from an object that bubbles its events to this object.
         *
         * Callback functions for events published with `emitFacade = true` will
         * receive an `EventFacade` as the first argument (typically named "e").
         * These callbacks can then call `e.preventDefault()` to disable the
         * behavior published to that event's `defaultFn`.  See the `EventFacade`
         * API for all available properties and methods. Subscribers to
         * non-`emitFacade` events will receive the arguments passed to `fire()`
         * after the event name.
         *
         * To subscribe to multiple events at once, pass an object as the first
         * argument, where the key:value pairs correspond to the eventName:callback,
         * or pass an array of event names as the first argument to subscribe to
         * all listed events with the same callback.
         *
         * Returning `false` from a callback is supported as an alternative to
         * calling `e.preventDefault(); e.stopPropagation();`.  However, it is
         * recommended to use the event methods whenever possible.
         *
         * @method on
         * @param {String} type The name of the event
         * @param {Function} fn The callback to execute in response to the event
         * @param {Object} [context] Override `this` object in callback
         * @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
         * @return {EventHandle} A subscription handle capable of detaching that
         *                       subscription
         */
        on: function(type, fn, context) {

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

            // full name, args, detachcategory, after
            this._monitor('attach', parts[1], {
                args: arguments,
                category: parts[0],
                after: parts[2]
            });

            if (L.isObject(type)) {

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

                f = fn;
                c = context;
                args = nativeSlice.call(arguments, 0);
                ret = [];

                if (L.isArray(type)) {
                    isArr = true;
                }

                after = type._after;
                delete type._after;

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

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

                    var nv = (after) ? AFTER_PREFIX : '';

                    args[0] = nv + ((isArr) ? v : k);
                    args[1] = f;
                    args[2] = c;

                    ret.push(this.on.apply(this, args));

                }, this);

                return (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 && Y.instanceOf(this, Node) && (shorttype in Node.DOM_EVENTS)) {
                args = nativeSlice.call(arguments, 0);
                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 (Y.instanceOf(this, YUI)) {

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

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

                    if (Y.instanceOf(n, Y.NodeList)) {
                        n = Y.NodeList.getDOMNodes(n);
                    } else if (Y.instanceOf(n, 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 = yuievt.events[type] || this.publish(type);
                handle = ce._on(fn, context, (arguments.length > 3) ? nativeSlice.call(arguments, 3) : null, (after) ? 'after' : true);

                // TODO: More robust regex, accounting for category
                if (type.indexOf("*:") !== -1) {
                    this._hasSiblings = true;
                }
            }

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

            return (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,
                Node = Y.Node,
                isNode = Node && (Y.instanceOf(this, Node));

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

                return this;
            }

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

            keyDetacher = function(lcat, ltype, host) {
                var handles = lcat[ltype], ce, i;
                if (handles) {
                    for (i = handles.length - 1; i >= 0; --i) {
                        ce = handles[i].evt;
                        if (ce.host === host || ce.el === host) {
                            handles[i].detach();
                        }
                    }
                }
            };

            if (detachcategory) {

                cat = store[detachcategory];
                type = parts[1];
                detachhost = (isNode) ? Y.Node.getDOMNode(this) : this;

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

                    return this;
                }

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

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

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

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

            return this;
        },

        /**
         * detach a listener
         * @method unsubscribe
         * @deprecated use detach
         */
        unsubscribe: function() {
    Y.log('EventTarget unsubscribe() is deprecated, use detach()', 'warn', 'deprecated');
            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() {
    Y.log('EventTarget unsubscribeAll() is deprecated, use detachAll()', 'warn', 'deprecated');
            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)
         *              Events can only bubble if emitFacade is 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>
         *   'async': fireOnce event listeners will fire synchronously if the event has already
         *    fired unless async is true.
         *    </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>
         *   'monitored': specifies whether or not this event should send notifications about
         *   when the event has been attached, detached, or published.
         *    </li>
         *    <li>
         *   'type': the event type (valid option if not provided as the first parameter to publish)
         *    </li>
         *  </ul>
         *
         *  @return {CustomEvent} the custom event
         *
         */
        publish: function(type, opts) {

            var ret,
                etState = this._yuievt,
                etConfig = etState.config,
                pre = etConfig.prefix;

            if (typeof type === "string")  {
                if (pre) {
                    type = _getType(type, pre);
                }
                ret = this._publish(type, etConfig, opts);
            } else {
                ret = {};

                Y.each(type, function(v, k) {
                    if (pre) {
                        k = _getType(k, pre);
                    }
                    ret[k] = this._publish(k, etConfig, v || opts);
                }, this);

            }

            return ret;
        },

        /**
         * Returns the fully qualified type, given a short type string.
         * That is, returns "foo:bar" when given "bar" if "foo" is the configured prefix.
         *
         * NOTE: This method, unlike _getType, does no checking of the value passed in, and
         * is designed to be used with the low level _publish() method, for critical path
         * implementations which need to fast-track publish for performance reasons.
         *
         * @method _getFullType
         * @private
         * @param {String} type The short type to prefix
         * @return {String} The prefixed type, if a prefix is set, otherwise the type passed in
         */
        _getFullType : function(type) {

            var pre = this._yuievt.config.prefix;

            if (pre) {
                return pre + PREFIX_DELIMITER + type;
            } else {
                return type;
            }
        },

        /**
         * The low level event publish implementation. It expects all the massaging to have been done
         * outside of this method. e.g. the `type` to `fullType` conversion. It's designed to be a fast
         * path publish, which can be used by critical code paths to improve performance.
         *
         * @method _publish
         * @private
         * @param {String} fullType The prefixed type of the event to publish.
         * @param {Object} etOpts The EventTarget specific configuration to mix into the published event.
         * @param {Object} ceOpts The publish specific configuration to mix into the published event.
         * @return {CustomEvent} The published event. If called without `etOpts` or `ceOpts`, this will
         * be the default `CustomEvent` instance, and can be configured independently.
         */
        _publish : function(fullType, etOpts, ceOpts) {

            var ce,
                etState = this._yuievt,
                etConfig = etState.config,
                host = etConfig.host,
                context = etConfig.context,
                events = etState.events;

            ce = events[fullType];

            // PERF: Hate to pull the check out of monitor, but trying to keep critical path tight.
            if ((etConfig.monitored && !ce) || (ce && ce.monitored)) {
                this._monitor('publish', fullType, {
                    args: arguments
                });
            }

            if (!ce) {
                // Publish event
                ce = events[fullType] = new Y.CustomEvent(fullType, etOpts);

                if (!etOpts) {
                    ce.host = host;
                    ce.context = context;
                }
            }

            if (ceOpts) {
                mixConfigs(ce, ceOpts, true);
            }

            return ce;
        },

        /**
         * This is the entry point for the event monitoring system.
         * You can monitor 'attach', 'detach', 'fire', and 'publish'.
         * When configured, these events generate an event.  click ->
         * click_attach, click_detach, click_publish -- these can
         * be subscribed to like other events to monitor the event
         * system.  Inividual published events can have monitoring
         * turned on or off (publish can't be turned off before it
         * it published) by setting the events 'monitor' config.
         *
         * @method _monitor
         * @param what {String} 'attach', 'detach', 'fire', or 'publish'
         * @param eventType {String|CustomEvent} The prefixed name of the event being monitored, or the CustomEvent object.
         * @param o {Object} Information about the event interaction, such as
         *                  fire() args, subscription category, publish config
         * @private
         */
        _monitor: function(what, eventType, o) {
            var monitorevt, ce, type;

            if (eventType) {
                if (typeof eventType === "string") {
                    type = eventType;
                    ce = this.getEvent(eventType, true);
                } else {
                    ce = eventType;
                    type = eventType.type;
                }

                if ((this._yuievt.config.monitored && (!ce || ce.monitored)) || (ce && ce.monitored)) {
                    monitorevt = type + '_' + what;
                    o.monitored = what;
                    this.fire.call(this, monitorevt, 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 {EventTarget} the event host
         */
        fire: function(type) {

            var typeIncluded = (typeof type === "string"),
                argCount = arguments.length,
                t = type,
                yuievt = this._yuievt,
                etConfig = yuievt.config,
                pre = etConfig.prefix,
                ret,
                ce,
                ce2,
                args;

            if (typeIncluded && argCount <= 3) {

                // PERF: Try to avoid slice/iteration for the common signatures

                // Most common
                if (argCount === 2) {
                    args = [arguments[1]]; // fire("foo", {})
                } else if (argCount === 3) {
                    args = [arguments[1], arguments[2]]; // fire("foo", {}, opts)
                } else {
                    args = []; // fire("foo")
                }

            } else {
                args = nativeSlice.call(arguments, ((typeIncluded) ? 1 : 0));
            }

            if (!typeIncluded) {
                t = (type && type.type);
            }

            if (pre) {
                t = _getType(t, pre);
            }

            ce = yuievt.events[t];

            if (this._hasSiblings) {
                ce2 = this.getSibling(t, ce);

                if (ce2 && !ce) {
                    ce = this.publish(t);
                }
            }

            // PERF: trying to avoid function call, since this is a critical path
            if ((etConfig.monitored && (!ce || ce.monitored)) || (ce && ce.monitored)) {
                this._monitor('fire', (ce || t), {
                    args: args
                });
            }

            // this event has not been published or subscribed to
            if (!ce) {
                if (yuievt.hasTargets) {
                    return this.bubble({ type: t }, args, this);
                }

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

                if (ce2) {
                    ce.sibling = ce2;
                }

                ret = ce._fire(args);
            }

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

        getSibling: function(type, ce) {
            var ce2;

            // delegate to *:type events if there are subscribers
            if (type.indexOf(PREFIX_DELIMITER) > -1) {
                type = _wildType(type);
                ce2 = this.getEvent(type, true);
                if (ce2) {
                    ce2.applyConfig(ce);
                    ce2.bubbles = false;
                    ce2.broadcast = 0;
                }
            }

            return ce2;
        },

        /**
         * 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 {CustomEvent} 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] || 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 {String} type The name of the event
         * @param {Function} fn The callback to execute in response to the event
         * @param {Object} [context] Override `this` object in callback
         * @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
         * @return {EventHandle} A subscription handle capable of detaching the
         *                       subscription
         */
        after: function(type, fn) {

            var a = nativeSlice.call(arguments, 0);

            switch (L.type(type)) {
                case 'function':
                    return Y.Do.after.apply(Y.Do, arguments);
                case 'array':
                //     YArray.each(a[0], function(v) {
                //         v = AFTER_PREFIX + v;
                //     });
                //     break;
                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
         */
        before: function() {
            return this.on.apply(this, arguments);
        }

    };

    Y.EventTarget = ET;

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

    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?

    /**
    `Y.on()` can do many things:

    <ul>
        <li>Subscribe to custom events `publish`ed and `fire`d from Y</li>
        <li>Subscribe to custom events `publish`ed with `broadcast` 1 or 2 and
            `fire`d from any object in the YUI instance sandbox</li>
        <li>Subscribe to DOM events</li>
        <li>Subscribe to the execution of a method on any object, effectively
        treating that method as an event</li>
    </ul>

    For custom event subscriptions, pass the custom event name as the first argument
    and callback as the second. The `this` object in the callback will be `Y` unless
    an override is passed as the third argument.

        Y.on('io:complete', function () {
            Y.MyApp.updateStatus('Transaction complete');
        });

    To subscribe to DOM events, pass the name of a DOM event as the first argument
    and a CSS selector string as the third argument after the callback function.
    Alternately, the third argument can be a `Node`, `NodeList`, `HTMLElement`,
    array, or simply omitted (the default is the `window` object).

        Y.on('click', function (e) {
            e.preventDefault();

            // proceed with ajax form submission
            var url = this.get('action');
            ...
        }, '#my-form');

    The `this` object in DOM event callbacks will be the `Node` targeted by the CSS
    selector or other identifier.

    `on()` subscribers for DOM events or custom events `publish`ed with a
    `defaultFn` can prevent the default behavior with `e.preventDefault()` from the
    event object passed as the first parameter to the subscription callback.

    To subscribe to the execution of an object method, pass arguments corresponding to the call signature for
    <a href="../classes/Do.html#methods_before">`Y.Do.before(...)`</a>.

    NOTE: The formal parameter list below is for events, not for function
    injection.  See `Y.Do.before` for that signature.

    @method on
    @param {String} type DOM or custom event name
    @param {Function} fn The callback to execute in response to the event
    @param {Object} [context] Override `this` object in callback
    @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
    @return {EventHandle} A subscription handle capable of detaching the
                          subscription
    @see Do.before
    @for YUI
    **/

    /**
    Listen for an event one time.  Equivalent to `on()`, except that
    the listener is immediately detached when executed.

    See the <a href="#methods_on">`on()` method</a> for additional subscription
    options.

    @see on
    @method once
    @param {String} type DOM or custom event name
    @param {Function} fn The callback to execute in response to the event
    @param {Object} [context] Override `this` object in callback
    @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
    @return {EventHandle} A subscription handle capable of detaching the
                          subscription
    @for YUI
    **/

    /**
    Listen for an event one time.  Equivalent to `once()`, except, like `after()`,
    the subscription callback executes after all `on()` subscribers and the event's
    `defaultFn` (if configured) have executed.  Like `after()` if any `on()` phase
    subscriber calls `e.preventDefault()`, neither the `defaultFn` nor the `after()`
    subscribers will execute.

    The listener is immediately detached when executed.

    See the <a href="#methods_on">`on()` method</a> for additional subscription
    options.

    @see once
    @method onceAfter
    @param {String} type The custom event name
    @param {Function} fn The callback to execute in response to the event
    @param {Object} [context] Override `this` object in callback
    @param {Any} [arg*] 0..n additional arguments to supply to the subscriber
    @return {EventHandle} A subscription handle capable of detaching the
                          subscription
    @for YUI
    **/

    /**
    Like `on()`, this method creates a subscription to a custom event or to the
    execution of a method on an object.

    For events, `after()` subscribers are executed after the event's
    `defaultFn` unless `e.preventDefault()` was called from an `on()` subscriber.

    See the <a href="#methods_on">`on()` method</a> for additional subscription
    options.

    NOTE: The subscription signature shown is for events, not for function
    injection.  See <a href="../classes/Do.html#methods_after">`Y.Do.after`</a>
    for that signature.

    @see on
    @see Do.after
    @method after
    @param {String} type The custom event name
    @param {Function} fn The callback to execute in response to the event
    @param {Object} [context] Override `this` object in callback
    @param {Any} [args*] 0..n additional arguments to supply to the subscriber
    @return {EventHandle} A subscription handle capable of detaching the
                          subscription
    @for YUI
    **/