jssource/src_files/include/javascript/yui3/build/pluginhost/pluginhost-base.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('pluginhost-base', function(Y) {
   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                         this[ns].setAttrs(config);
  91                     } else {
  92                         // Create new instance
  93                         this[ns] = new Plugin(config);
  94                         this._plugins[ns] = Plugin;
  95                     }
  96                 }
  97             }
  98             return this;
  99         },
 100
 101         /**
 102          * Removes a plugin from the host object. This will destroy the
 103          * plugin instance and delete the namepsace from the host object.
 104          *
 105          * @method unplug
 106          * @param {String | Function} plugin The namespace of the plugin, or the plugin class with the static NS namespace property defined. If not provided,
 107          * all registered plugins are unplugged.
 108          * @return {Base} A reference to the host object
 109          * @chainable
 110          */
 111         unplug: function(plugin) {
 112             var ns = plugin,
 113                 plugins = this._plugins;
 114
 115             if (plugin) {
 116                 if (L.isFunction(plugin)) {
 117                     ns = plugin.NS;
 118                     if (ns && (!plugins[ns] || plugins[ns] !== plugin)) {
 119                         ns = null;
 120                     }
 121                 }
 122
 123                 if (ns) {
 124                     if (this[ns]) {
 125                         this[ns].destroy();
 126                         delete this[ns];
 127                     }
 128                     if (plugins[ns]) {
 129                         delete plugins[ns];
 130                     }
 131                 }
 132             } else {
 133                 for (ns in this._plugins) {
 134                     if (this._plugins.hasOwnProperty(ns)) {
 135                         this.unplug(ns);
 136                     }
 137                 }
 138             }
 139             return this;
 140         },
 141
 142         /**
 143          * Determines if a plugin has plugged into this host.
 144          *
 145          * @method hasPlugin
 146          * @param {String} ns The plugin's namespace
 147          * @return {boolean} returns true, if the plugin has been plugged into this host, false otherwise.
 148          */
 149         hasPlugin : function(ns) {
 150             return (this._plugins[ns] && this[ns]);
 151         },
 152
 153         /**
 154          * Initializes static plugins registered on the host (using the
 155          * Base.plug static method) and any plugins passed to the
 156          * instance through the "plugins" configuration property.
 157          *
 158          * @method _initPlugins
 159          * @param {Config} config The configuration object with property name/value pairs.
 160          * @private
 161          */
 162
 163         _initPlugins: function(config) {
 164             this._plugins = this._plugins || {};
 165
 166             if (this._initConfigPlugins) {
 167                 this._initConfigPlugins(config);
 168             }
 169         },
 170
 171         /**
 172          * Unplugs and destroys all plugins on the host
 173          * @method _destroyPlugins
 174          * @private
 175          */
 176         _destroyPlugins: function() {
 177             this.unplug();
 178         }
 179     };
 180
 181     Y.namespace("Plugin").Host = PluginHost;
 182
 183
 184 }, '3.3.0' ,{requires:['yui-base']});