plugin.js revision 007d778311954420082ea0ea11f663d75d6a02c9
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen DesaiYUI.add('plugin', function(Y) {
64953b0596d07dbee9a9b521ed61c434ce4709b5Satyen Desai
64953b0596d07dbee9a9b521ed61c434ce4709b5Satyen Desai/**
64953b0596d07dbee9a9b521ed61c434ce4709b5Satyen Desai * Provides the base Plugin class for building widget plugins.
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai *
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai * @module plugin
64953b0596d07dbee9a9b521ed61c434ce4709b5Satyen Desai */
e0008d92cea7515616980ad13e1075346a3bca2eSatyen Desai
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai /**
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai * Plugin provides a base class for all Plugin classes.
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai *
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @class Plugin
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai * @extends Base
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @param {Object} config The configuration object for the
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai * plugin.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai */
2b449ca06646ebb6603e35918a40bca8e0f43c8eSatyen Desai function Plugin(config) {
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai Plugin.superclass.constructor.apply(this, arguments);
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai }
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai /**
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai * Static property provides a string to identify the class.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai *
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @property Plugin.NAME
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @type {String}
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @static
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai */
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai Plugin.NAME = 'plugin';
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai /**
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * Static property provides the namespace the plugin will be
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * registered under.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai *
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @property Plugin.NS
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @type {String}
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @static
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai */
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai Plugin.NS = 'plugin';
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai var proto = {
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai _handles: null,
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai /**
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * Initializer lifecycle implementation.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai *
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @method initializer
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @param {Object} config Configuration object literal for the plugin
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai */
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai initializer : function(config) {
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai config = config || {};
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai if (config.owner) {
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai this._owner = config.owner;
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai } else {
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai }
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai this._handles = [];
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai },
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai /**
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * desctructor lifecycle implementation.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai *
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * Removes any listeners attached by the Plugin and restores
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * and over-ridden methods.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai *
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @method destructor
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai */
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai destructor: function() {
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai // remove all handles
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai if (this._handles) {
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai for (var i = 0, l = this._handles.length; i < l; i++) {
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai this._handles[i].detach();
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai }
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai }
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai },
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai /**
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * Listens for events and methods fired by the owner widget.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * The handler is called before the event handler or method is called.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @method doBefore
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @param sFn The event of method to listen for.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @param fn The handler function to call when the listener fires.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @param context An optional context to call the handler with.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * Default context is the plugin instance.
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai * @return Handle A handle that can be used to detach the handler (e.g. "handle.detach()").
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai */
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai doBefore: function(sFn, fn, context) {
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai var owner = this._owner,
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai handle;
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai context = context || this;
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai if (sFn in owner) { // method
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai handle = Y.Do.before(fn, this._owner, sFn, context);
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai } else if (owner.on) { // event
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai handle = owner.on(sFn, fn, context);
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai }
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai this._handles.push(handle);
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai return handle;
c938b255ef3c02ee132e52fbd15bb211c6f3f760Satyen Desai },
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai /**
c938b255ef3c02ee132e52fbd15bb211c6f3f760Satyen Desai * Listens for events and methods fired by the owner widget.
c938b255ef3c02ee132e52fbd15bb211c6f3f760Satyen Desai * The handler is called after the event handler or method is called.
c938b255ef3c02ee132e52fbd15bb211c6f3f760Satyen Desai * @method doAfter
c938b255ef3c02ee132e52fbd15bb211c6f3f760Satyen Desai * @param sFn The event of method to listen for.
c938b255ef3c02ee132e52fbd15bb211c6f3f760Satyen Desai * @param fn The handler function to call when the listener fires.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @param context An optional context to call the handler with.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * Default context is the plugin instance.
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai * @return Handle A handle that can be used to detach the handler (e.g. "handle.detach()").
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai */
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai doAfter: function(sFn, fn, context) {
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai var owner = this._owner,
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai handle;
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai context = context || this;
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai if (sFn in owner) { // method
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai handle = Y.Do.after(fn, this._owner, sFn, context);
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai } else if (owner.after) { // event
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai handle = owner.after(sFn, fn, context);
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai }
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai this._handles.push(handle);
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai return handle;
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai },
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai toString: function() {
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai return this.constructor.NAME + '[' + this.constructor.NS + ']';
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai }
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai };
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
969d790cf689400dd37fcf1f11c1909a66c06de9Satyen Desai Y.extend(Plugin, Y.Base, proto);
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai Y.Plugin = Plugin;
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
1201815cf554ddd27ca4898d9623926cfe3c2ac9Satyen Desai
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai}, '@VERSION@' ,{requires:['base']});
fd76c7686fc15c4633e2199dbbfd992864f245d8Satyen Desai