lib/yui/3.5.1/build/plugin/plugin.js

   1 /*
   2 YUI 3.5.1 (build 22)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('plugin', function(Y) {
   8
   9     /**
  10      * Provides the base Plugin class, which plugin developers should extend, when creating custom plugins
  11      *
  12      * @module plugin
  13      */
  14
  15     /**
  16      * The base class for all Plugin instances.
  17      *
  18      * @class Plugin.Base
  19      * @extends Base
  20      * @param {Object} config Configuration object with property name/value pairs.
  21      */
  22     function Plugin(config) {
  23         if (! (this.hasImpl && this.hasImpl(Y.Plugin.Base)) ) {
  24             Plugin.superclass.constructor.apply(this, arguments);
  25         } else {
  26             Plugin.prototype.initializer.apply(this, arguments);
  27         }
  28     }
  29
  30     /**
  31      * Object defining the set of attributes supported by the Plugin.Base class
  32      *
  33      * @property ATTRS
  34      * @type Object
  35      * @static
  36      */
  37     Plugin.ATTRS = {
  38
  39         /**
  40          * The plugin's host object.
  41          *
  42          * @attribute host
  43          * @writeonce
  44          * @type Plugin.Host
  45          */
  46         host : {
  47             writeOnce: true
  48         }
  49     };
  50
  51     /**
  52      * The string identifying the Plugin.Base class. Plugins extending
  53      * Plugin.Base should set their own NAME value.
  54      *
  55      * @property NAME
  56      * @type String
  57      * @static
  58      */
  59     Plugin.NAME = 'plugin';
  60
  61     /**
  62      * The name of the property the the plugin will be attached to
  63      * when plugged into a Plugin Host. Plugins extending Plugin.Base,
  64      * should set their own NS value.
  65      *
  66      * @property NS
  67      * @type String
  68      * @static
  69      */
  70     Plugin.NS = 'plugin';
  71
  72     Y.extend(Plugin, Y.Base, {
  73
  74         /**
  75          * The list of event handles for event listeners or AOP injected methods
  76          * applied by the plugin to the host object.
  77          *
  78          * @property _handles
  79          * @private
  80          * @type Array
  81          * @value null
  82          */
  83         _handles: null,
  84
  85         /**
  86          * Initializer lifecycle implementation.
  87          *
  88          * @method initializer
  89          * @param {Object} config Configuration object with property name/value pairs.
  90          */
  91         initializer : function(config) {
  92             this._handles = [];
  93         },
  94
  95         /**
  96          * Destructor lifecycle implementation.
  97          *
  98          * Removes any event listeners or injected methods applied by the Plugin
  99          *
 100          * @method destructor
 101          */
 102         destructor: function() {
 103             // remove all handles
 104             if (this._handles) {
 105                 for (var i = 0, l = this._handles.length; i < l; i++) {
 106                    this._handles[i].detach();
 107                 }
 108             }
 109         },
 110
 111         /**
 112          * Listens for the "on" moment of events fired by the host,
 113          * or injects code "before" a given method on the host.
 114          *
 115          * @method doBefore
 116          *
 117          * @param strMethod {String} The event to listen for, or method to inject logic before.
 118          * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
 119          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
 120          * @return handle {EventHandle} The detach handle for the handler.
 121          */
 122         doBefore: function(strMethod, fn, context) {
 123             var host = this.get("host"), handle;
 124
 125             if (strMethod in host) { // method
 126                 handle = this.beforeHostMethod(strMethod, fn, context);
 127             } else if (host.on) { // event
 128                 handle = this.onHostEvent(strMethod, fn, context);
 129             }
 130
 131             return handle;
 132         },
 133
 134         /**
 135          * Listens for the "after" moment of events fired by the host,
 136          * or injects code "after" a given method on the host.
 137          *
 138          * @method doAfter
 139          *
 140          * @param strMethod {String} The event to listen for, or method to inject logic after.
 141          * @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.
 142          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
 143          * @return handle {EventHandle} The detach handle for the listener.
 144          */
 145         doAfter: function(strMethod, fn, context) {
 146             var host = this.get("host"), handle;
 147
 148             if (strMethod in host) { // method
 149                 handle = this.afterHostMethod(strMethod, fn, context);
 150             } else if (host.after) { // event
 151                 handle = this.afterHostEvent(strMethod, fn, context);
 152             }
 153
 154             return handle;
 155         },
 156
 157         /**
 158          * Listens for the "on" moment of events fired by the host object.
 159          *
 160          * Listeners attached through this method will be detached when the plugin is unplugged.
 161          *
 162          * @method onHostEvent
 163          * @param {String | Object} type The event type.
 164          * @param {Function} fn The listener.
 165          * @param {Object} context The execution context. Defaults to the plugin instance.
 166          * @return handle {EventHandle} The detach handle for the listener.
 167          */
 168         onHostEvent : function(type, fn, context) {
 169             var handle = this.get("host").on(type, fn, context || this);
 170             this._handles.push(handle);
 171             return handle;
 172         },
 173
 174         /**
 175          * Listens for the "after" moment of events fired by the host object.
 176          *
 177          * Listeners attached through this method will be detached when the plugin is unplugged.
 178          *
 179          * @method afterHostEvent
 180          * @param {String | Object} type The event type.
 181          * @param {Function} fn The listener.
 182          * @param {Object} context The execution context. Defaults to the plugin instance.
 183          * @return handle {EventHandle} The detach handle for the listener.
 184          */
 185         afterHostEvent : function(type, fn, context) {
 186             var handle = this.get("host").after(type, fn, context || this);
 187             this._handles.push(handle);
 188             return handle;
 189         },
 190
 191         /**
 192          * Injects a function to be executed before a given method on host object.
 193          *
 194          * The function will be detached when the plugin is unplugged.
 195          *
 196          * @method beforeHostMethod
 197          * @param {String} method The name of the method to inject the function before.
 198          * @param {Function} fn The function to inject.
 199          * @param {Object} context The execution context. Defaults to the plugin instance.
 200          * @return handle {EventHandle} The detach handle for the injected function.
 201          */
 202         beforeHostMethod : function(strMethod, fn, context) {
 203             var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);
 204             this._handles.push(handle);
 205             return handle;
 206         },
 207
 208         /**
 209          * Injects a function to be executed after a given method on host object.
 210          *
 211          * The function will be detached when the plugin is unplugged.
 212          *
 213          * @method afterHostMethod
 214          * @param {String} method The name of the method to inject the function after.
 215          * @param {Function} fn The function to inject.
 216          * @param {Object} context The execution context. Defaults to the plugin instance.
 217          * @return handle {EventHandle} The detach handle for the injected function.
 218          */
 219         afterHostMethod : function(strMethod, fn, context) {
 220             var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);
 221             this._handles.push(handle);
 222             return handle;
 223         },
 224
 225         toString: function() {
 226             return this.constructor.NAME + '[' + this.constructor.NS + ']';
 227         }
 228     });
 229
 230     Y.namespace("Plugin").Base = Plugin;
 231
 232
 233 }, '3.5.1' ,{requires:['base-base']});