1 /*

     2 YUI 3.10.3 (build 2fb5187)

     3 Copyright 2013 Yahoo! Inc. All rights reserved.

     4 Licensed under the BSD License.

     5 http://yuilibrary.com/license/

     6 */

     7 

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

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

    94             this._handles = [];

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

    96         },

    97 

    98         /**

    99          * Destructor lifecycle implementation.

   100          *

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

   102          *

   103          * @method destructor

   104          */

   105         destructor: function() {

   106             // remove all handles

   107             if (this._handles) {

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

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

   110                 }

   111             }

   112         },

   113 

   114         /**

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

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

   117          *

   118          * @method doBefore

   119          *

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

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

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

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

   124          */

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

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

   127 

   128             if (strMethod in host) { // method

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

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

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

   132             }

   133 

   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 strMethod {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 listener.

   147          */

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

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

   150 

   151             if (strMethod in host) { // method

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

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

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

   155             }

   156 

   157             return handle;

   158         },

   159 

   160         /**

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

   162          *

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

   164          * 

   165          * @method onHostEvent

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

   167          * @param {Function} fn The listener.

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

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

   170          */

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

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

   173             this._handles.push(handle);

   174             return handle;

   175         },

   176 

   177         /**

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

   179          *

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

   181          * 

   182          * @method afterHostEvent

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

   184          * @param {Function} fn The listener.

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

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

   187          */

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

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

   190             this._handles.push(handle);

   191             return handle;

   192         },

   193 

   194         /**

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

   196          *

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

   198          *

   199          * @method beforeHostMethod

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

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

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

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

   204          */

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

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

   207             this._handles.push(handle);

   208             return handle;

   209         },

   210 

   211         /**

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

   213          *

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

   215          *

   216          * @method afterHostMethod

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

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

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

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

   221          */

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

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

   224             this._handles.push(handle);

   225             return handle;

   226         },

   227 

   228         toString: function() {

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

   230         }

   231     });

   232 

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

   234 

   235 

   236 }, '3.10.3', {"requires": ["base-base"]});