[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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 {Object} 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.17.2', {"requires": ["yui-base"]});