plugin-debug.js revision 982119a5f53b6531610b5d29c631550a6222da1f
b32d148b0052e1f874e9bc9803bef729bf859d97Luke SmithYUI.add('plugin', function(Y) {
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith /**
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith * Provides the base Plugin class, which plugin developers should extend, when creating custom plugins
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith *
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith * @module plugin
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith */
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith /**
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith * The base class for all Plugin instances.
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith *
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @class Plugin.Base
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @extends Base
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith * @param {Object} config Configuration object with property name/value pairs.
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith */
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith function Plugin(config) {
3cefe5340bfed84038e5816dbfbe7cec44f0df31Luke Smith Plugin.superclass.constructor.apply(this, arguments);
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith }
01a9f856a72f90fbb8197384630b97bb93dc7473Luke Smith
01a9f856a72f90fbb8197384630b97bb93dc7473Luke Smith /**
01a9f856a72f90fbb8197384630b97bb93dc7473Luke Smith * Object defining the set of attributes supported by the Plugin.Base class
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @property Plugin.Base.ATTRS
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @type Object
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @static
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith */
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith Plugin.ATTRS = {
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith /**
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * The plugin's host object.
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith *
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @attribute host
d463aba91a07cde67f9ec9382bce464db5bcc9d3Luke Smith * @writeonce
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @type Plugin.Host
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith */
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith host : {
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith writeOnce: true
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith }
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith };
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith /**
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * The string identifying the Plugin.Base class. Plugins extending
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * Plugin.Base should set their own NAME value.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @property Plugin.Base.NAME
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @type String
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @static
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith */
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith Plugin.NAME = 'plugin';
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith /**
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * The name of the property the the plugin will be attached to
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * when plugged into a Plugin Host. Plugins extending Plugin.Base,
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * should set their own NS value.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @property Plugin.NS
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @type String
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @static
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith */
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith Plugin.NS = 'plugin';
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith Y.extend(Plugin, Y.Base, {
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith /**
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * The list of event handles for event listeners or AOP injected methods
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * applied by the plugin to the host object.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @property _handles
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @private
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @type Array
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @value null
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith */
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith _handles: null,
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith /**
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith * Initializer lifecycle implementation.
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith *
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith * @method initializer
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith * @param {Object} config Configuration object with property name/value pairs.
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith */
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith initializer : function(config) {
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith this._handles = [];
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith if (!this.get("host")) { Y.log('No host defined for plugin ' + this, 'warn', 'Plugin');}
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith Y.log('Initializing: ' + this.constructor.NAME, 'info', 'Plugin');
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith },
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith /**
abf34f3b3d65331ec654c9980a6d60d7f9701bfeLuke Smith * Destructor lifecycle implementation.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * Removes any event listeners or injected methods applied by the Plugin
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith * @method destructor
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith */
ed51daad3a3ab15255ca10edef69d5f703d69adbLuke Smith destructor: function() {
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith // remove all handles
9327ef7ad1fee11b0e494b97cc07386565326c03Luke Smith if (this._handles) {
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith for (var i = 0, l = this._handles.length; i < l; i++) {
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith this._handles[i].detach();
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith }
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith }
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith },
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith /**
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * Listens for the "on" moment of events fired by the host,
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * or injects code "before" a given method on the host.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @method doBefore
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @param sFn {String} The event to listen for, or method to inject logic before.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @param fn {Function} The handler function. For events, the "on" moment listener. For methods, the function to execute before the given method is executed.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @return handle {EventHandle} The detach handle for the handler.
8652e2d20f8ea9c9bfe21217ba427cf0d85ada9aLuke Smith */
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith doBefore: function(sFn, fn, context) {
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith var host = this.get("host"),
8652e2d20f8ea9c9bfe21217ba427cf0d85ada9aLuke Smith handle;
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith context = context || this;
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith if (sFn in host) { // method
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith handle = Y.Do.before(fn, host, sFn, context);
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith } else if (host.on) { // event
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith handle = host.on(sFn, fn, context);
8652e2d20f8ea9c9bfe21217ba427cf0d85ada9aLuke Smith }
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith this._handles.push(handle);
8652e2d20f8ea9c9bfe21217ba427cf0d85ada9aLuke Smith return handle;
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith },
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith /**
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * Listens for the "after" moment of events fired by the host,
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * or injects code "after" a given method on the host.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith *
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @method doAfter
8652e2d20f8ea9c9bfe21217ba427cf0d85ada9aLuke Smith *
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @param sFn {String} The event to listen for, or method to inject logic after.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @param fn {Function} The handler function. For events, the "after" moment listener. For methods, the function to execute after the given method is executed.
8652e2d20f8ea9c9bfe21217ba427cf0d85ada9aLuke Smith * @param context {Object} An optional context to call the handler with. The default context is the plugin instance.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith * @return handle {EventHandle} The detach handle for the handler.
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith */
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith doAfter: function(sFn, fn, context) {
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith var host = this.get("host"),
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith handle;
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith context = context || this;
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith if (sFn in host) { // method
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith handle = Y.Do.after(fn, host, sFn, context);
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith } else if (host.after) { // event
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith handle = host.after(sFn, fn, context);
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith }
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith this._handles.push(handle);
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith return handle;
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith },
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith toString: function() {
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith return this.constructor.NAME + '[' + this.constructor.NS + ']';
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith }
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith });
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith Y.namespace("Plugin").Base = Plugin;
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith}, '@VERSION@' ,{requires:['base']});
b32d148b0052e1f874e9bc9803bef729bf859d97Luke Smith