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