2
* Ext JS Library 3.0 RC2
3
* Copyright(c) 2006-2009, Ext JS, LLC.
6
* http://extjs.com/license
10
var BEFOREREQUEST = "beforerequest",
11
REQUESTCOMPLETE = "requestcomplete",
12
REQUESTEXCEPTION = "requestexception",
13
UNDEFINED = undefined,
20
* @class Ext.data.Connection
21
* @extends Ext.util.Observable
22
* <p>The class encapsulates a connection to the page's originating domain, allowing requests to be made
23
* either to a configured URL, or to a URL specified at request time.</p>
24
* <p>Requests made by this class are asynchronous, and will return immediately. No data from
25
* the server will be available to the statement immediately following the {@link #request} call.
26
* To process returned data, use a
27
* <a href="#request-option-success" ext:member="request-option-success" ext:cls="Ext.data.Connection">success callback</a>
28
* in the request options object,
29
* or an {@link #requestcomplete event listener}.</p>
30
* <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
31
* is they are <b>not</b> performed using XMLHttpRequests. Instead the form is submitted in the standard
32
* manner with the DOM <tt><form></tt> element temporarily modified to have its
33
* <a href="http://www.w3.org/TR/REC-html40/present/frames.html#adef-target">target</a> set to refer
34
* to a dynamically generated, hidden <tt><iframe></tt> which is inserted into the document
35
* but removed after the return data has been gathered.</p>
36
* <p>The server response is parsed by the browser to create the document for the IFRAME. If the
37
* server is using JSON to send the return object, then the
38
* <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17">Content-Type</a> header
39
* must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.</p>
40
* <p>Characters which are significant to an HTML parser must be sent as HTML entities, so encode
41
* "<" as "&lt;", "&" as "&amp;" etc.</p>
42
* <p>The response text is retrieved from the document, and a fake XMLHttpRequest object
43
* is created containing a <tt>responseText</tt> property in order to conform to the
44
* requirements of event handlers and callbacks.</p>
45
* <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>
46
* and some server technologies (notably JEE) may require some custom processing in order to
47
* retrieve parameter names and parameter values from the packet content.</p>
49
* @param {Object} config a configuration object.
51
Ext.data.Connection = function(config){
52
Ext.apply(this, config);
55
* @event beforerequest
56
* Fires before a network request is made to retrieve a data object.
57
* @param {Connection} conn This Connection object.
58
* @param {Object} options The options config object passed to the {@link #request} method.
62
* @event requestcomplete
63
* Fires if the request was successfully completed.
64
* @param {Connection} conn This Connection object.
65
* @param {Object} response The XHR object containing the response data.
66
* See <a href="http://www.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object</a>
68
* @param {Object} options The options config object passed to the {@link #request} method.
72
* @event requestexception
73
* Fires if an error HTTP status was returned from the server.
74
* See <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP Status Code Definitions</a>
75
* for details of HTTP status codes.
76
* @param {Connection} conn This Connection object.
77
* @param {Object} response The XHR object containing the response data.
78
* See <a href="http://www.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object</a>
80
* @param {Object} options The options config object passed to the {@link #request} method.
84
Ext.data.Connection.superclass.constructor.call(this);
88
function handleResponse(response){
90
var options = response.argument.options;
91
response.argument = options ? options.argument : null;
92
this.fireEvent(REQUESTCOMPLETE, this, response, options);
93
if(options.success) options.success.call(options.scope, response, options);
94
if(options.callback) options.callback.call(options.scope, options, true, response);
98
function handleFailure(response, e){
100
var options = response.argument.options;
101
response.argument = options ? options.argument : null;
102
this.fireEvent(REQUESTEXCEPTION, this, response, options, e);
103
if(options.failure) options.failure.call(options.scope, response, options);
104
if(options.callback) options.callback.call(options.scope, options, false, response);
108
function doFormUpload(o, ps, url){
111
frame = doc.createElement('iframe'),
112
form = Ext.getDom(o.form),
116
frame.id = frame.name = id;
117
frame.className = 'x-hidden';
118
frame.src = Ext.SSL_SECURE_URL; // for IE
119
doc.body.appendChild(frame);
122
doc.frames[id].name = id;
127
form.enctype = form.encoding = 'multipart/form-data';
128
form.action = url || "";
130
// add dynamic params
131
ps = Ext.urlDecode(ps, false);
133
if(ps.hasOwnProperty(k)){
134
hd = doc.createElement('input');
136
hd.value = ps[hd.name = k];
137
form.appendChild(hd);
144
// bogus response object
145
r = {responseText : '',
147
argument : o.argument},
152
doc = frame.contentWindow.document || frame.contentDocument || WINDOW.frames[id].document;
155
if (/textarea/i.test((firstChild = doc.body.firstChild || {}).tagName)) { // json response wrapped in textarea
156
r.responseText = firstChild.value;
158
r.responseText = doc.body.innerHTML;
161
r.responseXML = doc.XMLDocument || doc;
167
Ext.EventManager.removeListener(frame, LOAD, cb, me);
169
me.fireEvent(REQUESTCOMPLETE, me, r, o);
171
Ext.callback(o.success, o.scope, [r, o]);
172
Ext.callback(o.callback, o.scope, [o, true, r]);
174
if(!me.debugUploads){
175
setTimeout(function(){Ext.removeNode(frame);}, 100);
179
Ext.EventManager.on(frame, LOAD, cb, this);
182
Ext.each(hiddens, function(h) {
187
Ext.extend(Ext.data.Connection, Ext.util.Observable, {
189
* @cfg {String} url (Optional) <p>The default URL to be used for requests to the server. Defaults to undefined.</p>
190
* <p>The <code>url</code> config may be a function which <i>returns</i> the URL to use for the Ajax request. The scope
191
* (<code><b>this</b></code> reference) of the function is the <code>scope</code> option passed to the {@link #request} method.</p>
194
* @cfg {Object} extraParams (Optional) An object containing properties which are used as
195
* extra parameters to each request made by this object. (defaults to undefined)
198
* @cfg {Object} defaultHeaders (Optional) An object containing request headers which are added
199
* to each request made by this object. (defaults to undefined)
202
* @cfg {String} method (Optional) The default HTTP method to be used for requests.
203
* (defaults to undefined; if not set, but {@link #request} params are present, POST will be used;
204
* otherwise, GET will be used.)
207
* @cfg {Number} timeout (Optional) The timeout in milliseconds to be used for requests. (defaults to 30000)
211
* @cfg {Boolean} autoAbort (Optional) Whether this request should abort any pending requests. (defaults to false)
217
* @cfg {Boolean} disableCaching (Optional) True to add a unique cache-buster param to GET requests. (defaults to true)
220
disableCaching: true,
223
* @cfg {String} disableCachingParam (Optional) Change the parameter which is sent went disabling caching
224
* through a cache buster. Defaults to '_dc'
227
disableCachingParam: '_dc',
230
* <p>Sends an HTTP request to a remote server.</p>
231
* <p><b>Important:</b> Ajax server requests are asynchronous, and this call will
232
* return before the response has been received. Process any returned data
233
* in a callback function.</p>
236
url: 'ajax_demo/sample.json',
237
success: function(response, opts) {
238
var obj = Ext.decode(response.responseText);
241
failure: function(response, opts) {
242
console.log('server-side failure with status code ' + response.status);
246
* <p>To execute a callback function in the correct scope, use the <tt>scope</tt> option.</p>
247
* @param {Object} options An object which may contain the following properties:<ul>
248
* <li><b>url</b> : String/Function (Optional)<div class="sub-desc">The URL to
249
* which to send the request, or a function to call which returns a URL string. The scope of the
250
* function is specified by the <tt>scope</tt> option. Defaults to the configured
251
* <tt>{@link #url}</tt>.</div></li>
252
* <li><b>params</b> : Object/String/Function (Optional)<div class="sub-desc">
253
* An object containing properties which are used as parameters to the
254
* request, a url encoded string or a function to call to get either. The scope of the function
255
* is specified by the <tt>scope</tt> option.</div></li>
256
* <li><b>method</b> : String (Optional)<div class="sub-desc">The HTTP method to use
257
* for the request. Defaults to the configured method, or if no method was configured,
258
* "GET" if no parameters are being sent, and "POST" if parameters are being sent. Note that
259
* the method name is case-sensitive and should be all caps.</div></li>
260
* <li><b>callback</b> : Function (Optional)<div class="sub-desc">The
261
* function to be called upon receipt of the HTTP response. The callback is
262
* called regardless of success or failure and is passed the following
264
* <li><b>options</b> : Object<div class="sub-desc">The parameter to the request call.</div></li>
265
* <li><b>success</b> : Boolean<div class="sub-desc">True if the request succeeded.</div></li>
266
* <li><b>response</b> : Object<div class="sub-desc">The XMLHttpRequest object containing the response data.
267
* See <a href="http://www.w3.org/TR/XMLHttpRequest/">http://www.w3.org/TR/XMLHttpRequest/</a> for details about
268
* accessing elements of the response.</div></li>
270
* <li><a id="request-option-success"></a><b>success</b> : Function (Optional)<div class="sub-desc">The function
271
* to be called upon success of the request. The callback is passed the following
273
* <li><b>response</b> : Object<div class="sub-desc">The XMLHttpRequest object containing the response data.</div></li>
274
* <li><b>options</b> : Object<div class="sub-desc">The parameter to the request call.</div></li>
276
* <li><b>failure</b> : Function (Optional)<div class="sub-desc">The function
277
* to be called upon failure of the request. The callback is passed the
278
* following parameters:<ul>
279
* <li><b>response</b> : Object<div class="sub-desc">The XMLHttpRequest object containing the response data.</div></li>
280
* <li><b>options</b> : Object<div class="sub-desc">The parameter to the request call.</div></li>
282
* <li><b>scope</b> : Object (Optional)<div class="sub-desc">The scope in
283
* which to execute the callbacks: The "this" object for the callback function. If the <tt>url</tt>, or <tt>params</tt> options were
284
* specified as functions from which to draw values, then this also serves as the scope for those function calls.
285
* Defaults to the browser window.</div></li>
286
* <li><b>timeout</b> : Number (Optional)<div class="sub-desc">The timeout in milliseconds to be used for this request. Defaults to 30 seconds.</div></li>
287
* <li><b>form</b> : Element/HTMLElement/String (Optional)<div class="sub-desc">The <tt><form></tt>
288
* Element or the id of the <tt><form></tt> to pull parameters from.</div></li>
289
* <li><a id="request-option-isUpload"></a><b>isUpload</b> : Boolean (Optional)<div class="sub-desc"><b>Only meaningful when used
290
* with the <tt>form</tt> option</b>.
291
* <p>True if the form object is a file upload (will be set automatically if the form was
292
* configured with <b><tt>enctype</tt></b> "multipart/form-data").</p>
293
* <p>File uploads are not performed using normal "Ajax" techniques, that is they are <b>not</b>
294
* performed using XMLHttpRequests. Instead the form is submitted in the standard manner with the
295
* DOM <tt><form></tt> element temporarily modified to have its
296
* <a href="http://www.w3.org/TR/REC-html40/present/frames.html#adef-target">target</a> set to refer
297
* to a dynamically generated, hidden <tt><iframe></tt> which is inserted into the document
298
* but removed after the return data has been gathered.</p>
299
* <p>The server response is parsed by the browser to create the document for the IFRAME. If the
300
* server is using JSON to send the return object, then the
301
* <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17">Content-Type</a> header
302
* must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.</p>
303
* <p>The response text is retrieved from the document, and a fake XMLHttpRequest object
304
* is created containing a <tt>responseText</tt> property in order to conform to the
305
* requirements of event handlers and callbacks.</p>
306
* <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>
307
* and some server technologies (notably JEE) may require some custom processing in order to
308
* retrieve parameter names and parameter values from the packet content.</p>
310
* <li><b>headers</b> : Object (Optional)<div class="sub-desc">Request
311
* headers to set for the request.</div></li>
312
* <li><b>xmlData</b> : Object (Optional)<div class="sub-desc">XML document
313
* to use for the post. Note: This will be used instead of params for the post
314
* data. Any params will be appended to the URL.</div></li>
315
* <li><b>jsonData</b> : Object/String (Optional)<div class="sub-desc">JSON
316
* data to use as the post. Note: This will be used instead of params for the post
317
* data. Any params will be appended to the URL.</div></li>
318
* <li><b>disableCaching</b> : Boolean (Optional)<div class="sub-desc">True
319
* to add a unique cache-buster param to GET requests.</div></li>
321
* <p>The options object may also contain any other property which might be needed to perform
322
* postprocessing in a callback because it is passed to callback functions.</p>
323
* @return {Number} transactionId The id of the server transaction. This may be used
324
* to cancel the request.
326
request : function(o){
328
if(me.fireEvent(BEFOREREQUEST, me, o)){
330
if(!Ext.isEmpty(o.indicatorText)){
331
me.indicatorText = '<div class="loading-indicator">'+o.indicatorText+"</div>";
333
if(me.indicatorText) {
334
Ext.getDom(o.el).innerHTML = me.indicatorText;
336
o.success = (Ext.isFunction(o.success) ? o.success : function(){}).createInterceptor(function(response) {
337
Ext.getDom(o.el).innerHTML = response.responseText;
342
url = o.url || me.url,
344
cb = {success: handleResponse,
345
failure: handleFailure,
347
argument: {options: o},
348
timeout : o.timeout || me.timeout
354
if (Ext.isFunction(p)) {
355
p = p.call(o.scope||WINDOW, o);
358
p = Ext.urlEncode(me.extraParams, typeof p == 'object' ? Ext.urlEncode(p) : p);
360
if (Ext.isFunction(url)) {
361
url = url.call(o.scope || WINDOW, o);
364
if(form = Ext.getDom(o.form)){
365
url = url || form.action;
366
if(o.isUpload || /multipart\/form-data/i.test(form.getAttribute("enctype"))) {
367
return doFormUpload.call(me, o, p, url);
369
serForm = Ext.lib.Ajax.serializeForm(form);
370
p = p ? (p + '&' + serForm) : serForm;
373
method = o.method || me.method || ((p || o.xmlData || o.jsonData) ? POST : GET);
375
if(method === GET && (me.disableCaching && o.disableCaching !== false) || o.disableCaching === true){
376
var dcp = o.disableCachingParam || me.disableCachingParam;
377
url += (url.indexOf('?') != -1 ? '&' : '?') + dcp + '=' + (new Date().getTime());
380
o.headers = Ext.apply(o.headers || {}, me.defaultHeaders || {});
382
if(o.autoAbort === true || me.autoAbort) {
386
if((method == GET || o.xmlData || o.jsonData) && p){
387
url += (/\?/.test(url) ? '&' : '?') + p;
390
return me.transId = Ext.lib.Ajax.request(method, url, cb, p, o);
392
return o.callback ? o.callback.apply(o.scope, [o,UNDEFINED,UNDEFINED]) : null;
397
* Determine whether this object has a request outstanding.
398
* @param {Number} transactionId (Optional) defaults to the last transaction
399
* @return {Boolean} True if there is an outstanding request.
401
isLoading : function(transId){
402
return transId ? Ext.lib.Ajax.isCallInProgress(transId) : !! this.transId;
406
* Aborts any outstanding request.
407
* @param {Number} transactionId (Optional) defaults to the last transaction
409
abort : function(transId){
410
if(transId || this.isLoading()){
411
Ext.lib.Ajax.abort(transId || this.transId);
419
* @extends Ext.data.Connection
420
* <p>The global Ajax request class that provides a simple way to make Ajax requests
421
* with maximum flexibility.</p>
422
* <p>Since Ext.Ajax is a singleton, you can set common properties/events for it once
423
* and override them at the request function level only if necessary.</p>
424
* <p>Common <b>Properties</b> you may want to set are:<div class="mdetail-params"><ul>
425
* <li><b><tt>{@link #method}</tt></b><p class="sub-desc"></p></li>
426
* <li><b><tt>{@link #extraParams}</tt></b><p class="sub-desc"></p></li>
427
* <li><b><tt>{@link #url}</tt></b><p class="sub-desc"></p></li>
430
// Default headers to pass in every request
431
Ext.Ajax.defaultHeaders = {
436
* <p>Common <b>Events</b> you may want to set are:<div class="mdetail-params"><ul>
437
* <li><b><tt>{@link Ext.data.Connection#beforerequest beforerequest}</tt></b><p class="sub-desc"></p></li>
438
* <li><b><tt>{@link Ext.data.Connection#requestcomplete requestcomplete}</tt></b><p class="sub-desc"></p></li>
439
* <li><b><tt>{@link Ext.data.Connection#requestexception requestexception}</tt></b><p class="sub-desc"></p></li>
442
// Example: show a spinner during all Ajax requests
443
Ext.Ajax.on('beforerequest', this.showSpinner, this);
444
Ext.Ajax.on('requestcomplete', this.hideSpinner, this);
445
Ext.Ajax.on('requestexception', this.hideSpinner, this);
448
* <p>An example request:</p>
451
Ext.Ajax.{@link Ext.data.Connection#request request}({
458
params: { foo: 'bar' }
461
// Simple ajax form submission
462
Ext.Ajax.{@link Ext.data.Connection#request request}({
470
Ext.Ajax = new Ext.data.Connection({
472
* @cfg {String} url @hide
475
* @cfg {Object} extraParams @hide
478
* @cfg {Object} defaultHeaders @hide
481
* @cfg {String} method (Optional) @hide
484
* @cfg {Number} timeout (Optional) @hide
487
* @cfg {Boolean} autoAbort (Optional) @hide
491
* @cfg {Boolean} disableCaching (Optional) @hide
495
* @property disableCaching
496
* True to add a unique cache-buster param to GET requests. (defaults to true)
501
* The default URL to be used for requests to the server. (defaults to undefined)
502
* If the server receives all requests through one URL, setting this once is easier than
503
* entering it on every request.
507
* @property extraParams
508
* An object containing properties which are used as extra parameters to each request made
509
* by this object (defaults to undefined). Session information and other data that you need
510
* to pass with each request are commonly put here.
514
* @property defaultHeaders
515
* An object containing request headers which are added to each request made by this object
516
* (defaults to undefined).
521
* The default HTTP method to be used for requests. Note that this is case-sensitive and
522
* should be all caps (defaults to undefined; if not set but params are present will use
523
* <tt>"POST"</tt>, otherwise will use <tt>"GET"</tt>.)
528
* The timeout in milliseconds to be used for requests. (defaults to 30000)
533
* @property autoAbort
534
* Whether a new request should abort any pending requests. (defaults to false)
540
* Serialize the passed form into a url encoded string
541
* @param {String/HTMLElement} form
544
serializeForm : function(form){
545
return Ext.lib.Ajax.serializeForm(form);