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