File Uploads
+ * # 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 @@ -32,8 +31,8 @@ If you are unsure which license is appropriate for your use, please contact the * 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. + * 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. @@ -60,23 +59,39 @@ Ext.define('Ext.data.Connection', { password: '', /** - * @cfg {Boolean} disableCaching (Optional) True to add a unique cache-buster param to GET requests. (defaults to true) + * @cfg {Boolean} disableCaching + * True to add a unique cache-buster param to GET requests. */ disableCaching: true, /** - * @cfg {String} disableCachingParam (Optional) Change the parameter which is sent went disabling caching - * through a cache buster. Defaults to '_dc' + * @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 (Optional) The timeout in milliseconds to be used for requests. (defaults to 30000) + * @cfg {Number} timeout + * The timeout in milliseconds to be used for requests. */ timeout : 30000, /** - * @cfg {Object} extraParams (Optional) Any parameters to be appended to the request. + * @cfg {Object} extraParams + * Any parameters to be appended to the request. */ useDefaultHeader : true, @@ -92,29 +107,27 @@ Ext.define('Ext.data.Connection', { /** * @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 * 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 * 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' @@ -124,101 +137,112 @@ Ext.define('Ext.data.Connection', { }, /** - *Sends an HTTP request to a remote server.
- *Important: Ajax server requests are asynchronous, and this call will + * 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 + * the method name is case-sensitive and should be all caps. + * + * @param {Function} options.callback The function to be called upon receipt of the HTTP response. + * The callback is called regardless of success or failure and is passed the following parameters: + * @param {Object} options.callback.options The parameter to the request call. + * @param {Boolean} options.callback.success True if the request succeeded. + * @param {Object} options.callback.response The XMLHttpRequest object containing the response data. + * See [www.w3.org/TR/XMLHttpRequest/](http://www.w3.org/TR/XMLHttpRequest/) for details about + * accessing elements of the response. + * + * @param {Function} options.success The function to be called upon success of the request. + * The callback is passed the following parameters: + * @param {Object} options.success.response The XMLHttpRequest object containing the response data. + * @param {Object} options.success.options The parameter to the request call. + * + * @param {Function} options.failure The function to be called upon success of the request. + * The callback is passed the following parameters: + * @param {Object} options.failure.response The XMLHttpRequest object containing the response data. + * @param {Object} options.failure.options The parameter to the request call. + * + * @param {Object} options.scope The scope in which to execute the callbacks: The "this" object for + * the callback function. If the `url`, or `params` options were specified as functions from which to + * draw values, then this also serves as the scope for those function calls. Defaults to the browser + * window. + * + * @param {Number} options.timeout The timeout in milliseconds to be used for this request. + * Defaults to 30 seconds. + * + * @param {Ext.Element/HTMLElement/String} options.form The `
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 {Object} request The request object. This may be used - * to cancel the request. + * DOM `