# Yahoo! UI Library

### plugin 3.3.0

Yahoo! UI Library > plugin > plugin.js (source view)
Search:
Filters Show Private Show Protected Show Deprecated

        /**
         * Provides the base Plugin class, which plugin developers should extend, when creating custom plugins
         *
         * @module plugin
         */

        /**
         * The base class for all Plugin instances.
         *
         * @class Plugin.Base
         * @extends Base
         * @param {Object} config Configuration object with property name/value pairs.
         */
        function Plugin(config) {
            if (! (this.hasImpl && this.hasImpl(Y.Plugin.Base)) ) {
                Plugin.superclass.constructor.apply(this, arguments);
            } else {
                Plugin.prototype.initializer.apply(this, arguments);
            }
        }

        /**
         * Object defining the set of attributes supported by the Plugin.Base class
         *
         * @property Plugin.Base.ATTRS
         * @type Object
         * @static
         */
        Plugin.ATTRS = {

            /**
             * The plugin's host object.
             *
             * @attribute host
             * @writeonce
             * @type Plugin.Host
             */
            host : {
                writeOnce: true
            }
        };

        /**
         * The string identifying the Plugin.Base class. Plugins extending
         * Plugin.Base should set their own NAME value.
         *
         * @property Plugin.Base.NAME
         * @type String
         * @static
         */
        Plugin.NAME = 'plugin';

        /**
         * The name of the property the the plugin will be attached to
         * when plugged into a Plugin Host. Plugins extending Plugin.Base,
         * should set their own NS value.
         *
         * @property Plugin.NS
         * @type String
         * @static
         */
        Plugin.NS = 'plugin';

        Y.extend(Plugin, Y.Base, {

            /**
             * The list of event handles for event listeners or AOP injected methods
             * applied by the plugin to the host object.
             *
             * @property _handles
             * @private
             * @type Array
             * @value null
             */
            _handles: null,

            /**
             * Initializer lifecycle implementation.
             *
             * @method initializer
             * @param {Object} config Configuration object with property name/value pairs.
             */
            initializer : function(config) {
                if (!this.get("host")) { Y.log('No host defined for plugin ' + this, 'warn', 'Plugin');}
                this._handles = [];
                Y.log('Initializing: ' + this.constructor.NAME, 'info', 'Plugin');
            },

            /**
             * Destructor lifecycle implementation.
             *
             * Removes any event listeners or injected methods applied by the Plugin
             *
             * @method destructor
             */
            destructor: function() {
                // remove all handles
                if (this._handles) {
                    for (var i = 0, l = this._handles.length; i < l; i++) {
                       this._handles[i].detach();
                    }
                }
            },

            /**
             * Listens for the "on" moment of events fired by the host,
             * or injects code "before" a given method on the host.
             *
             * @method doBefore
             *
             * @param strMethod {String} The event to listen for, or method to inject logic before.
             * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
             * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
             * @return handle {EventHandle} The detach handle for the handler.
             */
            doBefore: function(strMethod, fn, context) {
                var host = this.get("host"), handle;

                if (strMethod in host) { // method
                    handle = this.beforeHostMethod(strMethod, fn, context);
                } else if (host.on) { // event
                    handle = this.onHostEvent(strMethod, fn, context);
                }

                return handle;
            },

            /**
             * Listens for the "after" moment of events fired by the host,
             * or injects code "after" a given method on the host.
             *
             * @method doAfter
             *
             * @param strMethod {String} The event to listen for, or method to inject logic after.
             * @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.
             * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
             * @return handle {EventHandle} The detach handle for the listener.
             */
            doAfter: function(strMethod, fn, context) {
                var host = this.get("host"), handle;

                if (strMethod in host) { // method
                    handle = this.afterHostMethod(strMethod, fn, context);
                } else if (host.after) { // event
                    handle = this.afterHostEvent(strMethod, fn, context);
                }

                return handle;
            },

            /**
             * Listens for the "on" moment of events fired by the host object.
             *
             * Listeners attached through this method will be detached when the plugin is unplugged.
             *
             * @method onHostEvent
             * @param {String | Object} type The event type.
             * @param {Function} fn The listener.
             * @param {Object} context The execution context. Defaults to the plugin instance.
             * @return handle {EventHandle} The detach handle for the listener.
             */
            onHostEvent : function(type, fn, context) {
                var handle = this.get("host").on(type, fn, context || this);
                this._handles.push(handle);
                return handle;
            },

            /**
             * Listens for the "after" moment of events fired by the host object.
             *
             * Listeners attached through this method will be detached when the plugin is unplugged.
             *
             * @method afterHostEvent
             * @param {String | Object} type The event type.
             * @param {Function} fn The listener.
             * @param {Object} context The execution context. Defaults to the plugin instance.
             * @return handle {EventHandle} The detach handle for the listener.
             */
            afterHostEvent : function(type, fn, context) {
                var handle = this.get("host").after(type, fn, context || this);
                this._handles.push(handle);
                return handle;
            },

            /**
             * Injects a function to be executed before a given method on host object.
             *
             * The function will be detached when the plugin is unplugged.
             *
             * @method beforeHostMethod
             * @param {String} method The name of the method to inject the function before.
             * @param {Function} fn The function to inject.
             * @param {Object} context The execution context. Defaults to the plugin instance.
             * @return handle {EventHandle} The detach handle for the injected function.
             */
            beforeHostMethod : function(strMethod, fn, context) {
                var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);
                this._handles.push(handle);
                return handle;
            },

            /**
             * Injects a function to be executed after a given method on host object.
             *
             * The function will be detached when the plugin is unplugged.
             *
             * @method afterHostMethod
             * @param {String} method The name of the method to inject the function after.
             * @param {Function} fn The function to inject.
             * @param {Object} context The execution context. Defaults to the plugin instance.
             * @return handle {EventHandle} The detach handle for the injected function.
             */
            afterHostMethod : function(strMethod, fn, context) {
                var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);
                this._handles.push(handle);
                return handle;
            },

            toString: function() {
                return this.constructor.NAME + '[' + this.constructor.NS + ']';
            }
        });

        Y.namespace("Plugin").Base = Plugin;

Copyright © 2011 Yahoo! Inc. All rights reserved.