API Docs for: 3.8.0
Show:

File: plugin/js/plugin.js

  1.     /**
  2.      * Provides the base Plugin class, which plugin developers should extend, when creating custom plugins
  3.      *
  4.      * @module plugin
  5.      */

  6.     /**
  7.      * The base class for all Plugin instances.
  8.      *
  9.      * @class Plugin.Base
  10.      * @extends Base
  11.      * @param {Object} config Configuration object with property name/value pairs.
  12.      */
  13.     function Plugin(config) {
  14.         if (! (this.hasImpl && this.hasImpl(Y.Plugin.Base)) ) {
  15.             Plugin.superclass.constructor.apply(this, arguments);
  16.         } else {
  17.             Plugin.prototype.initializer.apply(this, arguments);
  18.         }
  19.     }

  20.     /**
  21.      * Object defining the set of attributes supported by the Plugin.Base class
  22.      *
  23.      * @property ATTRS
  24.      * @type Object
  25.      * @static
  26.      */
  27.     Plugin.ATTRS = {

  28.         /**
  29.          * The plugin's host object.
  30.          *
  31.          * @attribute host
  32.          * @writeonce
  33.          * @type Plugin.Host
  34.          */
  35.         host : {
  36.             writeOnce: true
  37.         }
  38.     };

  39.     /**
  40.      * The string identifying the Plugin.Base class. Plugins extending
  41.      * Plugin.Base should set their own NAME value.
  42.      *
  43.      * @property NAME
  44.      * @type String
  45.      * @static
  46.      */
  47.     Plugin.NAME = 'plugin';

  48.     /**
  49.      * The name of the property the the plugin will be attached to
  50.      * when plugged into a Plugin Host. Plugins extending Plugin.Base,
  51.      * should set their own NS value.
  52.      *
  53.      * @property NS
  54.      * @type String
  55.      * @static
  56.      */
  57.     Plugin.NS = 'plugin';

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

  59.         /**
  60.          * The list of event handles for event listeners or AOP injected methods
  61.          * applied by the plugin to the host object.
  62.          *
  63.          * @property _handles
  64.          * @private
  65.          * @type Array
  66.          * @value null
  67.          */
  68.         _handles: null,

  69.         /**
  70.          * Initializer lifecycle implementation.
  71.          *
  72.          * @method initializer
  73.          * @param {Object} config Configuration object with property name/value pairs.
  74.          */
  75.         initializer : function(config) {
  76.             if (!this.get("host")) { Y.log('No host defined for plugin ' + this, 'warn', 'Plugin');}
  77.             this._handles = [];
  78.             Y.log('Initializing: ' + this.constructor.NAME, 'info', 'Plugin');
  79.         },

  80.         /**
  81.          * Destructor lifecycle implementation.
  82.          *
  83.          * Removes any event listeners or injected methods applied by the Plugin
  84.          *
  85.          * @method destructor
  86.          */
  87.         destructor: function() {
  88.             // remove all handles
  89.             if (this._handles) {
  90.                 for (var i = 0, l = this._handles.length; i < l; i++) {
  91.                    this._handles[i].detach();
  92.                 }
  93.             }
  94.         },

  95.         /**
  96.          * Listens for the "on" moment of events fired by the host,
  97.          * or injects code "before" a given method on the host.
  98.          *
  99.          * @method doBefore
  100.          *
  101.          * @param strMethod {String} The event to listen for, or method to inject logic before.
  102.          * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
  103.          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
  104.          * @return handle {EventHandle} The detach handle for the handler.
  105.          */
  106.         doBefore: function(strMethod, fn, context) {
  107.             var host = this.get("host"), handle;

  108.             if (strMethod in host) { // method
  109.                 handle = this.beforeHostMethod(strMethod, fn, context);
  110.             } else if (host.on) { // event
  111.                 handle = this.onHostEvent(strMethod, fn, context);
  112.             }

  113.             return handle;
  114.         },

  115.         /**
  116.          * Listens for the "after" moment of events fired by the host,
  117.          * or injects code "after" a given method on the host.
  118.          *
  119.          * @method doAfter
  120.          *
  121.          * @param strMethod {String} The event to listen for, or method to inject logic after.
  122.          * @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.
  123.          * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
  124.          * @return handle {EventHandle} The detach handle for the listener.
  125.          */
  126.         doAfter: function(strMethod, fn, context) {
  127.             var host = this.get("host"), handle;

  128.             if (strMethod in host) { // method
  129.                 handle = this.afterHostMethod(strMethod, fn, context);
  130.             } else if (host.after) { // event
  131.                 handle = this.afterHostEvent(strMethod, fn, context);
  132.             }

  133.             return handle;
  134.         },

  135.         /**
  136.          * Listens for the "on" moment of events fired by the host object.
  137.          *
  138.          * Listeners attached through this method will be detached when the plugin is unplugged.
  139.          *
  140.          * @method onHostEvent
  141.          * @param {String | Object} type The event type.
  142.          * @param {Function} fn The listener.
  143.          * @param {Object} context The execution context. Defaults to the plugin instance.
  144.          * @return handle {EventHandle} The detach handle for the listener.
  145.          */
  146.         onHostEvent : function(type, fn, context) {
  147.             var handle = this.get("host").on(type, fn, context || this);
  148.             this._handles.push(handle);
  149.             return handle;
  150.         },

  151.         /**
  152.          * Listens for the "after" moment of events fired by the host object.
  153.          *
  154.          * Listeners attached through this method will be detached when the plugin is unplugged.
  155.          *
  156.          * @method afterHostEvent
  157.          * @param {String | Object} type The event type.
  158.          * @param {Function} fn The listener.
  159.          * @param {Object} context The execution context. Defaults to the plugin instance.
  160.          * @return handle {EventHandle} The detach handle for the listener.
  161.          */
  162.         afterHostEvent : function(type, fn, context) {
  163.             var handle = this.get("host").after(type, fn, context || this);
  164.             this._handles.push(handle);
  165.             return handle;
  166.         },

  167.         /**
  168.          * Injects a function to be executed before a given method on host object.
  169.          *
  170.          * The function will be detached when the plugin is unplugged.
  171.          *
  172.          * @method beforeHostMethod
  173.          * @param {String} method The name of the method to inject the function before.
  174.          * @param {Function} fn The function to inject.
  175.          * @param {Object} context The execution context. Defaults to the plugin instance.
  176.          * @return handle {EventHandle} The detach handle for the injected function.
  177.          */
  178.         beforeHostMethod : function(strMethod, fn, context) {
  179.             var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);
  180.             this._handles.push(handle);
  181.             return handle;
  182.         },

  183.         /**
  184.          * Injects a function to be executed after a given method on host object.
  185.          *
  186.          * The function will be detached when the plugin is unplugged.
  187.          *
  188.          * @method afterHostMethod
  189.          * @param {String} method The name of the method to inject the function after.
  190.          * @param {Function} fn The function to inject.
  191.          * @param {Object} context The execution context. Defaults to the plugin instance.
  192.          * @return handle {EventHandle} The detach handle for the injected function.
  193.          */
  194.         afterHostMethod : function(strMethod, fn, context) {
  195.             var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);
  196.             this._handles.push(handle);
  197.             return handle;
  198.         },

  199.         toString: function() {
  200.             return this.constructor.NAME + '[' + this.constructor.NS + ']';
  201.         }
  202.     });

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

  204.