lib/yuilib/3.13.0/pluginhost-base/pluginhost-base-debug.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('pluginhost-base', function (Y, NAME) {
   9
  10     /**
  11      * Provides the augmentable PluginHost interface, which can be added to any class.
  12      * @module pluginhost
  13      */
  14
  15     /**
  16      * Provides the augmentable PluginHost interface, which can be added to any class.
  17      * @module pluginhost-base
  18      */
  19
  20     /**
  21      * <p>
  22      * An augmentable class, which provides the augmented class with the ability to host plugins.
  23      * It adds <a href="#method_plug">plug</a> and <a href="#method_unplug">unplug</a> methods to the augmented class, which can
  24      * be used to add or remove plugins from instances of the class.
  25      * </p>
  26      *
  27      * <p>Plugins can also be added through the constructor configuration object passed to the host class' constructor using
  28      * the "plugins" property. Supported values for the "plugins" property are those defined by the <a href="#method_plug">plug</a> method.
  29      *
  30      * For example the following code would add the AnimPlugin and IOPlugin to Overlay (the plugin host):
  31      * <xmp>
  32      * var o = new Overlay({plugins: [ AnimPlugin, {fn:IOPlugin, cfg:{section:"header"}}]});
  33      * </xmp>
  34      * </p>
  35      * <p>
  36      * Plug.Host's protected <a href="#method_initPlugins">_initPlugins</a> and <a href="#method_destroyPlugins">_destroyPlugins</a>
  37      * methods should be invoked by the host class at the appropriate point in the host's lifecyle.
  38      * </p>
  39      *
  40      * @class Plugin.Host
  41      */
  42
  43     var L = Y.Lang;
  44
  45     function PluginHost() {
  46         this._plugins = {};
  47     }
  48
  49     PluginHost.prototype = {
  50
  51         /**
  52          * Adds a plugin to the host object. This will instantiate the
  53          * plugin and attach it to the configured namespace on the host object.
  54          *
  55          * @method plug
  56          * @chainable
  57          * @param P {Function | Object |Array} Accepts the plugin class, or an
  58          * object with a "fn" property specifying the plugin class and
  59          * a "cfg" property specifying the configuration for the Plugin.
  60          * <p>
  61          * Additionally an Array can also be passed in, with the above function or
  62          * object values, allowing the user to add multiple plugins in a single call.
  63          * </p>
  64          * @param config (Optional) If the first argument is the plugin class, the second argument
  65          * can be the configuration for the plugin.
  66          * @return {Base} A reference to the host object
  67          */
  68         plug: function(Plugin, config) {
  69             var i, ln, ns;
  70
  71             if (L.isArray(Plugin)) {
  72                 for (i = 0, ln = Plugin.length; i < ln; i++) {
  73                     this.plug(Plugin[i]);
  74                 }
  75             } else {
  76                 if (Plugin && !L.isFunction(Plugin)) {
  77                     config = Plugin.cfg;
  78                     Plugin = Plugin.fn;
  79                 }
  80
  81                 // Plugin should be fn by now
  82                 if (Plugin && Plugin.NS) {
  83                     ns = Plugin.NS;
  84
  85                     config = config || {};
  86                     config.host = this;
  87
  88                     if (this.hasPlugin(ns)) {
  89                         // Update config
  90                         if (this[ns].setAttrs) {
  91                             this[ns].setAttrs(config);
  92                         }
  93                         else { Y.log("Attempt to replug an already attached plugin, and we can't setAttrs, because it's not Attribute based: " + ns); }
  94                     } else {
  95                         // Create new instance
  96                         this[ns] = new Plugin(config);
  97                         this._plugins[ns] = Plugin;
  98                     }
  99                 }
 100                 else { Y.log("Attempt to plug in an invalid plugin. Host:" + this + ", Plugin:" + Plugin); }
 101             }
 102             return this;
 103         },
 104
 105         /**
 106          * Removes a plugin from the host object. This will destroy the
 107          * plugin instance and delete the namespace from the host object.
 108          *
 109          * @method unplug
 110          * @param {String | Function} plugin The namespace of the plugin, or the plugin class with the static NS namespace property defined. If not provided,
 111          * all registered plugins are unplugged.
 112          * @return {Base} A reference to the host object
 113          * @chainable
 114          */
 115         unplug: function(plugin) {
 116             var ns = plugin,
 117                 plugins = this._plugins;
 118
 119             if (plugin) {
 120                 if (L.isFunction(plugin)) {
 121                     ns = plugin.NS;
 122                     if (ns && (!plugins[ns] || plugins[ns] !== plugin)) {
 123                         ns = null;
 124                     }
 125                 }
 126
 127                 if (ns) {
 128                     if (this[ns]) {
 129                         if (this[ns].destroy) {
 130                             this[ns].destroy();
 131                         }
 132                         delete this[ns];
 133                     }
 134                     if (plugins[ns]) {
 135                         delete plugins[ns];
 136                     }
 137                 }
 138             } else {
 139                 for (ns in this._plugins) {
 140                     if (this._plugins.hasOwnProperty(ns)) {
 141                         this.unplug(ns);
 142                     }
 143                 }
 144             }
 145             return this;
 146         },
 147
 148         /**
 149          * Determines if a plugin has plugged into this host.
 150          *
 151          * @method hasPlugin
 152          * @param {String} ns The plugin's namespace
 153          * @return {Plugin} Returns a truthy value (the plugin instance) if present, or undefined if not.
 154          */
 155         hasPlugin : function(ns) {
 156             return (this._plugins[ns] && this[ns]);
 157         },
 158
 159         /**
 160          * Initializes static plugins registered on the host (using the
 161          * Base.plug static method) and any plugins passed to the
 162          * instance through the "plugins" configuration property.
 163          *
 164          * @method _initPlugins
 165          * @param {Config} config The configuration object with property name/value pairs.
 166          * @private
 167          */
 168
 169         _initPlugins: function(config) {
 170             this._plugins = this._plugins || {};
 171
 172             if (this._initConfigPlugins) {
 173                 this._initConfigPlugins(config);
 174             }
 175         },
 176
 177         /**
 178          * Unplugs and destroys all plugins on the host
 179          * @method _destroyPlugins
 180          * @private
 181          */
 182         _destroyPlugins: function() {
 183             this.unplug();
 184         }
 185     };
 186
 187     Y.namespace("Plugin").Host = PluginHost;
 188
 189
 190 }, '3.13.0', {"requires": ["yui-base"]});