3 Copyright 2012 Yahoo! Inc. All rights reserved.
4 Licensed under the BSD License.
5 http://yuilibrary.com/license/
7 YUI.add('plugin', function(Y) {
10 * Provides the base Plugin class, which plugin developers should extend, when creating custom plugins
16 * The base class for all Plugin instances.
20 * @param {Object} config Configuration object with property name/value pairs.
22 function Plugin(config) {
23 if (! (this.hasImpl && this.hasImpl(Y.Plugin.Base)) ) {
24 Plugin.superclass.constructor.apply(this, arguments);
26 Plugin.prototype.initializer.apply(this, arguments);
31 * Object defining the set of attributes supported by the Plugin.Base class
40 * The plugin's host object.
52 * The string identifying the Plugin.Base class. Plugins extending
53 * Plugin.Base should set their own NAME value.
59 Plugin.NAME = 'plugin';
62 * The name of the property the the plugin will be attached to
63 * when plugged into a Plugin Host. Plugins extending Plugin.Base,
64 * should set their own NS value.
72 Y.extend(Plugin, Y.Base, {
75 * The list of event handles for event listeners or AOP injected methods
76 * applied by the plugin to the host object.
86 * Initializer lifecycle implementation.
89 * @param {Object} config Configuration object with property name/value pairs.
91 initializer : function(config) {
96 * Destructor lifecycle implementation.
98 * Removes any event listeners or injected methods applied by the Plugin
102 destructor: function() {
103 // remove all handles
105 for (var i = 0, l = this._handles.length; i < l; i++) {
106 this._handles[i].detach();
112 * Listens for the "on" moment of events fired by the host,
113 * or injects code "before" a given method on the host.
117 * @param strMethod {String} The event to listen for, or method to inject logic before.
118 * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
119 * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
120 * @return handle {EventHandle} The detach handle for the handler.
122 doBefore: function(strMethod, fn, context) {
123 var host = this.get("host"), handle;
125 if (strMethod in host) { // method
126 handle = this.beforeHostMethod(strMethod, fn, context);
127 } else if (host.on) { // event
128 handle = this.onHostEvent(strMethod, fn, context);
135 * Listens for the "after" moment of events fired by the host,
136 * or injects code "after" a given method on the host.
140 * @param strMethod {String} The event to listen for, or method to inject logic after.
141 * @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.
142 * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
143 * @return handle {EventHandle} The detach handle for the listener.
145 doAfter: function(strMethod, fn, context) {
146 var host = this.get("host"), handle;
148 if (strMethod in host) { // method
149 handle = this.afterHostMethod(strMethod, fn, context);
150 } else if (host.after) { // event
151 handle = this.afterHostEvent(strMethod, fn, context);
158 * Listens for the "on" moment of events fired by the host object.
160 * Listeners attached through this method will be detached when the plugin is unplugged.
162 * @method onHostEvent
163 * @param {String | Object} type The event type.
164 * @param {Function} fn The listener.
165 * @param {Object} context The execution context. Defaults to the plugin instance.
166 * @return handle {EventHandle} The detach handle for the listener.
168 onHostEvent : function(type, fn, context) {
169 var handle = this.get("host").on(type, fn, context || this);
170 this._handles.push(handle);
175 * Listens for the "after" moment of events fired by the host object.
177 * Listeners attached through this method will be detached when the plugin is unplugged.
179 * @method afterHostEvent
180 * @param {String | Object} type The event type.
181 * @param {Function} fn The listener.
182 * @param {Object} context The execution context. Defaults to the plugin instance.
183 * @return handle {EventHandle} The detach handle for the listener.
185 afterHostEvent : function(type, fn, context) {
186 var handle = this.get("host").after(type, fn, context || this);
187 this._handles.push(handle);
192 * Injects a function to be executed before a given method on host object.
194 * The function will be detached when the plugin is unplugged.
196 * @method beforeHostMethod
197 * @param {String} method The name of the method to inject the function before.
198 * @param {Function} fn The function to inject.
199 * @param {Object} context The execution context. Defaults to the plugin instance.
200 * @return handle {EventHandle} The detach handle for the injected function.
202 beforeHostMethod : function(strMethod, fn, context) {
203 var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);
204 this._handles.push(handle);
209 * Injects a function to be executed after a given method on host object.
211 * The function will be detached when the plugin is unplugged.
213 * @method afterHostMethod
214 * @param {String} method The name of the method to inject the function after.
215 * @param {Function} fn The function to inject.
216 * @param {Object} context The execution context. Defaults to the plugin instance.
217 * @return handle {EventHandle} The detach handle for the injected function.
219 afterHostMethod : function(strMethod, fn, context) {
220 var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);
221 this._handles.push(handle);
225 toString: function() {
226 return this.constructor.NAME + '[' + this.constructor.NS + ']';
230 Y.namespace("Plugin").Base = Plugin;
233 }, '3.5.1' ,{requires:['base-base']});