#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

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

    /**
     * Adds event facades, preventable default behavior, and bubbling.
     * events.
     * @module event-custom
     * @submodule event-custom-complex
     */

    var FACADE,
        FACADE_KEYS,
        YObject = Y.Object,
        key,
        EMPTY = {},
        CEProto = Y.CustomEvent.prototype,
        ETProto = Y.EventTarget.prototype,

        mixFacadeProps = function(facade, payload) {
            var p;

            for (p in payload) {
                if (!(FACADE_KEYS.hasOwnProperty(p))) {
                    facade[p] = payload[p];
                }
            }
        };

    /**
     * Wraps and protects a custom event for use when emitFacade is set to true.
     * Requires the event-custom-complex module
     * @class EventFacade
     * @param e {Event} the custom event
     * @param currentTarget {HTMLElement} the element the listener was attached to
     */

    Y.EventFacade = function(e, currentTarget) {

        if (!e) {
            e = EMPTY;
        }

        this._event = e;

        /**
         * The arguments passed to fire
         * @property details
         * @type Array
         */
        this.details = e.details;

        /**
         * The event type, this can be overridden by the fire() payload
         * @property type
         * @type string
         */
        this.type = e.type;

        /**
         * The real event type
         * @property _type
         * @type string
         * @private
         */
        this._type = e.type;

        //////////////////////////////////////////////////////

        /**
         * Node reference for the targeted eventtarget
         * @property target
         * @type Node
         */
        this.target = e.target;

        /**
         * Node reference for the element that the listener was attached to.
         * @property currentTarget
         * @type Node
         */
        this.currentTarget = currentTarget;

        /**
         * Node reference to the relatedTarget
         * @property relatedTarget
         * @type Node
         */
        this.relatedTarget = e.relatedTarget;

    };

    Y.mix(Y.EventFacade.prototype, {

        /**
         * Stops the propagation to the next bubble target
         * @method stopPropagation
         */
        stopPropagation: function() {
            this._event.stopPropagation();
            this.stopped = 1;
        },

        /**
         * Stops the propagation to the next bubble target and
         * prevents any additional listeners from being exectued
         * on the current target.
         * @method stopImmediatePropagation
         */
        stopImmediatePropagation: function() {
            this._event.stopImmediatePropagation();
            this.stopped = 2;
        },

        /**
         * Prevents the event's default behavior
         * @method preventDefault
         */
        preventDefault: function() {
            this._event.preventDefault();
            this.prevented = 1;
        },

        /**
         * Stops the event propagation and prevents the default
         * event behavior.
         * @method halt
         * @param immediate {boolean} if true additional listeners
         * on the current target will not be executed
         */
        halt: function(immediate) {
            this._event.halt(immediate);
            this.prevented = 1;
            this.stopped = (immediate) ? 2 : 1;
        }

    });

    CEProto.fireComplex = function(args) {

        var es,
            ef,
            q,
            queue,
            ce,
            ret = true,
            events,
            subs,
            ons,
            afters,
            afterQueue,
            postponed,
            prevented,
            preventedFn,
            defaultFn,
            self = this,
            host = self.host || self,
            next,
            oldbubble,
            stack,
            yuievt = host._yuievt,
            hasPotentialSubscribers;

        stack = self.stack;

        if (stack) {

            // queue this event if the current item in the queue bubbles
            if (self.queuable && self.type !== stack.next.type) {
                self.log('queue ' + self.type);

                if (!stack.queue) {
                    stack.queue = [];
                }
                stack.queue.push([self, args]);

                return true;
            }
        }

        hasPotentialSubscribers = self.hasSubs() || yuievt.hasTargets || self.broadcast;

        self.target = self.target || host;
        self.currentTarget = host;

        self.details = args.concat();

        if (hasPotentialSubscribers) {

            es = stack || {

               id: self.id, // id of the first event in the stack
               next: self,
               silent: self.silent,
               stopped: 0,
               prevented: 0,
               bubbling: null,
               type: self.type,
               // defaultFnQueue: new Y.Queue(),
               defaultTargetOnly: self.defaultTargetOnly

            };

            subs = self.getSubs();
            ons = subs[0];
            afters = subs[1];

            self.stopped = (self.type !== es.type) ? 0 : es.stopped;
            self.prevented = (self.type !== es.type) ? 0 : es.prevented;

            if (self.stoppedFn) {
                // PERF TODO: Can we replace with callback, like preventedFn. Look into history
                events = new Y.EventTarget({
                    fireOnce: true,
                    context: host
                });
                self.events = events;
                events.on('stopped', self.stoppedFn);
            }

            // self.log("Firing " + self  + ", " + "args: " + args);
            self.log("Firing " + self.type);

            self._facade = null; // kill facade to eliminate stale properties

            ef = self._getFacade(args);

            if (ons) {
                self._procSubs(ons, args, ef);
            }

            // bubble if this is hosted in an event target and propagation has not been stopped
            if (self.bubbles && host.bubble && !self.stopped) {
                oldbubble = es.bubbling;

                es.bubbling = self.type;

                if (es.type !== self.type) {
                    es.stopped = 0;
                    es.prevented = 0;
                }

                ret = host.bubble(self, args, null, es);

                self.stopped = Math.max(self.stopped, es.stopped);
                self.prevented = Math.max(self.prevented, es.prevented);

                es.bubbling = oldbubble;
            }

            prevented = self.prevented;

            if (prevented) {
                preventedFn = self.preventedFn;
                if (preventedFn) {
                    preventedFn.apply(host, args);
                }
            } else {
                defaultFn = self.defaultFn;

                if (defaultFn && ((!self.defaultTargetOnly && !es.defaultTargetOnly) || host === ef.target)) {
                    defaultFn.apply(host, args);
                }
            }

            // broadcast listeners are fired as discreet events on the
            // YUI instance and potentially the YUI global.
            if (self.broadcast) {
                self._broadcast(args);
            }

            if (afters && !self.prevented && self.stopped < 2) {

                // Queue the after
                afterQueue = es.afterQueue;

                if (es.id === self.id || self.type !== yuievt.bubbling) {

                    self._procSubs(afters, args, ef);

                    if (afterQueue) {
                        while ((next = afterQueue.last())) {
                            next();
                        }
                    }
                } else {
                    postponed = afters;

                    if (es.execDefaultCnt) {
                        postponed = Y.merge(postponed);

                        Y.each(postponed, function(s) {
                            s.postponed = true;
                        });
                    }

                    if (!afterQueue) {
                        es.afterQueue = new Y.Queue();
                    }

                    es.afterQueue.add(function() {
                        self._procSubs(postponed, args, ef);
                    });
                }

            }

            self.target = null;

            if (es.id === self.id) {

                queue = es.queue;

                if (queue) {
                    while (queue.length) {
                        q = queue.pop();
                        ce = q[0];
                        // set up stack to allow the next item to be processed
                        es.next = ce;
                        ce._fire(q[1]);
                    }
                }

                self.stack = null;
            }

            ret = !(self.stopped);

            if (self.type !== yuievt.bubbling) {
                es.stopped = 0;
                es.prevented = 0;
                self.stopped = 0;
                self.prevented = 0;
            }

        } else {
            defaultFn = self.defaultFn;

            if(defaultFn) {
                ef = self._getFacade(args);

                if ((!self.defaultTargetOnly) || (host === ef.target)) {
                    defaultFn.apply(host, args);
                }
            }
        }

        // Kill the cached facade to free up memory.
        // Otherwise we have the facade from the last fire, sitting around forever.
        self._facade = null;

        return ret;
    };

    CEProto._getFacade = function(fireArgs) {

        var userArgs = this.details,
            firstArg = userArgs && userArgs[0],
            firstArgIsObj = (firstArg && (typeof firstArg === "object")),
            ef = this._facade;

        if (!ef) {
            ef = new Y.EventFacade(this, this.currentTarget);
        }

        if (firstArgIsObj) {
            // protect the event facade properties
            mixFacadeProps(ef, firstArg);

            // Allow the event type to be faked http://yuilibrary.com/projects/yui3/ticket/2528376
            if (firstArg.type) {
                ef.type = firstArg.type;
            }

            if (fireArgs) {
                fireArgs[0] = ef;
            }
        } else {
            if (fireArgs) {
                fireArgs.unshift(ef);
            }
        }

        // update the details field with the arguments
        ef.details = this.details;

        // use the original target when the event bubbled to this target
        ef.target = this.originalTarget || this.target;

        ef.currentTarget = this.currentTarget;
        ef.stopped = 0;
        ef.prevented = 0;

        this._facade = ef;

        return this._facade;
    };

    /**
     * Stop propagation to bubble targets
     * @for CustomEvent
     * @method stopPropagation
     */
    CEProto.stopPropagation = function() {
        this.stopped = 1;
        if (this.stack) {
            this.stack.stopped = 1;
        }
        if (this.events) {
            this.events.fire('stopped', this);
        }
    };

    /**
     * Stops propagation to bubble targets, and prevents any remaining
     * subscribers on the current target from executing.
     * @method stopImmediatePropagation
     */
    CEProto.stopImmediatePropagation = function() {
        this.stopped = 2;
        if (this.stack) {
            this.stack.stopped = 2;
        }
        if (this.events) {
            this.events.fire('stopped', this);
        }
    };

    /**
     * Prevents the execution of this event's defaultFn
     * @method preventDefault
     */
    CEProto.preventDefault = function() {
        if (this.preventable) {
            this.prevented = 1;
            if (this.stack) {
                this.stack.prevented = 1;
            }
        }
    };

    /**
     * Stops the event propagation and prevents the default
     * event behavior.
     * @method halt
     * @param immediate {boolean} if true additional listeners
     * on the current target will not be executed
     */
    CEProto.halt = function(immediate) {
        if (immediate) {
            this.stopImmediatePropagation();
        } else {
            this.stopPropagation();
        }
        this.preventDefault();
    };

    /**
     * Registers another EventTarget as a bubble target.  Bubble order
     * is determined by the order registered.  Multiple targets can
     * be specified.
     *
     * Events can only bubble if emitFacade is true.
     *
     * Included in the event-custom-complex submodule.
     *
     * @method addTarget
     * @param o {EventTarget} the target to add
     * @for EventTarget
     */
    ETProto.addTarget = function(o) {
        var etState = this._yuievt;

        if (!etState.targets) {
            etState.targets = {};
        }

        etState.targets[Y.stamp(o)] = o;
        etState.hasTargets = true;
    };

    /**
     * Returns an array of bubble targets for this object.
     * @method getTargets
     * @return EventTarget[]
     */
    ETProto.getTargets = function() {
        var targets = this._yuievt.targets;
        return targets ? YObject.values(targets) : [];
    };

    /**
     * Removes a bubble target
     * @method removeTarget
     * @param o {EventTarget} the target to remove
     * @for EventTarget
     */
    ETProto.removeTarget = function(o) {
        var targets = this._yuievt.targets;

        if (targets) {
            delete targets[Y.stamp(o, true)];

            if (YObject.size(targets) === 0) {
                this._yuievt.hasTargets = false;
            }
        }
    };

    /**
     * Propagate an event.  Requires the event-custom-complex module.
     * @method bubble
     * @param evt {CustomEvent} the custom event to propagate
     * @return {boolean} the aggregated return value from Event.Custom.fire
     * @for EventTarget
     */
    ETProto.bubble = function(evt, args, target, es) {

        var targs = this._yuievt.targets,
            ret = true,
            t,
            ce,
            i,
            bc,
            ce2,
            type = evt && evt.type,
            originalTarget = target || (evt && evt.target) || this,
            oldbubble;

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

            for (i in targs) {
                if (targs.hasOwnProperty(i)) {

                    t = targs[i];

                    ce = t._yuievt.events[type];

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

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

                    oldbubble = t._yuievt.bubbling;
                    t._yuievt.bubbling = type;

                    // if this event was not published on the bubble target,
                    // continue propagating the event.
                    if (!ce) {
                        if (t._yuievt.hasTargets) {
                            t.bubble(evt, args, originalTarget, es);
                        }
                    } else {

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

                        // set the original target to that the target payload on the facade is correct.
                        ce.target = originalTarget;
                        ce.originalTarget = originalTarget;
                        ce.currentTarget = t;
                        bc = ce.broadcast;
                        ce.broadcast = false;

                        // default publish may not have emitFacade true -- that
                        // shouldn't be what the implementer meant to do
                        ce.emitFacade = true;

                        ce.stack = es;

                        // TODO: See what's getting in the way of changing this to use
                        // the more performant ce._fire(args || evt.details || []).

                        // Something in Widget Parent/Child tests is not happy if we
                        // change it - maybe evt.details related?
                        ret = ret && ce.fire.apply(ce, args || evt.details || []);

                        ce.broadcast = bc;
                        ce.originalTarget = null;

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

                    t._yuievt.bubbling = oldbubble;
                }
            }
        }

        return ret;
    };

    FACADE = new Y.EventFacade();
    FACADE_KEYS = {};

    // Flatten whitelist
    for (key in FACADE) {
        FACADE_KEYS[key] = true;
    }