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