X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/b37ceabb82336ee82757cd32efe353cfab8ec267..HEAD:/docs/source/Connection.html?ds=sidebyside diff --git a/docs/source/Connection.html b/docs/source/Connection.html index a180efc8..6f9befb2 100644 --- a/docs/source/Connection.html +++ b/docs/source/Connection.html @@ -1,360 +1,352 @@ +
- +/*! - * Ext JS Library 3.2.2 - * Copyright(c) 2006-2010 Ext JS, Inc. - * licensing@extjs.com - * http://www.extjs.com/license + +/** + * The Connection class encapsulates a connection to the page's originating domain, allowing requests to be made either + * to a configured URL, or to a URL specified at request time. + * + * Requests made by this class are asynchronous, and will return immediately. No data from the server will be available + * to the statement immediately following the {@link #request} call. To process returned data, use a success callback + * in the request options object, or an {@link #requestcomplete event listener}. + * + * # File Uploads + * + * File uploads are not performed using normal "Ajax" techniques, that is they are not performed using XMLHttpRequests. + * Instead the form is submitted in the standard manner with the DOM <form> element temporarily modified to have its + * target set to refer to a dynamically generated, hidden <iframe> which is inserted into the document but removed + * after the return data has been gathered. + * + * The server response is parsed by the browser to create the document for the IFRAME. If the server is using JSON to + * send the return object, then the Content-Type header must be set to "text/html" in order to tell the browser to + * insert the text unchanged into the document body. + * + * Characters which are significant to an HTML parser must be sent as HTML entities, so encode `<` as `<`, `&` as + * `&` etc. + * + * The response text is retrieved from the document, and a fake XMLHttpRequest object is created containing a + * responseText property in order to conform to the requirements of event handlers and callbacks. + * + * Be aware that file upload packets are sent with the content type multipart/form and some server technologies + * (notably JEE) may require some custom processing in order to retrieve parameter names and parameter values from the + * packet content. + * + * Also note that it's not possible to check the response code of the hidden iframe, so the success handler will ALWAYS fire. */ -(function(){ - var BEFOREREQUEST = "beforerequest", - REQUESTCOMPLETE = "requestcomplete", - REQUESTEXCEPTION = "requestexception", - UNDEFINED = undefined, - LOAD = 'load', - POST = 'POST', - GET = 'GET', - WINDOW = window; - - /** - * @class Ext.data.Connection - * @extends Ext.util.Observable - *The class encapsulates a connection to the page's originating domain, allowing requests to be made - * either to a configured URL, or to a URL specified at request time.
- *Requests made by this class are asynchronous, and will return immediately. No data from - * the server will be available to the statement immediately following the {@link #request} call. - * To process returned data, use a - * success callback - * in the request options object, - * or an {@link #requestcomplete event listener}.
- *File Uploads
File uploads are not performed using normal "Ajax" techniques, that - * is they are not performed using XMLHttpRequests. Instead the form is submitted in the standard - * manner with the DOM <form> element temporarily modified to have its - * target set to refer - * to a dynamically generated, hidden <iframe> which is inserted into the document - * but removed after the return data has been gathered. - *The server response is parsed by the browser to create the document for the IFRAME. If the - * server is using JSON to send the return object, then the - * Content-Type header - * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.
- *Characters which are significant to an HTML parser must be sent as HTML entities, so encode - * "<" as "<", "&" as "&" etc.
- *The response text is retrieved from the document, and a fake XMLHttpRequest object - * is created containing a responseText property in order to conform to the - * requirements of event handlers and callbacks.
- *Be aware that file upload packets are sent with the content type multipart/form - * and some server technologies (notably JEE) may require some custom processing in order to - * retrieve parameter names and parameter values from the packet content.
- *Also note that it's not possible to check the response code of the hidden iframe, so the success handler will ALWAYS fire.
- * @constructor - * @param {Object} config a configuration object. +Ext.define('Ext.data.Connection', { + mixins: { + observable: 'Ext.util.Observable' + }, + + statics: { + requestId: 0 + }, + + url: null, + async: true, + method: null, + username: '', + password: '', + + /** + * @cfg {Boolean} disableCaching + * True to add a unique cache-buster param to GET requests. + */ + disableCaching: true, + + /** + * @cfg {Boolean} withCredentials + * True to set `withCredentials = true` on the XHR object + */ + withCredentials: false, + + /** + * @cfg {Boolean} cors + * True to enable CORS support on the XHR object. Currently the only effect of this option + * is to use the XDomainRequest object instead of XMLHttpRequest if the browser is IE8 or above. + */ + cors: false, + + /** + * @cfg {String} disableCachingParam + * Change the parameter which is sent went disabling caching through a cache buster. + */ + disableCachingParam: '_dc', + + /** + * @cfg {Number} timeout + * The timeout in milliseconds to be used for requests. */ - Ext.data.Connection = function(config){ + timeout : 30000, + + /** + * @cfg {Object} extraParams + * Any parameters to be appended to the request. + */ + + useDefaultHeader : true, + defaultPostHeader : 'application/x-www-form-urlencoded; charset=UTF-8', + useDefaultXhrHeader : true, + defaultXhrHeader : 'XMLHttpRequest', + + constructor : function(config) { + config = config || {}; Ext.apply(this, config); + this.addEvents( - /** - * @event beforerequest + /** + * @event beforerequest * Fires before a network request is made to retrieve a data object. - * @param {Connection} conn This Connection object. + * @param {Ext.data.Connection} conn This Connection object. * @param {Object} options The options config object passed to the {@link #request} method. */ - BEFOREREQUEST, - /** - * @event requestcomplete + 'beforerequest', + /** + * @event requestcomplete * Fires if the request was successfully completed. - * @param {Connection} conn This Connection object. + * @param {Ext.data.Connection} conn This Connection object. * @param {Object} response The XHR object containing the response data. - * See The XMLHttpRequest Object - * for details. + * See [The XMLHttpRequest Object](http://www.w3.org/TR/XMLHttpRequest/) for details. * @param {Object} options The options config object passed to the {@link #request} method. */ - REQUESTCOMPLETE, - /** - * @event requestexception + 'requestcomplete', + /** + * @event requestexception * Fires if an error HTTP status was returned from the server. - * See HTTP Status Code Definitions + * See [HTTP Status Code Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) * for details of HTTP status codes. - * @param {Connection} conn This Connection object. + * @param {Ext.data.Connection} conn This Connection object. * @param {Object} response The XHR object containing the response data. - * See The XMLHttpRequest Object - * for details. + * See [The XMLHttpRequest Object](http://www.w3.org/TR/XMLHttpRequest/) for details. * @param {Object} options The options config object passed to the {@link #request} method. */ - REQUESTEXCEPTION + 'requestexception' ); - Ext.data.Connection.superclass.constructor.call(this); - }; - - Ext.extend(Ext.data.Connection, Ext.util.Observable, { - /** - * @cfg {String} url (Optional)The default URL to be used for requests to the server. Defaults to undefined.
- *The
- */ - /** - * @cfg {Object} extraParams (Optional) An object containing properties which are used as - * extra parameters to each request made by this object. (defaults to undefined) - */ - /** - * @cfg {Object} defaultHeaders (Optional) An object containing request headers which are added - * to each request made by this object. (defaults to undefined) - */ - /** - * @cfg {String} method (Optional) The default HTTP method to be used for requests. - * (defaults to undefined; if not set, but {@link #request} params are present, POST will be used; - * otherwise, GET will be used.) - */ - /** - * @cfg {Number} timeout (Optional) The timeout in milliseconds to be used for requests. (defaults to 30000) - */ - timeout : 30000, - /** - * @cfg {Boolean} autoAbort (Optional) Whether this request should abort any pending requests. (defaults to false) - * @type Boolean - */ - autoAbort:false, - - /** - * @cfg {Boolean} disableCaching (Optional) True to add a unique cache-buster param to GET requests. (defaults to true) - * @type Boolean - */ - disableCaching: true, - - /** - * @cfg {String} disableCachingParam (Optional) Change the parameter which is sent went disabling caching - * through a cache buster. Defaults to '_dc' - * @type String - */ - disableCachingParam: '_dc', - - /** - *url
config may be a function which returns the URL to use for the Ajax request. The scope - * (this
reference) of the function is thescope
option passed to the {@link #request} method.Sends an HTTP request to a remote server.
- *Important: Ajax server requests are asynchronous, and this call will - * return before the response has been received. Process any returned data - * in a callback function.
- *- *-Ext.Ajax.request({ - url: 'ajax_demo/sample.json', - success: function(response, opts) { - var obj = Ext.decode(response.responseText); - console.dir(obj); - }, - failure: function(response, opts) { - console.log('server-side failure with status code ' + response.status); - } -}); - *
To execute a callback function in the correct scope, use the scope option.
- * @param {Object} options An object which may contain the following properties:
True if the form object is a file upload (will be set automatically if the form was - * configured with enctype "multipart/form-data").
- *File uploads are not performed using normal "Ajax" techniques, that is they are not - * performed using XMLHttpRequests. Instead the form is submitted in the standard manner with the - * DOM <form> element temporarily modified to have its - * target set to refer - * to a dynamically generated, hidden <iframe> which is inserted into the document - * but removed after the return data has been gathered.
- *The server response is parsed by the browser to create the document for the IFRAME. If the - * server is using JSON to send the return object, then the - * Content-Type header - * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.
- *The response text is retrieved from the document, and a fake XMLHttpRequest object - * is created containing a responseText property in order to conform to the - * requirements of event handlers and callbacks.
- *Be aware that file upload packets are sent with the content type multipart/form - * and some server technologies (notably JEE) may require some custom processing in order to - * retrieve parameter names and parameter values from the packet content.
- *The options object may also contain any other property which might be needed to perform - * postprocessing in a callback because it is passed to callback functions.
- * @return {Number} transactionId The id of the server transaction. This may be used - * to cancel the request. - */ - request : function(o){ - var me = this; - if(me.fireEvent(BEFOREREQUEST, me, o)){ - if (o.el) { - if(!Ext.isEmpty(o.indicatorText)){ - me.indicatorText = 'The global Ajax request class that provides a simple way to make Ajax requests - * with maximum flexibility.
- *Since Ext.Ajax is a singleton, you can set common properties/events for it once - * and override them at the request function level only if necessary.
- *Common Properties you may want to set are:
-// Default headers to pass in every request
-Ext.Ajax.defaultHeaders = {
- 'Powered-By': 'Ext'
-};
- *
- *
- * Common Events you may want to set are:
-// Example: show a spinner during all Ajax requests
-Ext.Ajax.on('beforerequest', this.showSpinner, this);
-Ext.Ajax.on('requestcomplete', this.hideSpinner, this);
-Ext.Ajax.on('requestexception', this.hideSpinner, this);
- *
- *
- * An example request:
- *
-// Basic request
-Ext.Ajax.{@link Ext.data.Connection#request request}({
- url: 'foo.php',
- success: someFn,
- failure: otherFn,
- headers: {
- 'my-header': 'foo'
- },
- params: { foo: 'bar' }
-});
+ //</debug>
-// Simple ajax form submission
-Ext.Ajax.{@link Ext.data.Connection#request request}({
- form: 'some-form',
- params: 'foo=bar'
-});
- *
- *
- * @singleton
- */
-Ext.Ajax = new Ext.data.Connection({
- /**
- * @cfg {String} url @hide
+ // check for xml or json data, and make sure json data is encoded
+ data = options.rawData || options.xmlData || jsonData || null;
+ if (jsonData && !Ext.isPrimitive(jsonData)) {
+ data = Ext.encode(data);
+ }
+
+ // make sure params are a url encoded string and include any extraParams if specified
+ if (Ext.isObject(params)) {
+ params = Ext.Object.toQueryString(params);
+ }
+
+ if (Ext.isObject(extraParams)) {
+ extraParams = Ext.Object.toQueryString(extraParams);
+ }
+
+ params = params + ((extraParams) ? ((params) ? '&' : '') + extraParams : '');
+
+ urlParams = Ext.isObject(urlParams) ? Ext.Object.toQueryString(urlParams) : urlParams;
+
+ params = this.setupParams(options, params);
+
+ // decide the proper method for this request
+ method = (options.method || me.method || ((params || data) ? 'POST' : 'GET')).toUpperCase();
+ this.setupMethod(options, method);
+
+
+ disableCache = options.disableCaching !== false ? (options.disableCaching || me.disableCaching) : false;
+ // if the method is get append date to prevent caching
+ if (method === 'GET' && disableCache) {
+ url = Ext.urlAppend(url, (options.disableCachingParam || me.disableCachingParam) + '=' + (new Date().getTime()));
+ }
+
+ // if the method is get or there is json/xml data append the params to the url
+ if ((method == 'GET' || data) && params) {
+ url = Ext.urlAppend(url, params);
+ params = null;
+ }
+
+ // allow params to be forced into the url
+ if (urlParams) {
+ url = Ext.urlAppend(url, urlParams);
+ }
+
+ return {
+ url: url,
+ method: method,
+ data: data || params || null
+ };
+ },
+
+ /**
+ * Template method for overriding url
+ * @template
+ * @private
+ * @param {Object} options
+ * @param {String} url
+ * @return {String} The modified url
*/
- /**
- * @cfg {Object} extraParams @hide
+ setupUrl: function(options, url){
+ var form = this.getForm(options);
+ if (form) {
+ url = url || form.action;
+ }
+ return url;
+ },
+
+
+ /**
+ * Template method for overriding params
+ * @template
+ * @private
+ * @param {Object} options
+ * @param {String} params
+ * @return {String} The modified params
+ */
+ setupParams: function(options, params) {
+ var form = this.getForm(options),
+ serializedForm;
+ if (form && !this.isFormUpload(options)) {
+ serializedForm = Ext.Element.serializeForm(form);
+ params = params ? (params + '&' + serializedForm) : serializedForm;
+ }
+ return params;
+ },
+
+ /**
+ * Template method for overriding method
+ * @template
+ * @private
+ * @param {Object} options
+ * @param {String} method
+ * @return {String} The modified method
*/
- /**
- * @cfg {Object} defaultHeaders @hide
+ setupMethod: function(options, method){
+ if (this.isFormUpload(options)) {
+ return 'POST';
+ }
+ return method;
+ },
+
+ /**
+ * Setup all the headers for the request
+ * @private
+ * @param {Object} xhr The xhr object
+ * @param {Object} options The options for the request
+ * @param {Object} data The data for the request
+ * @param {Object} params The params for the request
*/
- /**
- * @cfg {String} method (Optional) @hide
+ setupHeaders: function(xhr, options, data, params){
+ var me = this,
+ headers = Ext.apply({}, options.headers || {}, me.defaultHeaders || {}),
+ contentType = me.defaultPostHeader,
+ jsonData = options.jsonData,
+ xmlData = options.xmlData,
+ key,
+ header;
+
+ if (!headers['Content-Type'] && (data || params)) {
+ if (data) {
+ if (options.rawData) {
+ contentType = 'text/plain';
+ } else {
+ if (xmlData && Ext.isDefined(xmlData)) {
+ contentType = 'text/xml';
+ } else if (jsonData && Ext.isDefined(jsonData)) {
+ contentType = 'application/json';
+ }
+ }
+ }
+ headers['Content-Type'] = contentType;
+ }
+
+ if (me.useDefaultXhrHeader && !headers['X-Requested-With']) {
+ headers['X-Requested-With'] = me.defaultXhrHeader;
+ }
+ // set up all the request headers on the xhr object
+ try{
+ for (key in headers) {
+ if (headers.hasOwnProperty(key)) {
+ header = headers[key];
+ xhr.setRequestHeader(key, header);
+ }
+
+ }
+ } catch(e) {
+ me.fireEvent('exception', key, header);
+ }
+ return headers;
+ },
+
+ /**
+ * Creates the appropriate XHR transport for the browser.
+ * @private
*/
- /**
- * @cfg {Number} timeout (Optional) @hide
+ getXhrInstance: (function(){
+ var options = [function(){
+ return new XMLHttpRequest();
+ }, function(){
+ return new ActiveXObject('MSXML2.XMLHTTP.3.0');
+ }, function(){
+ return new ActiveXObject('MSXML2.XMLHTTP');
+ }, function(){
+ return new ActiveXObject('Microsoft.XMLHTTP');
+ }], i = 0,
+ len = options.length,
+ xhr;
+
+ for(; i < len; ++i) {
+ try{
+ xhr = options[i];
+ xhr();
+ break;
+ }catch(e){}
+ }
+ return xhr;
+ })(),
+
+ /**
+ * Determines whether this object has a request outstanding.
+ * @param {Object} [request] Defaults to the last transaction
+ * @return {Boolean} True if there is an outstanding request.
*/
- /**
- * @cfg {Boolean} autoAbort (Optional) @hide
+ isLoading : function(request) {
+ if (!request) {
+ request = this.getLatest();
+ }
+ if (!(request && request.xhr)) {
+ return false;
+ }
+ // if there is a connection and readyState is not 0 or 4
+ var state = request.xhr.readyState;
+ return !(state === 0 || state == 4);
+ },
+
+ /**
+ * Aborts an active request.
+ * @param {Object} [request] Defaults to the last request
*/
+ abort : function(request) {
+ var me = this;
+
+ if (!request) {
+ request = me.getLatest();
+ }
+
+ if (request && me.isLoading(request)) {
+ /*
+ * Clear out the onreadystatechange here, this allows us
+ * greater control, the browser may/may not fire the function
+ * depending on a series of conditions.
+ */
+ request.xhr.onreadystatechange = null;
+ request.xhr.abort();
+ me.clearTimeout(request);
+ if (!request.timedout) {
+ request.aborted = true;
+ }
+ me.onComplete(request);
+ me.cleanup(request);
+ }
+ },
- /**
- * @cfg {Boolean} disableCaching (Optional) @hide
+ /**
+ * Aborts all active requests
*/
+ abortAll: function(){
+ var requests = this.requests,
+ id;
- /**
- * @property disableCaching
- * True to add a unique cache-buster param to GET requests. (defaults to true)
- * @type Boolean
+ for (id in requests) {
+ if (requests.hasOwnProperty(id)) {
+ this.abort(requests[id]);
+ }
+ }
+ },
+
+ /**
+ * Gets the most recent request
+ * @private
+ * @return {Object} The request. Null if there is no recent request
*/
- /**
- * @property url
- * The default URL to be used for requests to the server. (defaults to undefined)
- * If the server receives all requests through one URL, setting this once is easier than
- * entering it on every request.
- * @type String
+ getLatest: function(){
+ var id = this.latestId,
+ request;
+
+ if (id) {
+ request = this.requests[id];
+ }
+ return request || null;
+ },
+
+ /**
+ * Fires when the state of the xhr changes
+ * @private
+ * @param {Object} request The request
*/
- /**
- * @property extraParams
- * An object containing properties which are used as extra parameters to each request made
- * by this object (defaults to undefined). Session information and other data that you need
- * to pass with each request are commonly put here.
- * @type Object
+ onStateChange : function(request) {
+ if (request.xhr.readyState == 4) {
+ this.clearTimeout(request);
+ this.onComplete(request);
+ this.cleanup(request);
+ }
+ },
+
+ /**
+ * Clears the timeout on the request
+ * @private
+ * @param {Object} The request
*/
- /**
- * @property defaultHeaders
- * An object containing request headers which are added to each request made by this object
- * (defaults to undefined).
- * @type Object
+ clearTimeout: function(request){
+ clearTimeout(request.timeout);
+ delete request.timeout;
+ },
+
+ /**
+ * Cleans up any left over information from the request
+ * @private
+ * @param {Object} The request
*/
- /**
- * @property method
- * The default HTTP method to be used for requests. Note that this is case-sensitive and
- * should be all caps (defaults to undefined; if not set but params are present will use
- * "POST", otherwise will use "GET".)
- * @type String
+ cleanup: function(request){
+ request.xhr = null;
+ delete request.xhr;
+ },
+
+ /**
+ * To be called when the request has come back from the server
+ * @private
+ * @param {Object} request
+ * @return {Object} The response
*/
- /**
- * @property timeout
- * The timeout in milliseconds to be used for requests. (defaults to 30000)
- * @type Number
+ onComplete : function(request) {
+ var me = this,
+ options = request.options,
+ result,
+ success,
+ response;
+
+ try {
+ result = me.parseStatus(request.xhr.status);
+ } catch (e) {
+ // in some browsers we can't access the status if the readyState is not 4, so the request has failed
+ result = {
+ success : false,
+ isException : false
+ };
+ }
+ success = result.success;
+
+ if (success) {
+ response = me.createResponse(request);
+ me.fireEvent('requestcomplete', me, response, options);
+ Ext.callback(options.success, options.scope, [response, options]);
+ } else {
+ if (result.isException || request.aborted || request.timedout) {
+ response = me.createException(request);
+ } else {
+ response = me.createResponse(request);
+ }
+ me.fireEvent('requestexception', me, response, options);
+ Ext.callback(options.failure, options.scope, [response, options]);
+ }
+ Ext.callback(options.callback, options.scope, [options, success, response]);
+ delete me.requests[request.id];
+ return response;
+ },
+
+ /**
+ * Checks if the response status was successful
+ * @param {Number} status The status code
+ * @return {Object} An object containing success/status state
*/
-
- /**
- * @property autoAbort
- * Whether a new request should abort any pending requests. (defaults to false)
- * @type Boolean
+ parseStatus: function(status) {
+ // see: https://prototype.lighthouseapp.com/projects/8886/tickets/129-ie-mangles-http-response-status-code-204-to-1223
+ status = status == 1223 ? 204 : status;
+
+ var success = (status >= 200 && status < 300) || status == 304,
+ isException = false;
+
+ if (!success) {
+ switch (status) {
+ case 12002:
+ case 12029:
+ case 12030:
+ case 12031:
+ case 12152:
+ case 13030:
+ isException = true;
+ break;
+ }
+ }
+ return {
+ success: success,
+ isException: isException
+ };
+ },
+
+ /**
+ * Creates the response object
+ * @private
+ * @param {Object} request
*/
- autoAbort : false,
+ createResponse : function(request) {
+ var xhr = request.xhr,
+ headers = {},
+ lines = xhr.getAllResponseHeaders ? xhr.getAllResponseHeaders().replace(/\r\n/g, '\n').split('\n') : [],
+ count = lines.length,
+ line, index, key, value, response;
+
+ while (count--) {
+ line = lines[count];
+ index = line.indexOf(':');
+ if(index >= 0) {
+ key = line.substr(0, index).toLowerCase();
+ if (line.charAt(index + 1) == ' ') {
+ ++index;
+ }
+ headers[key] = line.substr(index + 1);
+ }
+ }
- /**
- * Serialize the passed form into a url encoded string
- * @param {String/HTMLElement} form
- * @return {String}
+ request.xhr = null;
+ delete request.xhr;
+
+ response = {
+ request: request,
+ requestId : request.id,
+ status : xhr.status,
+ statusText : xhr.statusText,
+ getResponseHeader : function(header){ return headers[header.toLowerCase()]; },
+ getAllResponseHeaders : function(){ return headers; },
+ responseText : xhr.responseText,
+ responseXML : xhr.responseXML
+ };
+
+ // If we don't explicitly tear down the xhr reference, IE6/IE7 will hold this in the closure of the
+ // functions created with getResponseHeader/getAllResponseHeaders
+ xhr = null;
+ return response;
+ },
+
+ /**
+ * Creates the exception object
+ * @private
+ * @param {Object} request
*/
- serializeForm : function(form){
- return Ext.lib.Ajax.serializeForm(form);
+ createException : function(request) {
+ return {
+ request : request,
+ requestId : request.id,
+ status : request.aborted ? -1 : 0,
+ statusText : request.aborted ? 'transaction aborted' : 'communication failure',
+ aborted: request.aborted,
+ timedout: request.timedout
+ };
}
});
-
+
-
\ No newline at end of file
+