/* Copyright (c) 2010, Yahoo! Inc. All rights reserved. Code licensed under the BSD License: http://developer.yahoo.com/yui/license.html version: 3.4.0 build: nightly */ YUI.add('plugin', function(Y) { /** * 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) { this._handles = []; }, /** * 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 "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; }, /** * 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; }, '3.4.0' ,{requires:['base-base']});