[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["base-base"]});