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

   1 /*
   2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 3.0.0
   6 build: 1549
   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         Plugin.superclass.constructor.apply(this, arguments);
  25     }
  26
  27     /**
  28      * Object defining the set of attributes supported by the Plugin.Base class
  29      *
  30      * @property Plugin.Base.ATTRS
  31      * @type Object
  32      * @static
  33      */
  34     Plugin.ATTRS = {
  35
  36         /**
  37          * The plugin's host object.
  38          *
  39          * @attribute host
  40          * @writeonce
  41          * @type Plugin.Host
  42          */
  43         host : {
  44             writeOnce: true
  45         }
  46     };
  47
  48     /**
  49      * The string identifying the Plugin.Base class. Plugins extending
  50      * Plugin.Base should set their own NAME value.
  51      *
  52      * @property Plugin.Base.NAME
  53      * @type String
  54      * @static
  55      */
  56     Plugin.NAME = 'plugin';
  57
  58     /**
  59      * The name of the property the the plugin will be attached to
  60      * when plugged into a Plugin Host. Plugins extending Plugin.Base,
  61      * should set their own NS value.
  62      *
  63      * @property Plugin.NS
  64      * @type String
  65      * @static
  66      */
  67     Plugin.NS = 'plugin';
  68
  69     Y.extend(Plugin, Y.Base, {
  70
  71         /**
  72          * The list of event handles for event listeners or AOP injected methods
  73          * applied by the plugin to the host object.
  74          *
  75          * @property _handles
  76          * @private
  77          * @type Array
  78          * @value null
  79          */
  80         _handles: null,
  81
  82         /**
  83          * Initializer lifecycle implementation.
  84          *
  85          * @method initializer
  86          * @param {Object} config Configuration object with property name/value pairs.
  87          */
  88         initializer : function(config) {
  89             this._handles = [];
  90         },
  91
  92         /**
  93          * Destructor lifecycle implementation.
  94          *
  95          * Removes any event listeners or injected methods applied by the Plugin
  96          *
  97          * @method destructor
  98          */
  99         destructor: function() {
 100             // remove all handles
 101             if (this._handles) {
 102                 for (var i = 0, l = this._handles.length; i < l; i++) {
 103                    this._handles[i].detach();
 104                 }
 105             }
 106         },
 107
 108         /**
 109          * Listens for the "on" moment of events fired by the host,
 110          * or injects code "before" a given method on the host.
 111          *
 112          * @method doBefore
 113          *
 114          * @param sFn {String} The event to listen for, or method to inject logic before.
 115          * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
 116          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
 117          * @return handle {EventHandle} The detach handle for the handler.
 118          */
 119         doBefore: function(sFn, fn, context) {
 120             var host = this.get("host"),
 121                 handle;
 122
 123             context = context || this;
 124
 125             if (sFn in host) { // method
 126                 handle = Y.Do.before(fn, host, sFn, context);
 127             } else if (host.on) { // event
 128                 handle = host.on(sFn, fn, context);
 129             }
 130
 131             this._handles.push(handle);
 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 sFn {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 handler.
 145          */
 146         doAfter: function(sFn, fn, context) {
 147             var host = this.get("host"),
 148                 handle;
 149
 150             context = context || this;
 151
 152             if (sFn in host) { // method
 153                 handle = Y.Do.after(fn, host, sFn, context);
 154             } else if (host.after) { // event
 155                 handle = host.after(sFn, fn, context);
 156             }
 157
 158             this._handles.push(handle);
 159             return handle;
 160         },
 161
 162         toString: function() {
 163             return this.constructor.NAME + '[' + this.constructor.NS + ']';
 164         }
 165     });
 166
 167     Y.namespace("Plugin").Base = Plugin;
 168
 169
 170 }, '3.0.0' ,{requires:['base-base']});