lib/yuilib/3.13.0/plugin/plugin.js

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