Author: pyaschenko Date: 2010-03-25 12:02:42 -0400 (Thu, 25 Mar 2010) New Revision: 16668 Modified: root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-base-component.js root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-event.js Log: jsdocs was added to BaseComponent and Event API RF-8517 Modified: root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-base-component.js =================================================================== --- root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-base-component.js 2010-03-25 14:13:23 UTC (rev 16667) +++ root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-base-component.js 2010-03-25 16:02:42 UTC (rev 16668) @@ -1,11 +1,32 @@ -(function (jQuery, richfaces, params) { +/** + * @author Pavel Yaschenko + */ + + +(function ($, richfaces, params) { richfaces.blankFunction = function (){}; //TODO: add it to global library + /** + * @class Base class for all components + * @name BaseComponent + * + * @constructor + * @param {String} componentId - component id + * */ richfaces.BaseComponent = function(componentId) { this.id = componentId; }; + /** + * Method extends child class prototype with parent prototype + * and return parent's prototype ($super) + * + * @methodOf + * @name BaseComponent.extend + * + * @return {object} + * */ richfaces.BaseComponent.extend = function (Parent, Child) { var F = richfaces.blankFunction; F.prototype = Parent.prototype; @@ -15,9 +36,24 @@ return Parent.prototype; } - jQuery.extend(richfaces.BaseComponent.prototype, (function (params) { + $.extend(richfaces.BaseComponent.prototype, (function (params) { return { + /** + * Component name. + * + * @name BaseComponent#name + * @type String + * */ name: "BaseComponent", + + /** + * Method for converting object to string + * + * @methodOf + * @name BaseComponent#toString + * + * @return {String} + * */ toString: function() { var result = []; if (this.constructor.$super) { @@ -26,6 +62,15 @@ result[result.length] = this.name; return result.join(', '); }, + + /** + * Method returns enement's id as jQuery selector + * + * @methodOf + * @name BaseComponent#getEventElement + * + * @return {String} + * */ getEventElement: function() { return "#"+this.id; } @@ -33,6 +78,8 @@ })(params)); })(jQuery, window.RichFaces || (window.RichFaces={})); + + /* (function (jQuery, richfaces, params) { Modified: root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-event.js =================================================================== --- root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-event.js 2010-03-25 14:13:23 UTC (rev 16667) +++ root/framework/trunk/impl/src/main/resources/META-INF/resources/richfaces-event.js 2010-03-25 16:02:42 UTC (rev 16668) @@ -1,4 +1,13 @@ +/** + * @author Pavel Yaschenko + */ + (function($, richfaces) { + + /** + * @class + * @name Event + * */ richfaces.Event = richfaces.Event || {}; var getEventElement = function (selector) { @@ -16,7 +25,21 @@ } $.extend(richfaces.Event, { + /** + * @constant + * @name Event.RICH_NAMESPACE + * @type string + * */ RICH_NAMESPACE : "RICH:", + + /** + * Attach an event handler to execute when the DOM is fully loaded + * @methodOf + * @name Event.ready + * + * @param {function} fn - event handler + * @return {jQuery} document element wrapped by jQuery + * */ ready : function(fn) { // TODO: not completed yet return $(document).ready(fn); @@ -26,6 +49,19 @@ } */ }, + + /** + * Attach a handler to an event for the elements + * @methodOf + * @name Event.bind + * + * @param {string|DOMElement|jQuery} selector - jQuery elements selector + * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names + * @param {function} fn - event handler + * @param {Object} [data] - component or object with additional data + * It is a context for an event handler + * @return {function} function that binded to the element's event + * */ bind : function(selector, type, fn, data) { // type: namespace can be used, like onclick.rf.conponentName var f = function (e,d){ @@ -34,6 +70,19 @@ getEventElement(selector).bind(type, {component: data, fn:fn}, f); return f; }, + + /** + * Attach a handler to an event for the element by element id + * @methodOf + * @name Event.bindById + * + * @param {string} id - DOM element id + * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names + * @param {function} fn - event handler + * @param {Object} [data] - component or object with additional data + * It is a context for an event handler + * @return {function} function that binded to the element's event + * */ bindById : function(id, type, fn, data) { // type: namespace can be used, like onclick.rf.conponentName var f = function (e,d){ @@ -41,7 +90,21 @@ }; $(document.getElementById(id)).bind(type, {component: data, fn:fn}, f); return f; - }, + }, + + /** + * Attach a handler to an event for the elements + * The handler will be called only once when event happened + * @methodOf + * @name Event.bindOne + * + * @param {string|DOMElement|jQuery} selector - jQuery elements selector + * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names + * @param {function} fn - event handler + * @param {Object} [data] - component or object with additional data + * It is a context for an event handler + * @return {function} function that binded to the element's event + * */ bindOne: function(selector, type, fn, data) { // type: namespace can be used, like onclick.rf.conponentName var f = function (e,d){ @@ -50,6 +113,20 @@ getEventElement(selector).one(type, {component: data, fn:fn}, f); return f; }, + + /** + * Attach a handler to an event for the element by element id + * The handler will be called only once when event happened + * @methodOf + * @name Event.bindOneById + * + * @param {string} id - DOM element id + * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names + * @param {function} fn - event handler + * @param {Object} [data] - component or object with additional data + * It is a context for an event handler + * @return {function} function that binded to the element's event + * */ bindOneById: function(id, type, fn, data) { // type: namespace can be used, like onclick.rf.conponentName var f = function (e,d){ @@ -57,27 +134,109 @@ }; $(document.getElementById(id)).one(type, {component: data, fn:fn}, f); return f; - }, + }, + + /** + * Remove a previously-attached event handler from the elements + * @methodOf + * @name Event.unbind + * + * @param {string|DOMElement|jQuery} selector - jQuery elements selector + * @param {string} [type] - one or more JavaScript event types, such as "click" or "submit," or custom event names + * @param {function} [fn] - event handler + * @return {jQuery} element wrapped by jQuery + * */ unbind : function(selector, type, fn) { // type: namespace can be used, like onclick.rf.conponentName return getEventElement(selector).unbind(type, fn); - }, + }, + + /** + * Remove a previously-attached event handler from the elements by element id + * The handler will be called only once when event happened + * @methodOf + * @name Event.unbindById + * + * @param {string} id - DOM element id + * @param {string} [type] - one or more JavaScript event types, such as "click" or "submit," or custom event names + * @param {function} [fn] - event handler + * @return {jQuery} element wrapped by jQuery + * */ unbindById : function(id, type, fn) { // type: namespace can be used, like onclick.rf.conponentName return $(document.getElementById(id)).unbind(type, fn); - }, + }, + + /** + * Execute all handlers and behaviors attached to the matched elements for the given event type + * @methodOf + * @name Event.fire + * + * @param {string|DOMElement|jQuery} selector - jQuery elements selector + * @param {string} event - event name + * @param {Object} [data] - a object of additional parameters to pass to the event handler + * @return {jQuery} element wrapped by jQuery + * */ fire : function(selector, event, data) { return getEventElement(selector).trigger(event, data); }, + + /** + * The same as the fire method, but selects element by id + * @methodOf + * @name Event.fireById + * + * @param {string} id - DOM element id + * @param {string} event - event name + * @param {Object} [data] - a object of additional parameters to pass to the event handler + * @return {jQuery} element wrapped by jQuery + * */ fireById : function(id, event, data) { return $(document.getElementById(id)).trigger(event, data); - }, + }, + + /** + * The same as the fire method, but: + * - does not cause the default behavior of an event to occur + * - does not bubble up event + * - call handler only for the first founded element + * - returns whatever value that was returned by the handler + * @methodOf + * @name Event.callHandler + * + * @param {string|DOMElement|jQuery} selector - jQuery elements selector + * @param {string} event - event name + * @param {Object} [data] - a object of additional parameters to pass to the event handler + * @return value that was returned by the handler + * */ callHandler : function(selector, event, data) { return getEventElement(selector).triggerHandler(event, data); }, + + /** + * The same as the callHandler method, but selects element by id + * @methodOf + * @name Event.callHandlerById + * + * @param {string} id - DOM element id + * @param {string} event - event name + * @param {Object} [data] - a object of additional parameters to pass to the event handler + * @return value that was returned by the handler + * */ callHandlerById : function(id, event, data) { return $(document.getElementById(id)).triggerHandler(event, data); - }, + }, + + /** + * Create an event namespace for the components + * @methodOf + * @name Event.createNamespace + * + * @param {string} [componentName] - component name + * @param {string} [id] - element id + * @param {string} [prefix=RichFaces.Event.RICH_NAMESPACE] - namespace prefix or + * @return {string} namespace string + * */ // TODO: rename argument names createNamespace : function(componentName, id, prefix) { var a = [];