|
1 /* |
|
2 YUI 3.10.3 (build 2fb5187) |
|
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 { 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 {Config} 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.10.3', {"requires": ["yui-base"]}); |