2 * Ext JS Library 2.2.1
\r
3 * Copyright(c) 2006-2009, Ext JS, LLC.
\r
4 * licensing@extjs.com
\r
6 * http://extjs.com/license
\r
10 * @class Ext.data.Connection
\r
11 * @extends Ext.util.Observable
\r
12 * <p>The class encapsulates a connection to the page's originating domain, allowing requests to be made
\r
13 * either to a configured URL, or to a URL specified at request time.</p>
\r
14 * <p>Requests made by this class are asynchronous, and will return immediately. No data from
\r
15 * the server will be available to the statement immediately following the {@link #request} call.
\r
16 * To process returned data, use a
\r
17 * <a href="#request-option-success" ext:member="request-option-success" ext:cls="Ext.data.Connection">success callback</a>
\r
18 * in the request options object,
\r
19 * or an {@link #requestcomplete event listener}.</p>
\r
20 * <p><h3>File Uploads</h3><a href="#request-option-isUpload" ext:member="request-option-isUpload" ext:cls="Ext.data.Connection">File uploads</a> are not performed using normal "Ajax" techniques, that
\r
21 * is they are <b>not</b> performed using XMLHttpRequests. Instead the form is submitted in the standard
\r
22 * manner with the DOM <tt><form></tt> element temporarily modified to have its
\r
23 * <a href="http://www.w3.org/TR/REC-html40/present/frames.html#adef-target">target</a> set to refer
\r
24 * to a dynamically generated, hidden <tt><iframe></tt> which is inserted into the document
\r
25 * but removed after the return data has been gathered.</p>
\r
26 * <p>The server response is parsed by the browser to create the document for the IFRAME. If the
\r
27 * server is using JSON to send the return object, then the
\r
28 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17">Content-Type</a> header
\r
29 * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.</p>
\r
30 * <p>Characters which are significant to an HTML parser must be sent as HTML entities, so encode
\r
31 * "<" as "&lt;", "&" as "&amp;" etc.</p>
\r
32 * <p>The response text is retrieved from the document, and a fake XMLHttpRequest object
\r
33 * is created containing a <tt>responseText</tt> property in order to conform to the
\r
34 * requirements of event handlers and callbacks.</p>
\r
35 * <p>Be aware that file upload packets are sent with the content type <a href="http://www.faqs.org/rfcs/rfc2388.html">multipart/form</a>
\r
36 * and some server technologies (notably JEE) may require some custom processing in order to
\r
37 * retrieve parameter names and parameter values from the packet content.</p>
\r
39 * @param {Object} config a configuration object.
\r
41 Ext.data.Connection = function(config){
\r
42 Ext.apply(this, config);
\r
45 * @event beforerequest
\r
46 * Fires before a network request is made to retrieve a data object.
\r
47 * @param {Connection} conn This Connection object.
\r
48 * @param {Object} options The options config object passed to the {@link #request} method.
\r
52 * @event requestcomplete
\r
53 * Fires if the request was successfully completed.
\r
54 * @param {Connection} conn This Connection object.
\r
55 * @param {Object} response The XHR object containing the response data.
\r
56 * See <a href="http://www.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object</a>
\r
58 * @param {Object} options The options config object passed to the {@link #request} method.
\r
62 * @event requestexception
\r
63 * Fires if an error HTTP status was returned from the server.
\r
64 * See <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP Status Code Definitions</a>
\r
65 * for details of HTTP status codes.
\r
66 * @param {Connection} conn This Connection object.
\r
67 * @param {Object} response The XHR object containing the response data.
\r
68 * See <a href="http://www.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object</a>
\r
70 * @param {Object} options The options config object passed to the {@link #request} method.
\r
74 Ext.data.Connection.superclass.constructor.call(this);
\r
77 Ext.extend(Ext.data.Connection, Ext.util.Observable, {
\r
79 * @cfg {String} url (Optional) The default URL to be used for requests to the server. (defaults to undefined)
\r
82 * @cfg {Object} extraParams (Optional) An object containing properties which are used as
\r
83 * extra parameters to each request made by this object. (defaults to undefined)
\r
86 * @cfg {Object} defaultHeaders (Optional) An object containing request headers which are added
\r
87 * to each request made by this object. (defaults to undefined)
\r
90 * @cfg {String} method (Optional) The default HTTP method to be used for requests.
\r
91 * (defaults to undefined; if not set, but {@link #request} params are present, POST will be used;
\r
92 * otherwise, GET will be used.)
\r
95 * @cfg {Number} timeout (Optional) The timeout in milliseconds to be used for requests. (defaults to 30000)
\r
99 * @cfg {Boolean} autoAbort (Optional) Whether this request should abort any pending requests. (defaults to false)
\r
105 * @cfg {Boolean} disableCaching (Optional) True to add a unique cache-buster param to GET requests. (defaults to true)
\r
108 disableCaching: true,
\r
111 * @cfg {String} disableCachingParam (Optional) Change the parameter which is sent went disabling caching
\r
112 * through a cache buster. Defaults to '_dc'
\r
115 disableCachingParam: '_dc',
\r
119 * <p>Sends an HTTP request to a remote server.</p>
\r
120 * <p><b>Important:</b> Ajax server requests are asynchronous, and this call will
\r
121 * return before the response has been received. Process any returned data
\r
122 * in a callback function.</p>
\r
123 * <p>To execute a callback function in the correct scope, use the <tt>scope</tt> option.</p>
\r
124 * @param {Object} options An object which may contain the following properties:<ul>
\r
125 * <li><b>url</b> : String/Function (Optional)<div class="sub-desc">The URL to
\r
126 * which to send the request, or a function to call which returns a URL string. The scope of the
\r
127 * function is specified by the <tt>scope</tt> option. Defaults to configured URL.</div></li>
\r
128 * <li><b>params</b> : Object/String/Function (Optional)<div class="sub-desc">
\r
129 * An object containing properties which are used as parameters to the
\r
130 * request, a url encoded string or a function to call to get either. The scope of the function
\r
131 * is specified by the <tt>scope</tt> option.</div></li>
\r
132 * <li><b>method</b> : String (Optional)<div class="sub-desc">The HTTP method to use
\r
133 * for the request. Defaults to the configured method, or if no method was configured,
\r
134 * "GET" if no parameters are being sent, and "POST" if parameters are being sent. Note that
\r
135 * the method name is case-sensitive and should be all caps.</div></li>
\r
136 * <li><b>callback</b> : Function (Optional)<div class="sub-desc">The
\r
137 * function to be called upon receipt of the HTTP response. The callback is
\r
138 * called regardless of success or failure and is passed the following
\r
140 * <li><b>options</b> : Object<div class="sub-desc">The parameter to the request call.</div></li>
\r
141 * <li><b>success</b> : Boolean<div class="sub-desc">True if the request succeeded.</div></li>
\r
142 * <li><b>response</b> : Object<div class="sub-desc">The XMLHttpRequest object containing the response data.
\r
143 * See <a href="http://www.w3.org/TR/XMLHttpRequest/">http://www.w3.org/TR/XMLHttpRequest/</a> for details about
\r
144 * accessing elements of the response.</div></li>
\r
146 * <li><a id="request-option-success"></a><b>success</b> : Function (Optional)<div class="sub-desc">The function
\r
147 * to be called upon success of the request. The callback is passed the following
\r
149 * <li><b>response</b> : Object<div class="sub-desc">The XMLHttpRequest object containing the response data.</div></li>
\r
150 * <li><b>options</b> : Object<div class="sub-desc">The parameter to the request call.</div></li>
\r
152 * <li><b>failure</b> : Function (Optional)<div class="sub-desc">The function
\r
153 * to be called upon failure of the request. The callback is passed the
\r
154 * following parameters:<ul>
\r
155 * <li><b>response</b> : Object<div class="sub-desc">The XMLHttpRequest object containing the response data.</div></li>
\r
156 * <li><b>options</b> : Object<div class="sub-desc">The parameter to the request call.</div></li>
\r
158 * <li><b>scope</b> : Object (Optional)<div class="sub-desc">The scope in
\r
159 * which to execute the callbacks: The "this" object for the callback function. If the <tt>url</tt>, or <tt>params</tt> options were
\r
160 * specified as functions from which to draw values, then this also serves as the scope for those function calls.
\r
161 * Defaults to the browser window.</div></li>
\r
162 * <li><b>form</b> : Element/HTMLElement/String (Optional)<div class="sub-desc">The <tt><form></tt>
\r
163 * Element or the id of the <tt><form></tt> to pull parameters from.</div></li>
\r
164 * <li><a id="request-option-isUpload"></a><b>isUpload</b> : Boolean (Optional)<div class="sub-desc"><b>Only meaningful when used
\r
165 * with the <tt>form</tt> option.</b>
\r
166 * <p>True if the form object is a file upload (will be set automatically if the form was
\r
167 * configured with <b><tt>enctype</tt></b> "multipart/form-data").</p>
\r
168 * <p>File uploads are not performed using normal "Ajax" techniques, that is they are <b>not</b>
\r
169 * performed using XMLHttpRequests. Instead the form is submitted in the standard manner with the
\r
170 * DOM <tt><form></tt> element temporarily modified to have its
\r
171 * <a href="http://www.w3.org/TR/REC-html40/present/frames.html#adef-target">target</a> set to refer
\r
172 * to a dynamically generated, hidden <tt><iframe></tt> which is inserted into the document
\r
173 * but removed after the return data has been gathered.</p>
\r
174 * <p>The server response is parsed by the browser to create the document for the IFRAME. If the
\r
175 * server is using JSON to send the return object, then the
\r
176 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17">Content-Type</a> header
\r
177 * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.</p>
\r
178 * <p>The response text is retrieved from the document, and a fake XMLHttpRequest object
\r
179 * is created containing a <tt>responseText</tt> property in order to conform to the
\r
180 * requirements of event handlers and callbacks.</p>
\r
181 * <p>Be aware that file upload packets are sent with the content type <a href="http://www.faqs.org/rfcs/rfc2388.html">multipart/form</a>
\r
182 * and some server technologies (notably JEE) may require some custom processing in order to
\r
183 * retrieve parameter names and parameter values from the packet content.</p>
\r
185 * <li><b>headers</b> : Object (Optional)<div class="sub-desc">Request
\r
186 * headers to set for the request.</div></li>
\r
187 * <li><b>xmlData</b> : Object (Optional)<div class="sub-desc">XML document
\r
188 * to use for the post. Note: This will be used instead of params for the post
\r
189 * data. Any params will be appended to the URL.</div></li>
\r
190 * <li><b>jsonData</b> : Object/String (Optional)<div class="sub-desc">JSON
\r
191 * data to use as the post. Note: This will be used instead of params for the post
\r
192 * data. Any params will be appended to the URL.</div></li>
\r
193 * <li><b>disableCaching</b> : Boolean (Optional)<div class="sub-desc">True
\r
194 * to add a unique cache-buster param to GET requests.</div></li>
\r
196 * <p>The options object may also contain any other property which might be needed to perform
\r
197 * postprocessing in a callback because it is passed to callback functions.</p>
\r
198 * @return {Number} transactionId The id of the server transaction. This may be used
\r
199 * to cancel the request.
\r
201 request : function(o){
\r
202 if(this.fireEvent("beforerequest", this, o) !== false){
\r
205 if(typeof p == "function"){
\r
206 p = p.call(o.scope||window, o);
\r
208 if(typeof p == "object"){
\r
209 p = Ext.urlEncode(p);
\r
211 if(this.extraParams){
\r
212 var extras = Ext.urlEncode(this.extraParams);
\r
213 p = p ? (p + '&' + extras) : extras;
\r
216 var url = o.url || this.url;
\r
217 if(typeof url == 'function'){
\r
218 url = url.call(o.scope||window, o);
\r
222 var form = Ext.getDom(o.form);
\r
223 url = url || form.action;
\r
225 var enctype = form.getAttribute("enctype");
\r
226 if(o.isUpload || (enctype && enctype.toLowerCase() == 'multipart/form-data')){
\r
227 return this.doFormUpload(o, p, url);
\r
229 var f = Ext.lib.Ajax.serializeForm(form);
\r
230 p = p ? (p + '&' + f) : f;
\r
233 var hs = o.headers;
\r
234 if(this.defaultHeaders){
\r
235 hs = Ext.apply(hs || {}, this.defaultHeaders);
\r
242 success: this.handleResponse,
\r
243 failure: this.handleFailure,
\r
245 argument: {options: o},
\r
246 timeout : o.timeout || this.timeout
\r
249 var method = o.method||this.method||((p || o.xmlData || o.jsonData) ? "POST" : "GET");
\r
251 if(method == 'GET' && (this.disableCaching && o.disableCaching !== false) || o.disableCaching === true){
\r
252 var dcp = o.disableCachingParam || this.disableCachingParam;
\r
253 url += (url.indexOf('?') != -1 ? '&' : '?') + dcp + '=' + (new Date().getTime());
\r
256 if(typeof o.autoAbort == 'boolean'){ // options gets top priority
\r
260 }else if(this.autoAbort !== false){
\r
263 if((method == 'GET' || o.xmlData || o.jsonData) && p){
\r
264 url += (url.indexOf('?') != -1 ? '&' : '?') + p;
\r
267 this.transId = Ext.lib.Ajax.request(method, url, cb, p, o);
\r
268 return this.transId;
\r
270 Ext.callback(o.callback, o.scope, [o, null, null]);
\r
276 * Determine whether this object has a request outstanding.
\r
277 * @param {Number} transactionId (Optional) defaults to the last transaction
\r
278 * @return {Boolean} True if there is an outstanding request.
\r
280 isLoading : function(transId){
\r
282 return Ext.lib.Ajax.isCallInProgress(transId);
\r
284 return this.transId ? true : false;
\r
289 * Aborts any outstanding request.
\r
290 * @param {Number} transactionId (Optional) defaults to the last transaction
\r
292 abort : function(transId){
\r
293 if(transId || this.isLoading()){
\r
294 Ext.lib.Ajax.abort(transId || this.transId);
\r
299 handleResponse : function(response){
\r
300 this.transId = false;
\r
301 var options = response.argument.options;
\r
302 response.argument = options ? options.argument : null;
\r
303 this.fireEvent("requestcomplete", this, response, options);
\r
304 Ext.callback(options.success, options.scope, [response, options]);
\r
305 Ext.callback(options.callback, options.scope, [options, true, response]);
\r
309 handleFailure : function(response, e){
\r
310 this.transId = false;
\r
311 var options = response.argument.options;
\r
312 response.argument = options ? options.argument : null;
\r
313 this.fireEvent("requestexception", this, response, options, e);
\r
314 Ext.callback(options.failure, options.scope, [response, options]);
\r
315 Ext.callback(options.callback, options.scope, [options, false, response]);
\r
319 doFormUpload : function(o, ps, url){
\r
321 var frame = document.createElement('iframe');
\r
324 frame.className = 'x-hidden';
\r
326 frame.src = Ext.SSL_SECURE_URL;
\r
328 document.body.appendChild(frame);
\r
331 document.frames[id].name = id;
\r
334 var form = Ext.getDom(o.form);
\r
336 form.method = 'POST';
\r
337 form.enctype = form.encoding = 'multipart/form-data';
\r
343 if(ps){ // add dynamic params
\r
345 ps = Ext.urlDecode(ps, false);
\r
347 if(ps.hasOwnProperty(k)){
\r
348 hd = document.createElement('input');
\r
349 hd.type = 'hidden';
\r
352 form.appendChild(hd);
\r
359 var r = { // bogus response object
\r
364 r.argument = o ? o.argument : null;
\r
369 doc = frame.contentWindow.document;
\r
371 doc = (frame.contentDocument || window.frames[id].document);
\r
373 if(doc && doc.body){
\r
374 r.responseText = doc.body.innerHTML;
\r
376 if(doc && doc.XMLDocument){
\r
377 r.responseXML = doc.XMLDocument;
\r
379 r.responseXML = doc;
\r
386 Ext.EventManager.removeListener(frame, 'load', cb, this);
\r
388 this.fireEvent("requestcomplete", this, r, o);
\r
390 Ext.callback(o.success, o.scope, [r, o]);
\r
391 Ext.callback(o.callback, o.scope, [o, true, r]);
\r
393 setTimeout(function(){Ext.removeNode(frame);}, 100);
\r
396 Ext.EventManager.on(frame, 'load', cb, this);
\r
399 if(hiddens){ // remove dynamic params
\r
400 for(var i = 0, len = hiddens.length; i < len; i++){
\r
401 Ext.removeNode(hiddens[i]);
\r
409 * @extends Ext.data.Connection
\r
410 * Global Ajax request class. Provides a simple way to make Ajax requests with maximum flexibility. Example usage:
\r
420 params: { foo: 'bar' }
\r
423 // Simple ajax form submission
\r
429 // Default headers to pass in every request
\r
430 Ext.Ajax.defaultHeaders = {
\r
431 'Powered-By': 'Ext'
\r
434 // Global Ajax events can be handled on every request!
\r
435 Ext.Ajax.on('beforerequest', this.showSpinner, this);
\r
439 Ext.Ajax = new Ext.data.Connection({
\r
441 * @cfg {String} url @hide
\r
444 * @cfg {Object} extraParams @hide
\r
447 * @cfg {Object} defaultHeaders @hide
\r
450 * @cfg {String} method (Optional) @hide
\r
453 * @cfg {Number} timeout (Optional) @hide
\r
456 * @cfg {Boolean} autoAbort (Optional) @hide
\r
460 * @cfg {Boolean} disableCaching (Optional) @hide
\r
464 * @property disableCaching
\r
465 * True to add a unique cache-buster param to GET requests. (defaults to true)
\r
470 * The default URL to be used for requests to the server. (defaults to undefined)
\r
474 * @property extraParams
\r
475 * An object containing properties which are used as
\r
476 * extra parameters to each request made by this object. (defaults to undefined)
\r
480 * @property defaultHeaders
\r
481 * An object containing request headers which are added to each request made by this object. (defaults to undefined)
\r
486 * The default HTTP method to be used for requests. Note that this is case-sensitive and should be all caps (defaults
\r
487 * to undefined; if not set but parms are present will use "POST," otherwise "GET.")
\r
491 * @property timeout
\r
492 * The timeout in milliseconds to be used for requests. (defaults to 30000)
\r
497 * @property autoAbort
\r
498 * Whether a new request should abort any pending requests. (defaults to false)
\r
504 * Serialize the passed form into a url encoded string
\r
505 * @param {String/HTMLElement} form
\r
508 serializeForm : function(form){
\r
509 return Ext.lib.Ajax.serializeForm(form);
\r