Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / HttpProxy.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.3.1
11  * Copyright(c) 2006-2010 Sencha Inc.
12  * licensing@sencha.com
13  * http://www.sencha.com/license
14  */
15 <div id="cls-Ext.data.HttpProxy"></div>/**
16  * @class Ext.data.HttpProxy
17  * @extends Ext.data.DataProxy
18  * <p>An implementation of {@link Ext.data.DataProxy} that processes data requests within the same
19  * domain of the originating page.</p>
20  * <p><b>Note</b>: this class cannot be used to retrieve data from a domain other
21  * than the domain from which the running page was served. For cross-domain requests, use a
22  * {@link Ext.data.ScriptTagProxy ScriptTagProxy}.</p>
23  * <p>Be aware that to enable the browser to parse an XML document, the server must set
24  * the Content-Type header in the HTTP response to "<tt>text/xml</tt>".</p>
25  * @constructor
26  * @param {Object} conn
27  * An {@link Ext.data.Connection} object, or options parameter to {@link Ext.Ajax#request}.
28  * <p>Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the
29  * Store's call to {@link #load} will override any specified <tt>callback</tt> and <tt>params</tt>
30  * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters,
31  * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be
32  * used to pass parameters known at instantiation time.</p>
33  * <p>If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make
34  * the request.</p>
35  */
36 Ext.data.HttpProxy = function(conn){
37     Ext.data.HttpProxy.superclass.constructor.call(this, conn);
38
39     <div id="prop-Ext.data.HttpProxy-conn"></div>/**
40      * The Connection object (Or options parameter to {@link Ext.Ajax#request}) which this HttpProxy
41      * uses to make requests to the server. Properties of this object may be changed dynamically to
42      * change the way data is requested.
43      * @property
44      */
45     this.conn = conn;
46
47     // nullify the connection url.  The url param has been copied to 'this' above.  The connection
48     // url will be set during each execution of doRequest when buildUrl is called.  This makes it easier for users to override the
49     // connection url during beforeaction events (ie: beforeload, beforewrite, etc).
50     // Url is always re-defined during doRequest.
51     this.conn.url = null;
52
53     this.useAjax = !conn || !conn.events;
54
55     // A hash containing active requests, keyed on action [Ext.data.Api.actions.create|read|update|destroy]
56     var actions = Ext.data.Api.actions;
57     this.activeRequest = {};
58     for (var verb in actions) {
59         this.activeRequest[actions[verb]] = undefined;
60     }
61 };
62
63 Ext.extend(Ext.data.HttpProxy, Ext.data.DataProxy, {
64     <div id="method-Ext.data.HttpProxy-getConnection"></div>/**
65      * Return the {@link Ext.data.Connection} object being used by this Proxy.
66      * @return {Connection} The Connection object. This object may be used to subscribe to events on
67      * a finer-grained basis than the DataProxy events.
68      */
69     getConnection : function() {
70         return this.useAjax ? Ext.Ajax : this.conn;
71     },
72
73     <div id="method-Ext.data.HttpProxy-setUrl"></div>/**
74      * Used for overriding the url used for a single request.  Designed to be called during a beforeaction event.  Calling setUrl
75      * will override any urls set via the api configuration parameter.  Set the optional parameter makePermanent to set the url for
76      * all subsequent requests.  If not set to makePermanent, the next request will use the same url or api configuration defined
77      * in the initial proxy configuration.
78      * @param {String} url
79      * @param {Boolean} makePermanent (Optional) [false]
80      *
81      * (e.g.: beforeload, beforesave, etc).
82      */
83     setUrl : function(url, makePermanent) {
84         this.conn.url = url;
85         if (makePermanent === true) {
86             this.url = url;
87             this.api = null;
88             Ext.data.Api.prepare(this);
89         }
90     },
91
92     <div id="method-Ext.data.HttpProxy-doRequest"></div>/**
93      * HttpProxy implementation of DataProxy#doRequest
94      * @param {String} action The crud action type (create, read, update, destroy)
95      * @param {Ext.data.Record/Ext.data.Record[]} rs If action is load, rs will be null
96      * @param {Object} params An object containing properties which are to be used as HTTP parameters
97      * for the request to the remote server.
98      * @param {Ext.data.DataReader} reader The Reader object which converts the data
99      * object into a block of Ext.data.Records.
100      * @param {Function} callback
101      * <div class="sub-desc"><p>A function to be called after the request.
102      * The <tt>callback</tt> is passed the following arguments:<ul>
103      * <li><tt>r</tt> : Ext.data.Record[] The block of Ext.data.Records.</li>
104      * <li><tt>options</tt>: Options object from the action request</li>
105      * <li><tt>success</tt>: Boolean success indicator</li></ul></p></div>
106      * @param {Object} scope The scope (<code>this</code> reference) in which the callback function is executed. Defaults to the browser window.
107      * @param {Object} arg An optional argument which is passed to the callback as its second parameter.
108      * @protected
109      */
110     doRequest : function(action, rs, params, reader, cb, scope, arg) {
111         var  o = {
112             method: (this.api[action]) ? this.api[action]['method'] : undefined,
113             request: {
114                 callback : cb,
115                 scope : scope,
116                 arg : arg
117             },
118             reader: reader,
119             callback : this.createCallback(action, rs),
120             scope: this
121         };
122
123         // If possible, transmit data using jsonData || xmlData on Ext.Ajax.request (An installed DataWriter would have written it there.).
124         // Use std HTTP params otherwise.
125         if (params.jsonData) {
126             o.jsonData = params.jsonData;
127         } else if (params.xmlData) {
128             o.xmlData = params.xmlData;
129         } else {
130             o.params = params || {};
131         }
132         // Set the connection url.  If this.conn.url is not null here,
133         // the user must have overridden the url during a beforewrite/beforeload event-handler.
134         // this.conn.url is nullified after each request.
135         this.conn.url = this.buildUrl(action, rs);
136
137         if(this.useAjax){
138
139             Ext.applyIf(o, this.conn);
140
141             // If a currently running request is found for this action, abort it.
142             if (this.activeRequest[action]) {
143                 ////
144                 // Disabled aborting activeRequest while implementing REST.  activeRequest[action] will have to become an array
145                 // TODO ideas anyone?
146                 //
147                 //Ext.Ajax.abort(this.activeRequest[action]);
148             }
149             this.activeRequest[action] = Ext.Ajax.request(o);
150         }else{
151             this.conn.request(o);
152         }
153         // request is sent, nullify the connection url in preparation for the next request
154         this.conn.url = null;
155     },
156
157     /**
158      * Returns a callback function for a request.  Note a special case is made for the
159      * read action vs all the others.
160      * @param {String} action [create|update|delete|load]
161      * @param {Ext.data.Record[]} rs The Store-recordset being acted upon
162      * @private
163      */
164     createCallback : function(action, rs) {
165         return function(o, success, response) {
166             this.activeRequest[action] = undefined;
167             if (!success) {
168                 if (action === Ext.data.Api.actions.read) {
169                     // @deprecated: fire loadexception for backwards compat.
170                     // TODO remove
171                     this.fireEvent('loadexception', this, o, response);
172                 }
173                 this.fireEvent('exception', this, 'response', action, o, response);
174                 o.request.callback.call(o.request.scope, null, o.request.arg, false);
175                 return;
176             }
177             if (action === Ext.data.Api.actions.read) {
178                 this.onRead(action, o, response);
179             } else {
180                 this.onWrite(action, o, response, rs);
181             }
182         };
183     },
184
185     <div id="method-Ext.data.HttpProxy-onRead"></div>/**
186      * Callback for read action
187      * @param {String} action Action name as per {@link Ext.data.Api.actions#read}.
188      * @param {Object} o The request transaction object
189      * @param {Object} res The server response
190      * @fires loadexception (deprecated)
191      * @fires exception
192      * @fires load
193      * @protected
194      */
195     onRead : function(action, o, response) {
196         var result;
197         try {
198             result = o.reader.read(response);
199         }catch(e){
200             // @deprecated: fire old loadexception for backwards-compat.
201             // TODO remove
202             this.fireEvent('loadexception', this, o, response, e);
203
204             this.fireEvent('exception', this, 'response', action, o, response, e);
205             o.request.callback.call(o.request.scope, null, o.request.arg, false);
206             return;
207         }
208         if (result.success === false) {
209             // @deprecated: fire old loadexception for backwards-compat.
210             // TODO remove
211             this.fireEvent('loadexception', this, o, response);
212
213             // Get DataReader read-back a response-object to pass along to exception event
214             var res = o.reader.readResponse(action, response);
215             this.fireEvent('exception', this, 'remote', action, o, res, null);
216         }
217         else {
218             this.fireEvent('load', this, o, o.request.arg);
219         }
220         // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance
221         // the calls to request.callback(...) in each will have to be made identical.
222         // NOTE reader.readResponse does not currently return Ext.data.Response
223         o.request.callback.call(o.request.scope, result, o.request.arg, result.success);
224     },
225     <div id="method-Ext.data.HttpProxy-onWrite"></div>/**
226      * Callback for write actions
227      * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]
228      * @param {Object} trans The request transaction object
229      * @param {Object} res The server response
230      * @fires exception
231      * @fires write
232      * @protected
233      */
234     onWrite : function(action, o, response, rs) {
235         var reader = o.reader;
236         var res;
237         try {
238             res = reader.readResponse(action, response);
239         } catch (e) {
240             this.fireEvent('exception', this, 'response', action, o, response, e);
241             o.request.callback.call(o.request.scope, null, o.request.arg, false);
242             return;
243         }
244         if (res.success === true) {
245             this.fireEvent('write', this, action, res.data, res, rs, o.request.arg);
246         } else {
247             this.fireEvent('exception', this, 'remote', action, o, res, rs);
248         }
249         // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance
250         // the calls to request.callback(...) in each will have to be made similar.
251         // NOTE reader.readResponse does not currently return Ext.data.Response
252         o.request.callback.call(o.request.scope, res.data, res, res.success);
253     },
254
255     // inherit docs
256     destroy: function(){
257         if(!this.useAjax){
258             this.conn.abort();
259         }else if(this.activeRequest){
260             var actions = Ext.data.Api.actions;
261             for (var verb in actions) {
262                 if(this.activeRequest[actions[verb]]){
263                     Ext.Ajax.abort(this.activeRequest[actions[verb]]);
264                 }
265             }
266         }
267         Ext.data.HttpProxy.superclass.destroy.call(this);
268     }
269 });</pre>    
270 </body>
271 </html>