jssource/src_files/include/javascript/yui3/build/pluginhost/pluginhost.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']});
 185 YUI.add('pluginhost-config', function(Y) {
 186
 187     /**
 188      * Adds pluginhost constructor configuration and static configuration support
 189      * @submodule pluginhost-config
 190      */
 191
 192     /**
 193      * Constructor and static configuration support for plugins
 194      *
 195      * @for Plugin.Host
 196      */
 197     var PluginHost = Y.Plugin.Host,
 198         L = Y.Lang;
 199
 200     PluginHost.prototype._initConfigPlugins = function(config) {
 201
 202         // Class Configuration
 203         var classes = (this._getClasses) ? this._getClasses() : [this.constructor],
 204             plug = [],
 205             unplug = {},
 206             constructor, i, classPlug, classUnplug, pluginClassName;
 207
 208         // TODO: Room for optimization. Can we apply statically/unplug in same pass?
 209         for (i = classes.length - 1; i >= 0; i--) {
 210             constructor = classes[i];
 211
 212             classUnplug = constructor._UNPLUG;
 213             if (classUnplug) {
 214                 // subclasses over-write
 215                 Y.mix(unplug, classUnplug, true);
 216             }
 217
 218             classPlug = constructor._PLUG;
 219             if (classPlug) {
 220                 // subclasses over-write
 221                 Y.mix(plug, classPlug, true);
 222             }
 223         }
 224
 225         for (pluginClassName in plug) {
 226             if (plug.hasOwnProperty(pluginClassName)) {
 227                 if (!unplug[pluginClassName]) {
 228                     this.plug(plug[pluginClassName]);
 229                 }
 230             }
 231         }
 232
 233         // User Configuration
 234         if (config && config.plugins) {
 235             this.plug(config.plugins);
 236         }
 237     };
 238
 239     /**
 240      * Registers plugins to be instantiated at the class level (plugins
 241      * which should be plugged into every instance of the class by default).
 242      *
 243      * @method Plugin.Host.plug
 244      * @static
 245      *
 246      * @param {Function} hostClass The host class on which to register the plugins
 247      * @param {Function | Array} plugin Either the plugin class, an array of plugin classes or an array of objects (with fn and cfg properties defined)
 248      * @param {Object} config (Optional) If plugin is the plugin class, the configuration for the plugin
 249      */
 250     PluginHost.plug = function(hostClass, plugin, config) {
 251         // Cannot plug into Base, since Plugins derive from Base [ will cause infinite recurrsion ]
 252         var p, i, l, name;
 253
 254         if (hostClass !== Y.Base) {
 255             hostClass._PLUG = hostClass._PLUG || {};
 256
 257             if (!L.isArray(plugin)) {
 258                 if (config) {
 259                     plugin = {fn:plugin, cfg:config};
 260                 }
 261                 plugin = [plugin];
 262             }
 263
 264             for (i = 0, l = plugin.length; i < l;i++) {
 265                 p = plugin[i];
 266                 name = p.NAME || p.fn.NAME;
 267                 hostClass._PLUG[name] = p;
 268             }
 269         }
 270     };
 271
 272     /**
 273      * Unregisters any class level plugins which have been registered by the host class, or any
 274      * other class in the hierarchy.
 275      *
 276      * @method Plugin.Host.unplug
 277      * @static
 278      *
 279      * @param {Function} hostClass The host class from which to unregister the plugins
 280      * @param {Function | Array} plugin The plugin class, or an array of plugin classes
 281      */
 282     PluginHost.unplug = function(hostClass, plugin) {
 283         var p, i, l, name;
 284
 285         if (hostClass !== Y.Base) {
 286             hostClass._UNPLUG = hostClass._UNPLUG || {};
 287
 288             if (!L.isArray(plugin)) {
 289                 plugin = [plugin];
 290             }
 291
 292             for (i = 0, l = plugin.length; i < l; i++) {
 293                 p = plugin[i];
 294                 name = p.NAME;
 295                 if (!hostClass._PLUG[name]) {
 296                     hostClass._UNPLUG[name] = p;
 297                 } else {
 298                     delete hostClass._PLUG[name];
 299                 }
 300             }
 301         }
 302     };
 303
 304
 305 }, '3.3.0' ,{requires:['pluginhost-base']});
 306
 307
 308 YUI.add('pluginhost', function(Y){}, '3.3.0' ,{use:['pluginhost-base', 'pluginhost-config']});
 309