jssource/src_files/include/javascript/yui3/build/plugin/plugin.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('plugin', function(Y) {
   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 Plugin.Base.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 Plugin.Base.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 Plugin.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 "after" moment of events fired by the host object.
 177          *
 178          * Listeners attached through this method will be detached when the plugin is unplugged.
 179          *
 180          * @method afterHostEvent
 181          * @param {String | Object} type The event type.
 182          * @param {Function} fn The listener.
 183          * @param {Object} context The execution context. Defaults to the plugin instance.
 184          * @return handle {EventHandle} The detach handle for the listener.
 185          */
 186         afterHostEvent : function(type, fn, context) {
 187             var handle = this.get("host").after(type, fn, context || this);
 188             this._handles.push(handle);
 189             return handle;
 190         },
 191
 192         /**
 193          * Injects a function to be executed before a given method on host object.
 194          *
 195          * The function will be detached when the plugin is unplugged.
 196          *
 197          * @method beforeHostMethod
 198          * @param {String} method The name of the method to inject the function before.
 199          * @param {Function} fn The function to inject.
 200          * @param {Object} context The execution context. Defaults to the plugin instance.
 201          * @return handle {EventHandle} The detach handle for the injected function.
 202          */
 203         beforeHostMethod : function(strMethod, fn, context) {
 204             var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);
 205             this._handles.push(handle);
 206             return handle;
 207         },
 208
 209         /**
 210          * Injects a function to be executed after a given method on host object.
 211          *
 212          * The function will be detached when the plugin is unplugged.
 213          *
 214          * @method afterHostMethod
 215          * @param {String} method The name of the method to inject the function after.
 216          * @param {Function} fn The function to inject.
 217          * @param {Object} context The execution context. Defaults to the plugin instance.
 218          * @return handle {EventHandle} The detach handle for the injected function.
 219          */
 220         afterHostMethod : function(strMethod, fn, context) {
 221             var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);
 222             this._handles.push(handle);
 223             return handle;
 224         },
 225
 226         toString: function() {
 227             return this.constructor.NAME + '[' + this.constructor.NS + ']';
 228         }
 229     });
 230
 231     Y.namespace("Plugin").Base = Plugin;
 232
 233
 234 }, '3.3.0' ,{requires:['base-base']});