File yui3/src/plugin/js/plugin.js
/**
* Provides the base Plugin class, which plugin developers should extend, when creating custom plugins
*
* @module plugin
*/
/**
* The base class for all Plugin instances.
*
* @class Plugin.Base
* @extends Base
* @param {Object} config Configuration object with property name/value pairs.
*/
function Plugin(config) {
if (! (this.hasImpl && this.hasImpl(Y.Plugin.Base)) ) {
Plugin.superclass.constructor.apply(this, arguments);
} else {
Plugin.prototype.initializer.apply(this, arguments);
}
}
/**
* Object defining the set of attributes supported by the Plugin.Base class
*
* @property ATTRS
* @type Object
* @static
*/
Plugin.ATTRS = {
/**
* The plugin's host object.
*
* @attribute host
* @writeonce
* @type Plugin.Host
*/
host : {
writeOnce: true
}
};
/**
* The string identifying the Plugin.Base class. Plugins extending
* Plugin.Base should set their own NAME value.
*
* @property NAME
* @type String
* @static
*/
Plugin.NAME = 'plugin';
/**
* The name of the property the the plugin will be attached to
* when plugged into a Plugin Host. Plugins extending Plugin.Base,
* should set their own NS value.
*
* @property NS
* @type String
* @static
*/
Plugin.NS = 'plugin';
Y.extend(Plugin, Y.Base, {
/**
* The list of event handles for event listeners or AOP injected methods
* applied by the plugin to the host object.
*
* @property _handles
* @private
* @type Array
* @value null
*/
_handles: null,
/**
* Initializer lifecycle implementation.
*
* @method initializer
* @param {Object} config Configuration object with property name/value pairs.
*/
initializer : function(config) {
if (!this.get("host")) { Y.log('No host defined for plugin ' + this, 'warn', 'Plugin');}
this._handles = [];
Y.log('Initializing: ' + this.constructor.NAME, 'info', 'Plugin');
},
/**
* Destructor lifecycle implementation.
*
* Removes any event listeners or injected methods applied by the Plugin
*
* @method destructor
*/
destructor: function() {
// remove all handles
if (this._handles) {
for (var i = 0, l = this._handles.length; i < l; i++) {
this._handles[i].detach();
}
}
},
/**
* Listens for the "on" moment of events fired by the host,
* or injects code "before" a given method on the host.
*
* @method doBefore
*
* @param strMethod {String} The event to listen for, or method to inject logic before.
* @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
* @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
* @return handle {EventHandle} The detach handle for the handler.
*/
doBefore: function(strMethod, fn, context) {
var host = this.get("host"), handle;
if (strMethod in host) { // method
handle = this.beforeHostMethod(strMethod, fn, context);
} else if (host.on) { // event
handle = this.onHostEvent(strMethod, fn, context);
}
return handle;
},
/**
* Listens for the "after" moment of events fired by the host,
* or injects code "after" a given method on the host.
*
* @method doAfter
*
* @param strMethod {String} The event to listen for, or method to inject logic after.
* @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.
* @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
* @return handle {EventHandle} The detach handle for the listener.
*/
doAfter: function(strMethod, fn, context) {
var host = this.get("host"), handle;
if (strMethod in host) { // method
handle = this.afterHostMethod(strMethod, fn, context);
} else if (host.after) { // event
handle = this.afterHostEvent(strMethod, fn, context);
}
return handle;
},
/**
* Listens for the "on" moment of events fired by the host object.
*
* Listeners attached through this method will be detached when the plugin is unplugged.
*
* @method onHostEvent
* @param {String | Object} type The event type.
* @param {Function} fn The listener.
* @param {Object} context The execution context. Defaults to the plugin instance.
* @return handle {EventHandle} The detach handle for the listener.
*/
onHostEvent : function(type, fn, context) {
var handle = this.get("host").on(type, fn, context || this);
this._handles.push(handle);
return handle;
},
/**
* Listens for the "on" moment of events fired by the host object one time only.
* The listener is immediately detached when it is executed.
*
* Listeners attached through this method will be detached when the plugin is unplugged.
*
* @method onceHostEvent
* @param {String | Object} type The event type.
* @param {Function} fn The listener.
* @param {Object} context The execution context. Defaults to the plugin instance.
* @return handle {EventHandle} The detach handle for the listener.
*/
onceHostEvent : function(type, fn, context) {
var handle = this.get("host").once(type, fn, context || this);
this._handles.push(handle);
return handle;
},
/**
* Listens for the "after" moment of events fired by the host object.
*
* Listeners attached through this method will be detached when the plugin is unplugged.
*
* @method afterHostEvent
* @param {String | Object} type The event type.
* @param {Function} fn The listener.
* @param {Object} context The execution context. Defaults to the plugin instance.
* @return handle {EventHandle} The detach handle for the listener.
*/
afterHostEvent : function(type, fn, context) {
var handle = this.get("host").after(type, fn, context || this);
this._handles.push(handle);
return handle;
},
/**
* Listens for the "after" moment of events fired by the host object one time only.
* The listener is immediately detached when it is executed.
*
* Listeners attached through this method will be detached when the plugin is unplugged.
*
* @method onceAfterHostEvent
* @param {String | Object} type The event type.
* @param {Function} fn The listener.
* @param {Object} context The execution context. Defaults to the plugin instance.
* @return handle {EventHandle} The detach handle for the listener.
*/
onceAfterHostEvent : function(type, fn, context) {
var handle = this.get("host").onceAfter(type, fn, context || this);
this._handles.push(handle);
return handle;
},
/**
* Injects a function to be executed before a given method on host object.
*
* The function will be detached when the plugin is unplugged.
*
* @method beforeHostMethod
* @param {String} method The name of the method to inject the function before.
* @param {Function} fn The function to inject.
* @param {Object} context The execution context. Defaults to the plugin instance.
* @return handle {EventHandle} The detach handle for the injected function.
*/
beforeHostMethod : function(strMethod, fn, context) {
var handle = Y.Do.before(fn, this.get("host"), strMethod, context || this);
this._handles.push(handle);
return handle;
},
/**
* Injects a function to be executed after a given method on host object.
*
* The function will be detached when the plugin is unplugged.
*
* @method afterHostMethod
* @param {String} method The name of the method to inject the function after.
* @param {Function} fn The function to inject.
* @param {Object} context The execution context. Defaults to the plugin instance.
* @return handle {EventHandle} The detach handle for the injected function.
*/
afterHostMethod : function(strMethod, fn, context) {
var handle = Y.Do.after(fn, this.get("host"), strMethod, context || this);
this._handles.push(handle);
return handle;
},
toString: function() {
return this.constructor.NAME + '[' + this.constructor.NS + ']';
}
});
Y.namespace("Plugin").Base = Plugin;