1 YUI.add('plugin', function (Y, NAME) {

     2 

     3     /**

     4      * Provides the base Plugin class, which plugin developers should extend, when creating custom plugins

     5      *

     6      * @module plugin

     7      */

     8 

     9     /**

    10      * The base class for all Plugin instances.

    11      *

    12      * @class Plugin.Base

    13      * @extends Base

    14      * @param {Object} config Configuration object with property name/value pairs.

    15      */

    16     function Plugin(config) {

    17         if (! (this.hasImpl && this.hasImpl(Y.Plugin.Base)) ) {

    18             Plugin.superclass.constructor.apply(this, arguments);

    19         } else {

    20             Plugin.prototype.initializer.apply(this, arguments);

    21         }

    22     }

    23 

    24     /**

    25      * Object defining the set of attributes supported by the Plugin.Base class

    26      *

    27      * @property ATTRS

    28      * @type Object

    29      * @static

    30      */

    31     Plugin.ATTRS = {

    32 

    33         /**

    34          * The plugin's host object.

    35          *

    36          * @attribute host

    37          * @writeonce

    38          * @type Plugin.Host

    39          */

    40         host : {

    41             writeOnce: true

    42         }

    43     };

    44 

    45     /**

    46      * The string identifying the Plugin.Base class. Plugins extending

    47      * Plugin.Base should set their own NAME value.

    48      *

    49      * @property NAME

    50      * @type String

    51      * @static

    52      */

    53     Plugin.NAME = 'plugin';

    54 

    55     /**

    56      * The name of the property the the plugin will be attached to

    57      * when plugged into a Plugin Host. Plugins extending Plugin.Base,

    58      * should set their own NS value.

    59      *

    60      * @property NS

    61      * @type String

    62      * @static

    63      */

    64     Plugin.NS = 'plugin';

    65 

    66     Y.extend(Plugin, Y.Base, {

    67 

    68         /**

    69          * The list of event handles for event listeners or AOP injected methods

    70          * applied by the plugin to the host object.

    71          *

    72          * @property _handles

    73          * @private

    74          * @type Array

    75          * @value null

    76          */

    77         _handles: null,

    78 

    79         /**

    80          * Initializer lifecycle implementation.

    81          *

    82          * @method initializer

    83          * @param {Object} config Configuration object with property name/value pairs.

    84          */

    85         initializer : function(config) {

    86             if (!this.get("host")) { Y.log('No host defined for plugin ' + this, 'warn', 'Plugin');}

    87             this._handles = [];

    88             Y.log('Initializing: ' + this.constructor.NAME, 'info', 'Plugin');

    89         },

    90 

    91         /**

    92          * Destructor lifecycle implementation.

    93          *

    94          * Removes any event listeners or injected methods applied by the Plugin

    95          *

    96          * @method destructor

    97          */

    98         destructor: function() {

    99             // remove all handles

   100             if (this._handles) {

   101                 for (var i = 0, l = this._handles.length; i < l; i++) {

   102                    this._handles[i].detach();

   103                 }

   104             }

   105         },

   106 

   107         /**

   108          * Listens for the "on" moment of events fired by the host,

   109          * or injects code "before" a given method on the host.

   110          *

   111          * @method doBefore

   112          *

   113          * @param strMethod {String} The event to listen for, or method to inject logic before.

   114          * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.

   115          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.

   116          * @return handle {EventHandle} The detach handle for the handler.

   117          */

   118         doBefore: function(strMethod, fn, context) {

   119             var host = this.get("host"), handle;

   120 

   121             if (strMethod in host) { // method

   122                 handle = this.beforeHostMethod(strMethod, fn, context);

   123             } else if (host.on) { // event

   124                 handle = this.onHostEvent(strMethod, fn, context);

   125             }

   126 

   127             return handle;

   128         },

   129 

   130         /**

   131          * Listens for the "after" moment of events fired by the host,

   132          * or injects code "after" a given method on the host.

   133          *

   134          * @method doAfter

   135          *

   136          * @param strMethod {String} The event to listen for, or method to inject logic after.

   137          * @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.

   138          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.

   139          * @return handle {EventHandle} The detach handle for the listener.

   140          */

   141         doAfter: function(strMethod, fn, context) {

   142             var host = this.get("host"), handle;

   143 

   144             if (strMethod in host) { // method

   145                 handle = this.afterHostMethod(strMethod, fn, context);

   146             } else if (host.after) { // event

   147                 handle = this.afterHostEvent(strMethod, fn, context);

   148             }

   149 

   150             return handle;

   151         },

   152 

   153         /**

   154          * Listens for the "on" moment of events fired by the host object.

   155          *

   156          * Listeners attached through this method will be detached when the plugin is unplugged.

   157          *

   158          * @method onHostEvent

   159          * @param {String | Object} type The event type.

   160          * @param {Function} fn The listener.

   161          * @param {Object} context The execution context. Defaults to the plugin instance.

   162          * @return handle {EventHandle} The detach handle for the listener.

   163          */

   164         onHostEvent : function(type, fn, context) {

   165             var handle = this.get("host").on(type, fn, context || this);

   166             this._handles.push(handle);

   167             return handle;

   168         },

   169 

   170         /**

   171          * Listens for the "on" moment of events fired by the host object one time only.

   172          * The listener is immediately detached when it is executed.

   173          *

   174          * Listeners attached through this method will be detached when the plugin is unplugged.

   175          *

   176          * @method onceHostEvent

   177          * @param {String | Object} type The event type.

   178          * @param {Function} fn The listener.

   179          * @param {Object} context The execution context. Defaults to the plugin instance.

   180          * @return handle {EventHandle} The detach handle for the listener.

   181          */

   182         onceHostEvent : function(type, fn, context) {

   183             var handle = this.get("host").once(type, fn, context || this);

   184             this._handles.push(handle);

   185             return handle;

   186         },

   187 

   188         /**

   189          * Listens for the "after" moment of events fired by the host object.

   190          *

   191          * Listeners attached through this method will be detached when the plugin is unplugged.

   192          *

   193          * @method afterHostEvent

   194          * @param {String | Object} type The event type.

   195          * @param {Function} fn The listener.

   196          * @param {Object} context The execution context. Defaults to the plugin instance.

   197          * @return handle {EventHandle} The detach handle for the listener.

   198          */

   199         afterHostEvent : function(type, fn, context) {

   200             var handle = this.get("host").after(type, fn, context || this);

   201             this._handles.push(handle);

   202             return handle;

   203         },

   204 

   205         /**

   206          * Listens for the "after" moment of events fired by the host object one time only.

   207          * The listener is immediately detached when it is executed.

   208          *

   209          * Listeners attached through this method will be detached when the plugin is unplugged.

   210          *

   211          * @method onceAfterHostEvent

   212          * @param {String | Object} type The event type.

   213          * @param {Function} fn The listener.

   214          * @param {Object} context The execution context. Defaults to the plugin instance.

   215          * @return handle {EventHandle} The detach handle for the listener.

   216          */

   217         onceAfterHostEvent : function(type, fn, context) {

   218             var handle = this.get("host").onceAfter(type, fn, context || this);

   219             this._handles.push(handle);

   220             return handle;

   221         },

   222 

   223         /**

   224          * Injects a function to be executed before a given method on host object.

   225          *

   226          * The function will be detached when the plugin is unplugged.

   227          *

   228          * @method beforeHostMethod

   229          * @param {String} method The name of the method to inject the function before.

   230          * @param {Function} fn The function to inject.

   231          * @param {Object} context The execution context. Defaults to the plugin instance.

   232          * @return handle {EventHandle} The detach handle for the injected function.

   233          */

   234         beforeHostMethod : function(strMethod, fn, context) {

   235             var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);

   236             this._handles.push(handle);

   237             return handle;

   238         },

   239 

   240         /**

   241          * Injects a function to be executed after a given method on host object.

   242          *

   243          * The function will be detached when the plugin is unplugged.

   244          *

   245          * @method afterHostMethod

   246          * @param {String} method The name of the method to inject the function after.

   247          * @param {Function} fn The function to inject.

   248          * @param {Object} context The execution context. Defaults to the plugin instance.

   249          * @return handle {EventHandle} The detach handle for the injected function.

   250          */

   251         afterHostMethod : function(strMethod, fn, context) {

   252             var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);

   253             this._handles.push(handle);

   254             return handle;

   255         },

   256 

   257         toString: function() {

   258             return this.constructor.NAME + '[' + this.constructor.NS + ']';

   259         }

   260     });

   261 

   262     Y.namespace("Plugin").Base = Plugin;

   263 

   264 

   265 }, '@VERSION@', {"requires": ["base-base"]});