/** * AjaxProxy is one of the most widely-used ways of getting data into your application. It uses AJAX * requests to load data from the server, usually to be placed into a {@link Ext.data.Store Store}. * Let's take a look at a typical setup. Here we're going to set up a Store that has an Ajax Proxy. * To prepare, we'll also set up a {@link Ext.data.Model Model}: * * Ext.define('User', { * extend: 'Ext.data.Model', * fields: ['id', 'name', 'email'] * }); * * // The Store contains the AjaxProxy as an inline configuration * var store = Ext.create('Ext.data.Store', { * model: 'User', * proxy: { * type: 'ajax', * url: 'users.json' * } * }); * * store.load(); * * Our example is going to load user data into a Store, so we start off by defining a * {@link Ext.data.Model Model} with the fields that we expect the server to return. Next we set up * the Store itself, along with a {@link Ext.data.Store#proxy proxy} configuration. * This configuration was automatically turned into an Ext.data.proxy.Ajax instance, with the url * we specified being passed into AjaxProxy's constructor. It's as if we'd done this: * * new Ext.data.proxy.Ajax({ * url: 'users.json', * model: 'User', * reader: 'json' * }); * * A couple of extra configurations appeared here - {@link #model} and {@link #reader}. These are * set by default when we create the proxy via the Store - the Store already knows about the Model, * and Proxy's default {@link Ext.data.reader.Reader Reader} is * {@link Ext.data.reader.Json JsonReader}. * * Now when we call store.load(), the AjaxProxy springs into action, making a request to the url * we configured ('users.json' in this case). As we're performing a read, it sends a GET request * to that url (see {@link #actionMethods} to customize this - by default any kind of read will be * sent as a GET request and any kind of write will be sent as a POST request). * * # Limitations * * AjaxProxy cannot be used to retrieve data from other domains. If your application is running * on http://domainA.com it cannot load data from http://domainB.com because browsers have * a built-in security policy that prohibits domains talking to each other via AJAX. * * If you need to read data from another domain and can't set up a proxy server (some software * that runs on your own domain's web server and transparently forwards requests to * http://domainB.com, making it look like they actually came from http://domainA.com), you can use * {@link Ext.data.proxy.JsonP} and a technique known as JSON-P (JSON with Padding), which can help * you get around the problem so long as the server on http://domainB.com is set up to support * JSON-P responses. See {@link Ext.data.proxy.JsonP JsonPProxy}'s introduction docs for more * details. * * # Readers and Writers * * AjaxProxy can be configured to use any type of {@link Ext.data.reader.Reader Reader} to decode * the server's response. If no Reader is supplied, AjaxProxy will default to using a * {@link Ext.data.reader.Json JsonReader}. Reader configuration can be passed in as a simple * object, which the Proxy automatically turns into a {@link Ext.data.reader.Reader Reader} * instance: * * var proxy = new Ext.data.proxy.Ajax({ * model: 'User', * reader: { * type: 'xml', * rootProperty: 'users' * } * }); * * proxy.getReader(); // returns an XmlReader instance based on the config we supplied * * # Url generation * * AjaxProxy automatically inserts any sorting, filtering, paging and grouping options into the url * it generates for each request. These are controlled with the following configuration options: * * - {@link #pageParam} - controls how the page number is sent to the server (see also * {@link #startParam} and {@link #limitParam}) * - {@link #sortParam} - controls how sort information is sent to the server * - {@link #groupParam} - controls how grouping information is sent to the server * - {@link #filterParam} - controls how filter information is sent to the server * * Each request sent by AjaxProxy is described by an {@link Ext.data.operation.Operation Operation}. * To see how we can customize the generated urls, let's say we're loading the Proxy * with the following Operation: * * var proxy = new Ext.data.proxy.Ajax({ * url: '/users' * }); * * var operation = proxy.createOperation('read', { * page: 2 * }); * * Now we'll issue the request for this Operation by calling {@link #read}: * * proxy.read(operation); // GET /users?page=2 * * Easy enough - the Proxy just copied the page property from the Operation. We can customize * how this page data is sent to the server: * * var proxy = new Ext.data.proxy.Ajax({ * url: '/users', * pageParam: 'pageNumber' * }); * * proxy.read(operation); // GET /users?pageNumber=2 * * Alternatively, our Operation could have been configured to send start and limit parameters * instead of page: * * var proxy = new Ext.data.proxy.Ajax({ * url: '/users' * }); * * var operation = proxy.createOperation('read', { * start: 50, * limit: 25 * }); * * proxy.read(operation); // GET /users?start=50&limit;=25 * * Again we can customize this url: * * var proxy = new Ext.data.proxy.Ajax({ * url: '/users', * startParam: 'startIndex', * limitParam: 'limitIndex' * }); * * proxy.read(operation); // GET /users?startIndex=50&limitIndex;=25 * * AjaxProxy will also send sort and filter information to the server. Let's take a look at how * this looks with a more expressive Operation object: * * var operation = proxy.createOperation('read', { * sorters: [ * new Ext.util.Sorter({ * property: 'name', * direction: 'ASC' * }), * new Ext.util.Sorter({ * property: 'age', * direction: 'DESC' * }) * ], * filters: [ * new Ext.util.Filter({ * property: 'eyeColor', * value: 'brown' * }) * ] * }); * * This is the type of object that is generated internally when loading a * {@link Ext.data.Store Store} with sorters and filters defined. By default the AjaxProxy will * JSON encode the sorters and filters, resulting in something like this (note that the url * is escaped before sending the request, but is left unescaped here for clarity): * * var proxy = new Ext.data.proxy.Ajax({ * url: '/users' * }); * * // GET /users?sort=[{"property":"name","direction":"ASC"}, * {"property":"age","direction":"DESC"}] * &filter;=[{"property":"eyeColor","value":"brown"}] * proxy.read(operation); * * We can again customize how this is created by supplying a few configuration options. Let's say * our server is set up to receive sorting information is a format like "sortBy=name#ASC,age#DESC". * We can configure AjaxProxy to provide that format like this: * * var proxy = new Ext.data.proxy.Ajax({ * url: '/users', * sortParam: 'sortBy', * filterParam: 'filterBy', * * // our custom implementation of sorter encoding - * // turns our sorters into "name#ASC,age#DESC" * encodeSorters: function(sorters) { * var length = sorters.length, * sortStrs = [], * sorter, i; * * for (i = 0; i < length; i++) { * sorter = sorters[i]; * * sortStrs[i] = sorter.property + '#' + sorter.direction * } * * return sortStrs.join(","); * } * }); * * // GET /users?sortBy=name#ASC,age#DESC&filterBy;=[{"property":"eyeColor","value":"brown"}] * proxy.read(operation); * * We can also provide a custom {@link #encodeFilters} function to encode our filters. * * # Debugging your Ajax Proxy * * If the data is not being loaded into the store as expected, it could be due to a mismatch * between the the way that the {@link #reader} is configured, and the shape of the incoming data. * * To debug from the point that your data arrives back from the network, set a breakpoint inside * the callback function created in the `createRequestCallback` method of the Ajax Proxy class, * and follow the data to where the {@link #reader} attempts to consume it. * * @constructor * Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the Store's * call to {@link Ext.data.Store#method-load load} will override any specified callback and params * options. In this case, use the {@link Ext.data.Store Store}'s events to modify parameters, * or react to loading events. * * @param {Object} config (optional) Config object. * If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make * the request. */Ext.define('Ext.data.proxy.Ajax', { requires: ['Ext.Ajax'], extend: 'Ext.data.proxy.Server', alias: 'proxy.ajax', alternateClassName: ['Ext.data.HttpProxy', 'Ext.data.AjaxProxy'], isAjaxProxy: true, // Keep a default copy of the action methods here. Ideally could just null // out actionMethods and just check if it exists & has a property, otherwise // fallback to the default. But at the moment it's defined as a public property, // so we need to be able to maintain the ability to modify/access it. defaultActionMethods: { create: 'POST', read: 'GET', update: 'POST', destroy: 'POST' }, config: { /** * @cfg {Boolean} binary * True to request binary data from the server. This feature requires * the use of a binary reader such as {@link Ext.data.amf.Reader AMF Reader} */ binary: false, /** * @cfg {Object} [headers] * Any headers to add to the Ajax request. * * example: * * proxy: { * headers: {'Content-Type': "text/plain" } * ... * } */ headers: undefined, /** * @cfg {Boolean} paramsAsJson * Set to `true` to have any request parameters sent as * {@link Ext.data.Connection#method-request jsonData} where they can be parsed from the * raw request. By default, parameters are sent via the * {@link Ext.data.Connection#method-request params} property. * **Note**: This setting does not apply when the request is sent as a 'GET' request. * See {@link #cfg!actionMethods} for controlling the HTTP verb that is used when sending * requests. */ paramsAsJson: false, /** * @cfg {Boolean} withCredentials * This configuration is sometimes necessary when using cross-origin resource sharing. * @accessor */ withCredentials: false, /** * @cfg {Boolean} useDefaultXhrHeader * Set this to false to not send the default Xhr header (X-Requested-With) with every * request. This should be set to false when making CORS (cross-domain) requests. * @accessor */ useDefaultXhrHeader: true, /** * @cfg {String} username * Most oData feeds require basic HTTP authentication. This configuration allows * you to specify the username. * @accessor */ username: null, /** * @cfg {String} password * Most oData feeds require basic HTTP authentication. This configuration allows * you to specify the password. * @accessor */ password: null, /** * @cfg {Object} actionMethods * Mapping of action name to HTTP request method. In the basic AjaxProxy these are set to * 'GET' for 'read' actions and 'POST' for 'create', 'update' and 'destroy' actions. The * {@link Ext.data.proxy.Rest} maps these to the correct RESTful methods. */ actionMethods: { create: 'POST', read: 'GET', update: 'POST', destroy: 'POST' } }, doRequest: function(operation) { var me = this, writer = me.getWriter(), request = me.buildRequest(operation), method = me.getMethod(request), jsonData, params; if (writer && operation.allowWrite()) { request = writer.write(request); } request.setConfig({ binary: me.getBinary(), headers: me.getHeaders(), timeout: me.getTimeout(), scope: me, callback: me.createRequestCallback(request, operation), method: method, useDefaultXhrHeader: me.getUseDefaultXhrHeader(), disableCaching: false // explicitly set it to false, ServerProxy handles caching }); if (me.responseType != null && Ext.supports.XHR2) { request.setResponseType(me.responseType); } if (method.toUpperCase() !== 'GET' && me.getParamsAsJson()) { params = request.getParams(); if (params) { jsonData = request.getJsonData(); if (jsonData) { jsonData = Ext.Object.merge({}, jsonData, params); } else { jsonData = params; } request.setJsonData(jsonData); request.setParams(undefined); } } if (me.getWithCredentials()) { request.setWithCredentials(true); request.setUsername(me.getUsername()); request.setPassword(me.getPassword()); } return me.sendRequest(request); }, /** * Fires a request * @param {Ext.data.Request} request The request * @return {Ext.data.Request} The request * @private */ sendRequest: function(request) { request.setRawRequest(Ext.Ajax.request(request.getCurrentConfig())); this.lastRequest = request; return request; }, /** * Aborts a running request. * @param {Ext.data.Request} [request] The request to abort. If not passed, the most recent * active request will be aborted. */ abort: function(request) { request = request || this.lastRequest; if (request) { Ext.Ajax.abort(request.getRawRequest()); } }, /** * Returns the HTTP method name for a given request. By default this returns based on a lookup * on {@link #cfg!actionMethods}. * @param {Ext.data.Request} request The request object * @return {String} The HTTP method to use (should be one of 'GET', 'POST', 'PUT' or 'DELETE') */ getMethod: function(request) { var actions = this.getActionMethods(), action = request.getAction(), method; if (actions) { method = actions[action]; } return method || this.defaultActionMethods[action]; }, /** * @private * TODO: This is currently identical to the JsonPProxy version except for the return function's * signature. There is a lot of code duplication inside the returned function so we need to * find a way to DRY this up. * @param {Ext.data.Request} request The Request object * @param {Ext.data.operation.Operation} operation The Operation being executed * @return {Function} The callback function */ createRequestCallback: function(request, operation) { return function(options, success, response) { var me = this; if (request === me.lastRequest) { me.lastRequest = null; } if (!me.destroying && !me.destroyed) { me.processResponse(success, operation, request, response); } }; }, destroy: function() { this.lastRequest = null; this.callParent(); }});