3 * @class Ext.data.proxy.Server
4 * @extends Ext.data.proxy.Proxy
6 * <p>ServerProxy is a superclass of {@link Ext.data.proxy.JsonP JsonPProxy} and {@link Ext.data.proxy.Ajax AjaxProxy},
7 * and would not usually be used directly.</p>
9 * <p>ServerProxy should ideally be named HttpProxy as it is a superclass for all HTTP proxies - for Ext JS 4.x it has been
10 * called ServerProxy to enable any 3.x applications that reference the HttpProxy to continue to work (HttpProxy is now an
11 * alias of AjaxProxy).</p>
13 Ext.define('Ext.data.proxy.Server', {
14 extend: 'Ext.data.proxy.Proxy',
15 alias : 'proxy.server',
16 alternateClassName: 'Ext.data.ServerProxy',
17 uses : ['Ext.data.Request'],
20 * @cfg {String} url The URL from which to request the data object.
24 * @cfg {Object/String/Ext.data.reader.Reader} reader The Ext.data.reader.Reader to use to decode the server's response. This can
25 * either be a Reader instance, a config object or just a valid Reader type name (e.g. 'json', 'xml').
29 * @cfg {Object/String/Ext.data.writer.Writer} writer The Ext.data.writer.Writer to use to encode any request sent to the server.
30 * This can either be a Writer instance, a config object or just a valid Writer type name (e.g. 'json', 'xml').
34 * @cfg {String} pageParam The name of the 'page' parameter to send in a request. Defaults to 'page'. Set this to
35 * undefined if you don't want to send a page parameter
40 * @cfg {String} startParam The name of the 'start' parameter to send in a request. Defaults to 'start'. Set this
41 * to undefined if you don't want to send a start parameter
46 * @cfg {String} limitParam The name of the 'limit' parameter to send in a request. Defaults to 'limit'. Set this
47 * to undefined if you don't want to send a limit parameter
52 * @cfg {String} groupParam The name of the 'group' parameter to send in a request. Defaults to 'group'. Set this
53 * to undefined if you don't want to send a group parameter
58 * @cfg {String} sortParam The name of the 'sort' parameter to send in a request. Defaults to 'sort'. Set this
59 * to undefined if you don't want to send a sort parameter
64 * @cfg {String} filterParam The name of the 'filter' parameter to send in a request. Defaults to 'filter'. Set
65 * this to undefined if you don't want to send a filter parameter
67 filterParam: 'filter',
70 * @cfg {String} directionParam The name of the direction parameter to send in a request. <strong>This is only used when simpleSortMode is set to true.</strong>
73 directionParam: 'dir',
76 * @cfg {Boolean} simpleSortMode Enabling simpleSortMode in conjunction with remoteSort will only send one sort property and a direction when a remote sort is requested.
77 * The directionParam and sortParam will be sent with the property name and either 'ASC' or 'DESC'
79 simpleSortMode: false,
82 * @cfg {Boolean} noCache (optional) Defaults to true. Disable caching by adding a unique parameter
83 * name to the request.
88 * @cfg {String} cacheString The name of the cache param added to the url when using noCache (defaults to "_dc")
93 * @cfg {Number} timeout (optional) The number of milliseconds to wait for a response. Defaults to 30 seconds.
99 * Specific urls to call on CRUD action methods "read", "create", "update" and "destroy".
100 * Defaults to:<pre><code>
108 * <p>The url is built based upon the action being executed <tt>[load|create|save|destroy]</tt>
109 * using the commensurate <tt>{@link #api}</tt> property, or if undefined default to the
110 * configured {@link Ext.data.Store}.{@link Ext.data.proxy.Server#url url}.</p><br>
111 * <p>For example:</p>
114 load : '/controller/load',
115 create : '/controller/new',
116 save : '/controller/update',
117 destroy : '/controller/destroy_action'
120 * <p>If the specific URL for a given CRUD action is undefined, the CRUD action request
121 * will be directed to the configured <tt>{@link Ext.data.proxy.Server#url url}</tt>.</p>
127 constructor: function(config) {
130 config = config || {};
134 * Fires when the server returns an exception
135 * @param {Ext.data.proxy.Proxy} this
136 * @param {Object} response The response from the AJAX request
137 * @param {Ext.data.Operation} operation The operation that triggered request
141 me.callParent([config]);
144 * @cfg {Object} extraParams Extra parameters that will be included on every request. Individual requests with params
145 * of the same name will override these params when they are in conflict.
147 me.extraParams = config.extraParams || {};
149 me.api = config.api || {};
151 //backwards compatibility, will be deprecated in 5.0
152 me.nocache = me.noCache;
155 //in a ServerProxy all four CRUD operations are executed in the same manner, so we delegate to doRequest in each case
157 return this.doRequest.apply(this, arguments);
161 return this.doRequest.apply(this, arguments);
165 return this.doRequest.apply(this, arguments);
168 destroy: function() {
169 return this.doRequest.apply(this, arguments);
173 * Creates and returns an Ext.data.Request object based on the options passed by the {@link Ext.data.Store Store}
174 * that this Proxy is attached to.
175 * @param {Ext.data.Operation} operation The {@link Ext.data.Operation Operation} object to execute
176 * @return {Ext.data.Request} The request object
178 buildRequest: function(operation) {
179 var params = Ext.applyIf(operation.params || {}, this.extraParams || {}),
182 //copy any sorters, filters etc into the params so they can be sent over the wire
183 params = Ext.applyIf(params, this.getParams(params, operation));
185 if (operation.id && !params.id) {
186 params.id = operation.id;
189 request = Ext.create('Ext.data.Request', {
191 action : operation.action,
192 records : operation.records,
193 operation: operation,
197 request.url = this.buildUrl(request);
200 * Save the request on the Operation. Operations don't usually care about Request and Response data, but in the
201 * ServerProxy and any of its subclasses we add both request and response as they may be useful for further processing
203 operation.request = request;
211 processResponse: function(success, operation, request, response, callback, scope){
221 if (success === true) {
222 reader = me.getReader();
223 result = reader.read(me.extractResponseData(response));
224 records = result.records;
225 length = records.length;
227 if (result.success !== false) {
228 mc = Ext.create('Ext.util.MixedCollection', true, function(r) {return r.getId();});
229 mc.addAll(operation.records);
230 for (i = 0; i < length; i++) {
231 record = mc.get(records[i].getId());
235 record.set(record.data);
236 record.endEdit(true);
240 //see comment in buildRequest for why we include the response object here
241 Ext.apply(operation, {
246 operation.setCompleted();
247 operation.setSuccessful();
249 operation.setException(result.message);
250 me.fireEvent('exception', this, response, operation);
253 me.setException(operation, response);
254 me.fireEvent('exception', this, response, operation);
257 //this callback is the one that was passed to the 'read' or 'write' function above
258 if (typeof callback == 'function') {
259 callback.call(scope || me, operation);
262 me.afterRequest(request, success);
266 * Sets up an exception on the operation
268 * @param {Ext.data.Operation} operation The operation
269 * @param {Object} response The response
271 setException: function(operation, response){
272 operation.setException({
273 status: response.status,
274 statusText: response.statusText
279 * Template method to allow subclasses to specify how to get the response for the reader.
281 * @param {Object} response The server response
282 * @return {Mixed} The response data to be used by the reader
284 extractResponseData: function(response){
289 * Encode any values being sent to the server. Can be overridden in subclasses.
291 * @param {Array} An array of sorters/filters.
292 * @return {Mixed} The encoded value
294 applyEncoding: function(value){
295 return Ext.encode(value);
299 * Encodes the array of {@link Ext.util.Sorter} objects into a string to be sent in the request url. By default,
300 * this simply JSON-encodes the sorter data
301 * @param {Array} sorters The array of {@link Ext.util.Sorter Sorter} objects
302 * @return {String} The encoded sorters
304 encodeSorters: function(sorters) {
306 length = sorters.length,
309 for (; i < length; i++) {
311 property : sorters[i].property,
312 direction: sorters[i].direction
315 return this.applyEncoding(min);
320 * Encodes the array of {@link Ext.util.Filter} objects into a string to be sent in the request url. By default,
321 * this simply JSON-encodes the filter data
322 * @param {Array} sorters The array of {@link Ext.util.Filter Filter} objects
323 * @return {String} The encoded filters
325 encodeFilters: function(filters) {
327 length = filters.length,
330 for (; i < length; i++) {
332 property: filters[i].property,
333 value : filters[i].value
336 return this.applyEncoding(min);
341 * Copy any sorters, filters etc into the params so they can be sent over the wire
343 getParams: function(params, operation) {
344 params = params || {};
347 isDef = Ext.isDefined,
348 groupers = operation.groupers,
349 sorters = operation.sorters,
350 filters = operation.filters,
351 page = operation.page,
352 start = operation.start,
353 limit = operation.limit,
355 simpleSortMode = me.simpleSortMode,
357 pageParam = me.pageParam,
358 startParam = me.startParam,
359 limitParam = me.limitParam,
360 groupParam = me.groupParam,
361 sortParam = me.sortParam,
362 filterParam = me.filterParam,
363 directionParam = me.directionParam;
365 if (pageParam && isDef(page)) {
366 params[pageParam] = page;
369 if (startParam && isDef(start)) {
370 params[startParam] = start;
373 if (limitParam && isDef(limit)) {
374 params[limitParam] = limit;
377 if (groupParam && groupers && groupers.length > 0) {
378 // Grouper is a subclass of sorter, so we can just use the sorter method
379 params[groupParam] = me.encodeSorters(groupers);
382 if (sortParam && sorters && sorters.length > 0) {
383 if (simpleSortMode) {
384 params[sortParam] = sorters[0].property;
385 params[directionParam] = sorters[0].direction;
387 params[sortParam] = me.encodeSorters(sorters);
392 if (filterParam && filters && filters.length > 0) {
393 params[filterParam] = me.encodeFilters(filters);
400 * Generates a url based on a given Ext.data.Request object. By default, ServerProxy's buildUrl will
401 * add the cache-buster param to the end of the url. Subclasses may need to perform additional modifications
403 * @param {Ext.data.Request} request The request object
404 * @return {String} The url
406 buildUrl: function(request) {
408 url = me.getUrl(request);
412 Ext.Error.raise("You are using a ServerProxy but have not supplied it with a url.");
417 url = Ext.urlAppend(url, Ext.String.format("{0}={1}", me.cacheString, Ext.Date.now()));
424 * Get the url for the request taking into account the order of priority,
429 * @param {Ext.data.Request} request The request
430 * @return {String} The url
432 getUrl: function(request){
433 return request.url || this.api[request.action] || this.url;
437 * In ServerProxy subclasses, the {@link #create}, {@link #read}, {@link #update} and {@link #destroy} methods all pass
438 * through to doRequest. Each ServerProxy subclass must implement the doRequest method - see {@link Ext.data.proxy.JsonP}
439 * and {@link Ext.data.proxy.Ajax} for examples. This method carries the same signature as each of the methods that delegate to it.
440 * @param {Ext.data.Operation} operation The Ext.data.Operation object
441 * @param {Function} callback The callback function to call when the Operation has completed
442 * @param {Object} scope The scope in which to execute the callback
444 doRequest: function(operation, callback, scope) {
446 Ext.Error.raise("The doRequest function has not been implemented on your Ext.data.proxy.Server subclass. See src/data/ServerProxy.js for details");
451 * Optional callback function which can be used to clean up after a request has been completed.
452 * @param {Ext.data.Request} request The Request object
453 * @param {Boolean} success True if the request was successful
456 afterRequest: Ext.emptyFn,
458 onDestroy: function() {
459 Ext.destroy(this.reader, this.writer);