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 AjaxProxy. 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 = new 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 #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 + * + * 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 AjaxProxy. 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 + * 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',
- root: 'users'
- }
-});
-
-proxy.getReader(); //returns an {@link Ext.data.reader.Xml 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:
- * - *Each request sent by AjaxProxy is described by an {@link Ext.data.Operation Operation}. To see how we can - * customize the generated urls, let's say we're loading the Proxy with the following Operation:
- * -
-var operation = new Ext.data.Operation({
- action: 'read',
- page : 2
-});
-Now we'll issue the request for this Operation by calling {@link #read}:
- * -
-var proxy = new Ext.data.proxy.Ajax({
- url: '/users'
-});
-
-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',
- pagePage: '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 operation = new Ext.data.Operation({
- action: 'read',
- start : 50,
- limit : 25
-});
-
-var proxy = new Ext.data.proxy.Ajax({
- url: '/users'
-});
-
-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 = new Ext.data.Operation({
- action: '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'
-});
-
-proxy.read(operation); //GET /users?sort=[{"property":"name","direction":"ASC"},{"property":"age","direction":"DESC"}]&filter=[{"property":"eyeColor","value":"brown"}]
-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(",");
- }
- });
-
- proxy.read(operation); //GET /users?sortBy=name#ASC,age#DESC&filterBy=[{"property":"eyeColor","value":"brown"}]
- We can also provide a custom {@link #encodeFilters} function to encode our filters.
- * + * 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', + * root: 'users' + * } + * }); + * + * proxy.getReader(); //returns an {@link Ext.data.reader.Xml 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}. To see how we can customize + * the generated urls, let's say we're loading the Proxy with the following Operation: + * + * var operation = new Ext.data.Operation({ + * action: 'read', + * page : 2 + * }); + * + * Now we'll issue the request for this Operation by calling {@link #read}: + * + * var proxy = new Ext.data.proxy.Ajax({ + * url: '/users' + * }); + * + * 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', + * pagePage: '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 operation = new Ext.data.Operation({ + * action: 'read', + * start : 50, + * limit : 25 + * }); + * + * var proxy = new Ext.data.proxy.Ajax({ + * url: '/users' + * }); + * + * 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 = new Ext.data.Operation({ + * action: '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' + * }); + * + * proxy.read(operation); //GET /users?sort=[{"property":"name","direction":"ASC"},{"property":"age","direction":"DESC"}]&filter;=[{"property":"eyeColor","value":"brown"}] + * + * 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(","); + * } + * }); + * + * proxy.read(operation); //GET /users?sortBy=name#ASC,age#DESC&filterBy;=[{"property":"eyeColor","value":"brown"}] + * + * We can also provide a custom {@link #encodeFilters} function to encode our filters. + * * @constructor - * - *Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the - * Store's call to {@link #load} will override any specified callback and params - * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters, - * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be - * used to pass parameters known at instantiation time.
- * - *If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make - * the request.
+ * 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#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.util.MixedCollection', 'Ext.Ajax'], @@ -252,9 +223,10 @@ Ext.define('Ext.data.proxy.Ajax', { alternateClassName: ['Ext.data.HttpProxy', 'Ext.data.AjaxProxy'], /** - * @property 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. + * @property {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', @@ -264,7 +236,8 @@ Ext.define('Ext.data.proxy.Ajax', { }, /** - * @cfg {Object} headers Any headers to add to the Ajax request. Defaults to undefined. + * @cfg {Object} headers + * Any headers to add to the Ajax request. Defaults to undefined. */ /** @@ -293,7 +266,8 @@ Ext.define('Ext.data.proxy.Ajax', { }, /** - * Returns the HTTP method name for a given request. By default this returns based on a lookup on {@link #actionMethods}. + * Returns the HTTP method name for a given request. By default this returns based on a lookup on + * {@link #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') */