lib/yuilib/3.13.0/plugin/plugin-debug.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             if (!this.get("host")) { Y.log('No host defined for plugin ' + this, 'warn', 'Plugin');}
  94             this._handles = [];
  95             Y.log('Initializing: ' + this.constructor.NAME, 'info', 'Plugin');
  96         },
  97
  98         /**
  99          * Destructor lifecycle implementation.
 100          *
 101          * Removes any event listeners or injected methods applied by the Plugin
 102          *
 103          * @method destructor
 104          */
 105         destructor: function() {
 106             // remove all handles
 107             if (this._handles) {
 108                 for (var i = 0, l = this._handles.length; i < l; i++) {
 109                    this._handles[i].detach();
 110                 }
 111             }
 112         },
 113
 114         /**
 115          * Listens for the "on" moment of events fired by the host,
 116          * or injects code "before" a given method on the host.
 117          *
 118          * @method doBefore
 119          *
 120          * @param strMethod {String} The event to listen for, or method to inject logic before.
 121          * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
 122          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
 123          * @return handle {EventHandle} The detach handle for the handler.
 124          */
 125         doBefore: function(strMethod, fn, context) {
 126             var host = this.get("host"), handle;
 127
 128             if (strMethod in host) { // method
 129                 handle = this.beforeHostMethod(strMethod, fn, context);
 130             } else if (host.on) { // event
 131                 handle = this.onHostEvent(strMethod, fn, context);
 132             }
 133
 134             return handle;
 135         },
 136
 137         /**
 138          * Listens for the "after" moment of events fired by the host,
 139          * or injects code "after" a given method on the host.
 140          *
 141          * @method doAfter
 142          *
 143          * @param strMethod {String} The event to listen for, or method to inject logic after.
 144          * @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.
 145          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
 146          * @return handle {EventHandle} The detach handle for the listener.
 147          */
 148         doAfter: function(strMethod, fn, context) {
 149             var host = this.get("host"), handle;
 150
 151             if (strMethod in host) { // method
 152                 handle = this.afterHostMethod(strMethod, fn, context);
 153             } else if (host.after) { // event
 154                 handle = this.afterHostEvent(strMethod, fn, context);
 155             }
 156
 157             return handle;
 158         },
 159
 160         /**
 161          * Listens for the "on" moment of events fired by the host object.
 162          *
 163          * Listeners attached through this method will be detached when the plugin is unplugged.
 164          *
 165          * @method onHostEvent
 166          * @param {String | Object} type The event type.
 167          * @param {Function} fn The listener.
 168          * @param {Object} context The execution context. Defaults to the plugin instance.
 169          * @return handle {EventHandle} The detach handle for the listener.
 170          */
 171         onHostEvent : function(type, fn, context) {
 172             var handle = this.get("host").on(type, fn, context || this);
 173             this._handles.push(handle);
 174             return handle;
 175         },
 176
 177         /**
 178          * Listens for the "on" moment of events fired by the host object one time only.
 179          * The listener is immediately detached when it is executed.
 180          *
 181          * Listeners attached through this method will be detached when the plugin is unplugged.
 182          *
 183          * @method onceHostEvent
 184          * @param {String | Object} type The event type.
 185          * @param {Function} fn The listener.
 186          * @param {Object} context The execution context. Defaults to the plugin instance.
 187          * @return handle {EventHandle} The detach handle for the listener.
 188          */
 189         onceHostEvent : function(type, fn, context) {
 190             var handle = this.get("host").once(type, fn, context || this);
 191             this._handles.push(handle);
 192             return handle;
 193         },
 194
 195         /**
 196          * Listens for the "after" moment of events fired by the host object.
 197          *
 198          * Listeners attached through this method will be detached when the plugin is unplugged.
 199          *
 200          * @method afterHostEvent
 201          * @param {String | Object} type The event type.
 202          * @param {Function} fn The listener.
 203          * @param {Object} context The execution context. Defaults to the plugin instance.
 204          * @return handle {EventHandle} The detach handle for the listener.
 205          */
 206         afterHostEvent : function(type, fn, context) {
 207             var handle = this.get("host").after(type, fn, context || this);
 208             this._handles.push(handle);
 209             return handle;
 210         },
 211
 212         /**
 213          * Listens for the "after" moment of events fired by the host object one time only.
 214          * The listener is immediately detached when it is executed.
 215          *
 216          * Listeners attached through this method will be detached when the plugin is unplugged.
 217          *
 218          * @method onceAfterHostEvent
 219          * @param {String | Object} type The event type.
 220          * @param {Function} fn The listener.
 221          * @param {Object} context The execution context. Defaults to the plugin instance.
 222          * @return handle {EventHandle} The detach handle for the listener.
 223          */
 224         onceAfterHostEvent : function(type, fn, context) {
 225             var handle = this.get("host").onceAfter(type, fn, context || this);
 226             this._handles.push(handle);
 227             return handle;
 228         },
 229
 230         /**
 231          * Injects a function to be executed before a given method on host object.
 232          *
 233          * The function will be detached when the plugin is unplugged.
 234          *
 235          * @method beforeHostMethod
 236          * @param {String} method The name of the method to inject the function before.
 237          * @param {Function} fn The function to inject.
 238          * @param {Object} context The execution context. Defaults to the plugin instance.
 239          * @return handle {EventHandle} The detach handle for the injected function.
 240          */
 241         beforeHostMethod : function(strMethod, fn, context) {
 242             var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);
 243             this._handles.push(handle);
 244             return handle;
 245         },
 246
 247         /**
 248          * Injects a function to be executed after a given method on host object.
 249          *
 250          * The function will be detached when the plugin is unplugged.
 251          *
 252          * @method afterHostMethod
 253          * @param {String} method The name of the method to inject the function after.
 254          * @param {Function} fn The function to inject.
 255          * @param {Object} context The execution context. Defaults to the plugin instance.
 256          * @return handle {EventHandle} The detach handle for the injected function.
 257          */
 258         afterHostMethod : function(strMethod, fn, context) {
 259             var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);
 260             this._handles.push(handle);
 261             return handle;
 262         },
 263
 264         toString: function() {
 265             return this.constructor.NAME + '[' + this.constructor.NS + ']';
 266         }
 267     });
 268
 269     Y.namespace("Plugin").Base = Plugin;
 270
 271
 272 }, '3.13.0', {"requires": ["base-base"]});