1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-data.proxy.Ajax-method-constructor'><span id='Ext-data.proxy.Ajax'>/**
2 </span></span> * @author Ed Spencer
3 * @class Ext.data.proxy.Ajax
4 * @extends Ext.data.proxy.Server
6 * <p>AjaxProxy is one of the most widely-used ways of getting data into your application. It uses AJAX requests to
7 * load data from the server, usually to be placed into a {@link Ext.data.Store Store}. Let's take a look at a typical
8 * setup. Here we're going to set up a Store that has an AjaxProxy. To prepare, we'll also set up a
9 * {@link Ext.data.Model Model}:</p>
11 <pre><code>
13 extend: 'Ext.data.Model',
14 fields: ['id', 'name', 'email']
17 //The Store contains the AjaxProxy as an inline configuration
18 var store = new Ext.data.Store({
27 </code></pre>
29 * <p>Our example is going to load user data into a Store, so we start off by defining a {@link Ext.data.Model Model}
30 * with the fields that we expect the server to return. Next we set up the Store itself, along with a {@link #proxy}
31 * configuration. This configuration was automatically turned into an Ext.data.proxy.Ajax instance, with the url we
32 * specified being passed into AjaxProxy's constructor. It's as if we'd done this:</p>
34 <pre><code>
35 new Ext.data.proxy.Ajax({
40 </code></pre>
42 * <p>A couple of extra configurations appeared here - {@link #model} and {@link #reader}. These are set by default
43 * when we create the proxy via the Store - the Store already knows about the Model, and Proxy's default
44 * {@link Ext.data.reader.Reader Reader} is {@link Ext.data.reader.Json JsonReader}.</p>
46 * <p>Now when we call store.load(), the AjaxProxy springs into action, making a request to the url we configured
47 * ('users.json' in this case). As we're performing a read, it sends a GET request to that url (see {@link #actionMethods}
48 * 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
49 * POST request).</p>
51 * <p><u>Limitations</u></p>
53 * <p>AjaxProxy cannot be used to retrieve data from other domains. If your application is running on http://domainA.com
54 * it cannot load data from http://domainB.com because browsers have a built-in security policy that prohibits domains
55 * talking to each other via AJAX.</p>
57 * <p>If you need to read data from another domain and can't set up a proxy server (some software that runs on your own
58 * domain's web server and transparently forwards requests to http://domainB.com, making it look like they actually came
59 * from http://domainA.com), you can use {@link Ext.data.proxy.JsonP} and a technique known as JSON-P (JSON with
60 * Padding), which can help you get around the problem so long as the server on http://domainB.com is set up to support
61 * JSON-P responses. See {@link Ext.data.proxy.JsonP JsonPProxy}'s introduction docs for more details.</p>
63 * <p><u>Readers and Writers</u></p>
65 * <p>AjaxProxy can be configured to use any type of {@link Ext.data.reader.Reader Reader} to decode the server's response. If
66 * no Reader is supplied, AjaxProxy will default to using a {@link Ext.data.reader.Json JsonReader}. Reader configuration
67 * can be passed in as a simple object, which the Proxy automatically turns into a {@link Ext.data.reader.Reader Reader}
70 <pre><code>
71 var proxy = new Ext.data.proxy.Ajax({
79 proxy.getReader(); //returns an {@link Ext.data.reader.Xml XmlReader} instance based on the config we supplied
80 </code></pre>
82 * <p><u>Url generation</u></p>
84 * <p>AjaxProxy automatically inserts any sorting, filtering, paging and grouping options into the url it generates for
85 * each request. These are controlled with the following configuration options:</p>
87 * <ul style="list-style-type: disc; padding-left: 20px;">
88 * <li>{@link #pageParam} - controls how the page number is sent to the server
89 * (see also {@link #startParam} and {@link #limitParam})</li>
90 * <li>{@link #sortParam} - controls how sort information is sent to the server</li>
91 * <li>{@link #groupParam} - controls how grouping information is sent to the server</li>
92 * <li>{@link #filterParam} - controls how filter information is sent to the server</li>
95 * <p>Each request sent by AjaxProxy is described by an {@link Ext.data.Operation Operation}. To see how we can
96 * customize the generated urls, let's say we're loading the Proxy with the following Operation:</p>
98 <pre><code>
99 var operation = new Ext.data.Operation({
103 </code></pre>
105 * <p>Now we'll issue the request for this Operation by calling {@link #read}:</p>
107 <pre><code>
108 var proxy = new Ext.data.proxy.Ajax({
112 proxy.read(operation); //GET /users?page=2
113 </code></pre>
115 * <p>Easy enough - the Proxy just copied the page property from the Operation. We can customize how this page data is
116 * sent to the server:</p>
118 <pre><code>
119 var proxy = new Ext.data.proxy.Ajax({
121 pagePage: 'pageNumber'
124 proxy.read(operation); //GET /users?pageNumber=2
125 </code></pre>
127 * <p>Alternatively, our Operation could have been configured to send start and limit parameters instead of page:</p>
129 <pre><code>
130 var operation = new Ext.data.Operation({
136 var proxy = new Ext.data.proxy.Ajax({
140 proxy.read(operation); //GET /users?start=50&limit=25
141 </code></pre>
143 * <p>Again we can customize this url:</p>
145 <pre><code>
146 var proxy = new Ext.data.proxy.Ajax({
148 startParam: 'startIndex',
149 limitParam: 'limitIndex'
152 proxy.read(operation); //GET /users?startIndex=50&limitIndex=25
153 </code></pre>
155 * <p>AjaxProxy will also send sort and filter information to the server. Let's take a look at how this looks with a
156 * more expressive Operation object:</p>
158 <pre><code>
159 var operation = new Ext.data.Operation({
162 new Ext.util.Sorter({
166 new Ext.util.Sorter({
172 new Ext.util.Filter({
173 property: 'eyeColor',
178 </code></pre>
180 * <p>This is the type of object that is generated internally when loading a {@link Ext.data.Store Store} with sorters
181 * and filters defined. By default the AjaxProxy will JSON encode the sorters and filters, resulting in something like
182 * this (note that the url is escaped before sending the request, but is left unescaped here for clarity):</p>
184 <pre><code>
185 var proxy = new Ext.data.proxy.Ajax({
189 proxy.read(operation); //GET /users?sort=[{"property":"name","direction":"ASC"},{"property":"age","direction":"DESC"}]&filter=[{"property":"eyeColor","value":"brown"}]
190 </code></pre>
192 * <p>We can again customize how this is created by supplying a few configuration options. Let's say our server is set
193 * up to receive sorting information is a format like "sortBy=name#ASC,age#DESC". We can configure AjaxProxy to provide
194 * that format like this:</p>
196 <pre><code>
197 var proxy = new Ext.data.proxy.Ajax({
200 filterParam: 'filterBy',
202 //our custom implementation of sorter encoding - turns our sorters into "name#ASC,age#DESC"
203 encodeSorters: function(sorters) {
204 var length = sorters.length,
208 for (i = 0; i < length; i++) {
211 sortStrs[i] = sorter.property + '#' + sorter.direction
214 return sortStrs.join(",");
218 proxy.read(operation); //GET /users?sortBy=name#ASC,age#DESC&filterBy=[{"property":"eyeColor","value":"brown"}]
219 </code></pre>
221 * <p>We can also provide a custom {@link #encodeFilters} function to encode our filters.</p>
225 * <p>Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the
226 * Store's call to {@link #load} will override any specified <tt>callback</tt> and <tt>params</tt>
227 * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters,
228 * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be
229 * used to pass parameters known at instantiation time.</p>
231 * <p>If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make
232 * the request.</p>
234 Ext.define('Ext.data.proxy.Ajax', {
235 requires: ['Ext.util.MixedCollection', 'Ext.Ajax'],
236 extend: 'Ext.data.proxy.Server',
238 alternateClassName: ['Ext.data.HttpProxy', 'Ext.data.AjaxProxy'],
240 <span id='Ext-data.proxy.Ajax-property-actionMethods'> /**
241 </span> * @property actionMethods
242 * Mapping of action name to HTTP request method. In the basic AjaxProxy these are set to 'GET' for 'read' actions and 'POST'
243 * for 'create', 'update' and 'destroy' actions. The {@link Ext.data.proxy.Rest} maps these to the correct RESTful methods.
252 <span id='Ext-data.proxy.Ajax-cfg-headers'> /**
253 </span> * @cfg {Object} headers Any headers to add to the Ajax request. Defaults to <tt>undefined</tt>.
256 <span id='Ext-data.proxy.Ajax-method-doRequest'> /**
259 doRequest: function(operation, callback, scope) {
260 var writer = this.getWriter(),
261 request = this.buildRequest(operation, callback, scope);
263 if (operation.allowWrite()) {
264 request = writer.write(request);
268 headers : this.headers,
269 timeout : this.timeout,
271 callback : this.createRequestCallback(request, operation, callback, scope),
272 method : this.getMethod(request),
273 disableCaching: false // explicitly set it to false, ServerProxy handles caching
276 Ext.Ajax.request(request);
281 <span id='Ext-data.proxy.Ajax-method-getMethod'> /**
282 </span> * Returns the HTTP method name for a given request. By default this returns based on a lookup on {@link #actionMethods}.
283 * @param {Ext.data.Request} request The request object
284 * @return {String} The HTTP method to use (should be one of 'GET', 'POST', 'PUT' or 'DELETE')
286 getMethod: function(request) {
287 return this.actionMethods[request.action];
290 <span id='Ext-data.proxy.Ajax-method-createRequestCallback'> /**
292 * TODO: This is currently identical to the JsonPProxy version except for the return function's signature. There is a lot
293 * of code duplication inside the returned function so we need to find a way to DRY this up.
294 * @param {Ext.data.Request} request The Request object
295 * @param {Ext.data.Operation} operation The Operation being executed
296 * @param {Function} callback The callback function to be called when the request completes. This is usually the callback
297 * passed to doRequest
298 * @param {Object} scope The scope in which to execute the callback function
299 * @return {Function} The callback function
301 createRequestCallback: function(request, operation, callback, scope) {
304 return function(options, success, response) {
305 me.processResponse(success, operation, request, response, callback, scope);
309 //backwards compatibility, remove in Ext JS 5.0
310 Ext.data.HttpProxy = this;
312 </pre></pre></body></html>