lib/yuilib/3.13.0/pluginhost-base/pluginhost-base.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 {
  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 {Config} 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.13.0', {"requires": ["yui-base"]});