# Yahoo! UI Library

### event-custom 3.3.0

Yahoo! UI Library > event-custom > event-do.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
     */

    /**
     * Allows for the insertion of methods that are executed before or after
     * a specified method
     * @class Do
     * @static
     */

    var DO_BEFORE = 0,
        DO_AFTER = 1,

    DO = {

        /**
         * Cache of objects touched by the utility
         * @property objs
         * @static
         */
        objs: {},

        /**
         * Execute the supplied method before the specified function
         * @method before
         * @param fn {Function} the function to execute
         * @param obj the object hosting the method to displace
         * @param sFn {string} the name of the method to displace
         * @param c The execution context for fn
         * @param arg* {mixed} 0..n additional arguments to supply to the subscriber
         * when the event fires.
         * @return {string} handle for the subscription
         * @static
         */
        before: function(fn, obj, sFn, c) {
            // Y.log('Do before: ' + sFn, 'info', 'event');
            var f = fn, a;
            if (c) {
                a = [fn, c].concat(Y.Array(arguments, 4, true));
                f = Y.rbind.apply(Y, a);
            }

            return this._inject(DO_BEFORE, f, obj, sFn);
        },

        /**
         * Execute the supplied method after the specified function
         * @method after
         * @param fn {Function} the function to execute
         * @param obj the object hosting the method to displace
         * @param sFn {string} the name of the method to displace
         * @param c The execution context for fn
         * @param arg* {mixed} 0..n additional arguments to supply to the subscriber
         * @return {string} handle for the subscription
         * @static
         */
        after: function(fn, obj, sFn, c) {
            var f = fn, a;
            if (c) {
                a = [fn, c].concat(Y.Array(arguments, 4, true));
                f = Y.rbind.apply(Y, a);
            }

            return this._inject(DO_AFTER, f, obj, sFn);
        },

        /**
         * Execute the supplied method after the specified function
         * @method _inject
         * @param when {string} before or after
         * @param fn {Function} the function to execute
         * @param obj the object hosting the method to displace
         * @param sFn {string} the name of the method to displace
         * @param c The execution context for fn
         * @return {string} handle for the subscription
         * @private
         * @static
         */
        _inject: function(when, fn, obj, sFn) {

            // object id
            var id = Y.stamp(obj), o, sid;

            if (! this.objs[id]) {
                // create a map entry for the obj if it doesn't exist
                this.objs[id] = {};
            }

            o = this.objs[id];

            if (! o[sFn]) {
                // create a map entry for the method if it doesn't exist
                o[sFn] = new Y.Do.Method(obj, sFn);

                // re-route the method to our wrapper
                obj[sFn] =
                    function() {
                        return o[sFn].exec.apply(o[sFn], arguments);
                    };
            }

            // subscriber id
            sid = id + Y.stamp(fn) + sFn;

            // register the callback
            o[sFn].register(sid, fn, when);

            return new Y.EventHandle(o[sFn], sid);

        },

        /**
         * Detach a before or after subscription
         * @method detach
         * @param handle {string} the subscription handle
         */
        detach: function(handle) {

            if (handle.detach) {
                handle.detach();
            }

        },

        _unload: function(e, me) {

        }
    };

    Y.Do = DO;

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

    /**
     * Contains the return value from the wrapped method, accessible
     * by 'after' event listeners.
     *
     * @property Do.originalRetVal
     * @static
     * @since 2.3.0
     */

    /**
     * Contains the current state of the return value, consumable by
     * 'after' event listeners, and updated if an after subscriber
     * changes the return value generated by the wrapped function.
     *
     * @property Do.currentRetVal
     * @static
     * @since 2.3.0
     */

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

    /**
     * Wrapper for a displaced method with aop enabled
     * @class Do.Method
     * @constructor
     * @param obj The object to operate on
     * @param sFn The name of the method to displace
     */
    DO.Method = function(obj, sFn) {
        this.obj = obj;
        this.methodName = sFn;
        this.method = obj[sFn];
        this.before = {};
        this.after = {};
    };

    /**
     * Register a aop subscriber
     * @method register
     * @param sid {string} the subscriber id
     * @param fn {Function} the function to execute
     * @param when {string} when to execute the function
     */
    DO.Method.prototype.register = function (sid, fn, when) {
        if (when) {
            this.after[sid] = fn;
        } else {
            this.before[sid] = fn;
        }
    };

    /**
     * Unregister a aop subscriber
     * @method delete
     * @param sid {string} the subscriber id
     * @param fn {Function} the function to execute
     * @param when {string} when to execute the function
     */
    DO.Method.prototype._delete = function (sid) {
        // Y.log('Y.Do._delete: ' + sid, 'info', 'Event');
        delete this.before[sid];
        delete this.after[sid];
    };

    /**
     * Execute the wrapped method
     * @method exec
     */
    DO.Method.prototype.exec = function () {

        var args = Y.Array(arguments, 0, true),
            i, ret, newRet,
            bf = this.before,
            af = this.after,
            prevented = false;

        // execute before
        for (i in bf) {
            if (bf.hasOwnProperty(i)) {
                ret = bf[i].apply(this.obj, args);
                if (ret) {
                    switch (ret.constructor) {
                        case DO.Halt:
                            return ret.retVal;
                        case DO.AlterArgs:
                            args = ret.newArgs;
                            break;
                        case DO.Prevent:
                            prevented = true;
                            break;
                        default:
                    }
                }
            }
        }

        // execute method
        if (!prevented) {
            ret = this.method.apply(this.obj, args);
        }

        DO.originalRetVal = ret;
        DO.currentRetVal = ret;

        // execute after methods.
        for (i in af) {
            if (af.hasOwnProperty(i)) {
                newRet = af[i].apply(this.obj, args);
                // Stop processing if a Halt object is returned
                if (newRet && newRet.constructor == DO.Halt) {
                    return newRet.retVal;
                // Check for a new return value
                } else if (newRet && newRet.constructor == DO.AlterReturn) {
                    ret = newRet.newRetVal;
                    // Update the static retval state
                    DO.currentRetVal = ret;
                }
            }
        }

        return ret;
    };

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

    /**
     * Return an AlterArgs object when you want to change the arguments that
     * were passed into the function.  An example would be a service that scrubs
     * out illegal characters prior to executing the core business logic.
     * @class Do.AlterArgs
     */
    DO.AlterArgs = function(msg, newArgs) {
        this.msg = msg;
        this.newArgs = newArgs;
    };

    /**
     * Return an AlterReturn object when you want to change the result returned
     * from the core method to the caller
     * @class Do.AlterReturn
     */
    DO.AlterReturn = function(msg, newRetVal) {
        this.msg = msg;
        this.newRetVal = newRetVal;
    };

    /**
     * Return a Halt object when you want to terminate the execution
     * of all subsequent subscribers as well as the wrapped method
     * if it has not exectued yet.
     * @class Do.Halt
     */
    DO.Halt = function(msg, retVal) {
        this.msg = msg;
        this.retVal = retVal;
    };

    /**
     * Return a Prevent object when you want to prevent the wrapped function
     * from executing, but want the remaining listeners to execute
     * @class Do.Prevent
     */
    DO.Prevent = function(msg) {
        this.msg = msg;
    };

    /**
     * Return an Error object when you want to terminate the execution
     * of all subsequent method calls.
     * @class Do.Error
     * @deprecated use Y.Do.Halt or Y.Do.Prevent
     */
    DO.Error = DO.Halt;

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

    // Y["Event"] && Y.Event.addListener(window, "unload", Y.Do._unload, Y.Do);

Copyright © 2011 Yahoo! Inc. All rights reserved.