1 /** 2 * @author Pavel Yaschenko 3 */ 4 5 (function($, richfaces) { 6 7 /** 8 * RichFaces Event API container 9 * @class 10 * @memberOf RichFaces 11 * @static 12 * @name Event 13 * */ 14 richfaces.Event = richfaces.Event || {}; 15 16 var getEventElement = function (selector) { 17 if (!selector) { 18 throw "RichFaces.Event: empty selector"; 19 } 20 var element; 21 if (RichFaces.BaseComponent && selector instanceof RichFaces.BaseComponent) { 22 element = $(richfaces.getDomElement(selector.getEventElement())); 23 } else { 24 element = $(selector); 25 } 26 27 return element; 28 } 29 30 $.extend(richfaces.Event, { 31 /** 32 * @constant 33 * @name RichFaces.Event.RICH_NAMESPACE 34 * @type string 35 * */ 36 RICH_NAMESPACE : "RICH:", 37 38 /** 39 * Attach an event handler to execute when the DOM is fully loaded. 40 * 41 * @function 42 * @name RichFaces.Event.ready 43 * @param {function} fn - event handler 44 * @return {jQuery} document element wrapped by jQuery 45 * */ 46 ready : function(fn) { 47 // TODO: not completed yet 48 return $(document).ready(fn); 49 /* 50 function callback(jQueryReference) { 51 this; // document 52 } 53 */ 54 }, 55 56 /** 57 * Attach a handler to an event for the elements. 58 * @function 59 * @name RichFaces.Event.bind 60 * 61 * @param {string|DOMElement|jQuery} selector - jQuery elements selector 62 * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names 63 * @param {function} fn - event handler 64 * @param {Object} [data] - component or object with additional data 65 * It is a context for an event handler 66 * @return {function} function that binded to the element's event 67 * */ 68 bind : function(selector, type, fn, data) { 69 // type: namespace can be used, like onclick.rf.conponentName 70 var f = function (e,d){ 71 e.data.fn.call(e.data.component||this, e, this, d); 72 }; 73 getEventElement(selector).bind(type, {component: data, fn:fn}, f); 74 return f; 75 }, 76 77 /** 78 * Attach a handler to an event for the element by element id. 79 * @function 80 * @name RichFaces.Event.bindById 81 * 82 * @param {string} id - DOM element id 83 * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names 84 * @param {function} fn - event handler 85 * @param {Object} [data] - component or object with additional data 86 * It is a context for an event handler 87 * @return {function} function that binded to the element's event 88 * */ 89 bindById : function(id, type, fn, data) { 90 // type: namespace can be used, like onclick.rf.conponentName 91 var f = function (e,d){ 92 e.data.fn.call(e.data.component||this, e, this, d); 93 }; 94 $(document.getElementById(id)).bind(type, {component: data, fn:fn}, f); 95 return f; 96 }, 97 98 /** 99 * Attach a handler to an event for the elements. 100 * The handler will be called only once when event happened. 101 * @function 102 * @name RichFaces.Event.bindOne 103 * 104 * @param {string|DOMElement|jQuery} selector - jQuery elements selector 105 * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names 106 * @param {function} fn - event handler 107 * @param {Object} [data] - component or object with additional data 108 * It is a context for an event handler 109 * @return {function} function that binded to the element's event 110 * */ 111 bindOne: function(selector, type, fn, data) { 112 // type: namespace can be used, like onclick.rf.conponentName 113 var f = function (e,d){ 114 e.data.fn.call(e.data.component||this, e, this, d); 115 }; 116 getEventElement(selector).one(type, {component: data, fn:fn}, f); 117 return f; 118 }, 119 120 /** 121 * Attach a handler to an event for the element by element id. 122 * The handler will be called only once when event happened. 123 * @function 124 * @name RichFaces.Event.bindOneById 125 * 126 * @param {string} id - DOM element id 127 * @param {string} type - one or more JavaScript event types, such as "click" or "submit," or custom event names 128 * @param {function} fn - event handler 129 * @param {Object} [data] - component or object with additional data 130 * It is a context for an event handler 131 * @return {function} function that binded to the element's event 132 * */ 133 bindOneById: function(id, type, fn, data) { 134 // type: namespace can be used, like onclick.rf.conponentName 135 var f = function (e,d){ 136 e.data.fn.call(e.data.component||this, e, this, d); 137 }; 138 $(document.getElementById(id)).one(type, {component: data, fn:fn}, f); 139 return f; 140 }, 141 142 /** 143 * Remove a previously-attached event handler from the elements. 144 * @function 145 * @name RichFaces.Event.unbind 146 * 147 * @param {string|DOMElement|jQuery} selector - jQuery elements selector 148 * @param {string} [type] - one or more JavaScript event types, such as "click" or "submit," or custom event names 149 * @param {function} [fn] - event handler 150 * @return {jQuery} element wrapped by jQuery 151 * */ 152 unbind : function(selector, type, fn) { 153 // type: namespace can be used, like onclick.rf.conponentName 154 return getEventElement(selector).unbind(type, fn); 155 }, 156 157 /** 158 * Remove a previously-attached event handler from the elements by element id. 159 * The handler will be called only once when event happened. 160 * @function 161 * @name RichFaces.Event.unbindById 162 * 163 * @param {string} id - DOM element id 164 * @param {string} [type] - one or more JavaScript event types, such as "click" or "submit," or custom event names 165 * @param {function} [fn] - event handler 166 * @return {jQuery} element wrapped by jQuery 167 * */ 168 unbindById : function(id, type, fn) { 169 // type: namespace can be used, like onclick.rf.conponentName 170 return $(document.getElementById(id)).unbind(type, fn); 171 }, 172 173 /** 174 * Execute all handlers and behaviors attached to the matched elements for the given event type. 175 * @function 176 * @name RichFaces.Event.fire 177 * 178 * @param {string|DOMElement|jQuery} selector - jQuery elements selector 179 * @param {string} event - event name 180 * @param {Object} [data] - a object of additional parameters to pass to the event handler 181 * @return {jQuery} element wrapped by jQuery 182 * */ 183 fire : function(selector, event, data) { 184 return getEventElement(selector).trigger(event, data); 185 }, 186 187 /** 188 * The same as the fire method, but selects element by id. 189 * @function 190 * @name RichFaces.Event.fireById 191 * 192 * @param {string} id - DOM element id 193 * @param {string} event - event name 194 * @param {Object} [data] - a object of additional parameters to pass to the event handler 195 * @return {jQuery} element wrapped by jQuery 196 * */ 197 fireById : function(id, event, data) { 198 return $(document.getElementById(id)).trigger(event, data); 199 }, 200 201 /** 202 * The same as the fire method, but: 203 * - does not cause the default behavior of an event to occur 204 * - does not bubble up event 205 * - call handler only for the first founded element 206 * - returns whatever value that was returned by the handler 207 * @function 208 * @name RichFaces.Event.callHandler 209 * 210 * @param {string|DOMElement|jQuery} selector - jQuery elements selector 211 * @param {string} event - event name 212 * @param {Object} [data] - a object of additional parameters to pass to the event handler 213 * @return value that was returned by the handler 214 * */ 215 callHandler : function(selector, event, data) { 216 return getEventElement(selector).triggerHandler(event, data); 217 }, 218 219 /** 220 * The same as the callHandler method, but selects element by id. 221 * @function 222 * @name RichFaces.Event.callHandlerById 223 * 224 * @param {string} id - DOM element id 225 * @param {string} event - event name 226 * @param {Object} [data] - a object of additional parameters to pass to the event handler 227 * @return value that was returned by the handler 228 * */ 229 callHandlerById : function(id, event, data) { 230 return $(document.getElementById(id)).triggerHandler(event, data); 231 }, 232 233 /** 234 * Create an event namespace for the components. 235 * @function 236 * @name RichFaces.Event.createNamespace 237 * 238 * @param {string} [componentName] - component name 239 * @param {string} [id] - element id 240 * @param {string} [prefix=RichFaces.Event.RICH_NAMESPACE] - namespace prefix 241 * @return {string} namespace string 242 * */ 243 // TODO: rename argument names 244 createNamespace : function(componentName, id, prefix) { 245 var a = []; 246 a.push(prefix || richfaces.Event.RICH_NAMESPACE); 247 if (componentName) { 248 a.push(componentName); 249 } 250 if (id) { 251 a.push(id); 252 } 253 return a.join('.'); 254 } 255 }); 256 257 })(jQuery, window.RichFaces || (window.RichFaces={})); 258 259 /* 260 fn : function (eventObject, element) { 261 this; // object passed as data to bind function or dom element if no data 262 element; // dom element 263 264 } 265 */ 266 267 // API usage example: 268 // RichFaces.Event.bind(selector, type, fn, data); 269