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.0b1

     6 build: 1163

     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 

   171 }, '3.0.0b1' ,{requires:['base']});