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             if (!this.get("host")) { Y.log('No host defined for plugin ' + this, 'warn', 'Plugin');}

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

    92         },

    93 

    94         /**

    95          * Destructor lifecycle implementation.

    96          *

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

    98          *

    99          * @method destructor

   100          */

   101         destructor: function() {

   102             // remove all handles

   103             if (this._handles) {

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

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

   106                 }

   107             }

   108         },

   109 

   110         /**

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

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

   113          *

   114          * @method doBefore

   115          *

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

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

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

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

   120          */

   121         doBefore: function(sFn, fn, context) {

   122             var host = this.get("host"),

   123                 handle;

   124 

   125             context = context || this;

   126 

   127             if (sFn in host) { // method

   128                 handle = Y.Do.before(fn, host, sFn, context);

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

   130                 handle = host.on(sFn, fn, context);

   131             }

   132 

   133             this._handles.push(handle);

   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 sFn {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 handler.

   147          */

   148         doAfter: function(sFn, fn, context) {

   149             var host = this.get("host"),

   150                 handle;

   151 

   152             context = context || this;

   153 

   154             if (sFn in host) { // method

   155                 handle = Y.Do.after(fn, host, sFn, context);

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

   157                 handle = host.after(sFn, fn, context);

   158             }

   159 

   160             this._handles.push(handle);

   161             return handle;

   162         },

   163 

   164         toString: function() {

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

   166         }

   167     });

   168 

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

   170 

   171 

   172 

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