[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 {
  94                          // Create new instance
  95                          this[ns] = new Plugin(config);
  96                          this._plugins[ns] = Plugin;
  97                      }
  98                  }
  99              }
 100              return this;
 101          },
 102  
 103          /**
 104           * Removes a plugin from the host object. This will destroy the
 105           * plugin instance and delete the namespace from the host object.
 106           *
 107           * @method unplug
 108           * @param {String | Function} plugin The namespace of the plugin, or the plugin class with the static NS namespace property defined. If not provided,
 109           * all registered plugins are unplugged.
 110           * @return {Base} A reference to the host object
 111           * @chainable
 112           */
 113          unplug: function(plugin) {
 114              var ns = plugin,
 115                  plugins = this._plugins;
 116  
 117              if (plugin) {
 118                  if (L.isFunction(plugin)) {
 119                      ns = plugin.NS;
 120                      if (ns && (!plugins[ns] || plugins[ns] !== plugin)) {
 121                          ns = null;
 122                      }
 123                  }
 124  
 125                  if (ns) {
 126                      if (this[ns]) {
 127                          if (this[ns].destroy) {
 128                              this[ns].destroy();
 129                          }
 130                          delete this[ns];
 131                      }
 132                      if (plugins[ns]) {
 133                          delete plugins[ns];
 134                      }
 135                  }
 136              } else {
 137                  for (ns in this._plugins) {
 138                      if (this._plugins.hasOwnProperty(ns)) {
 139                          this.unplug(ns);
 140                      }
 141                  }
 142              }
 143              return this;
 144          },
 145  
 146          /**
 147           * Determines if a plugin has plugged into this host.
 148           *
 149           * @method hasPlugin
 150           * @param {String} ns The plugin's namespace
 151           * @return {Plugin} Returns a truthy value (the plugin instance) if present, or undefined if not.
 152           */
 153          hasPlugin : function(ns) {
 154              return (this._plugins[ns] && this[ns]);
 155          },
 156  
 157          /**
 158           * Initializes static plugins registered on the host (using the
 159           * Base.plug static method) and any plugins passed to the
 160           * instance through the "plugins" configuration property.
 161           *
 162           * @method _initPlugins
 163           * @param {Object} config The configuration object with property name/value pairs.
 164           * @private
 165           */
 166  
 167          _initPlugins: function(config) {
 168              this._plugins = this._plugins || {};
 169  
 170              if (this._initConfigPlugins) {
 171                  this._initConfigPlugins(config);
 172              }
 173          },
 174  
 175          /**
 176           * Unplugs and destroys all plugins on the host
 177           * @method _destroyPlugins
 178           * @private
 179           */
 180          _destroyPlugins: function() {
 181              this.unplug();
 182          }
 183      };
 184  
 185      Y.namespace("Plugin").Host = PluginHost;
 186  
 187  
 188  }, '3.17.2', {"requires": ["yui-base"]});