Upgrade to ExtJS 3.0.3 - Released 10/11/2009
[extjs.git] / docs / source / HttpProxy.html
index c042893..6e27e88 100644 (file)
@@ -1,11 +1,17 @@
-<html>\r
-<head>\r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.data.HttpProxy"></div>/**\r
+<html>
+<head>
+  <title>The source code</title>
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+</head>
+<body  onload="prettyPrint();">
+    <pre class="prettyprint lang-js">/*!
+ * Ext JS Library 3.0.3
+ * Copyright(c) 2006-2009 Ext JS, LLC
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+<div id="cls-Ext.data.HttpProxy"></div>/**\r
  * @class Ext.data.HttpProxy\r
  * @extends Ext.data.DataProxy\r
  * <p>An implementation of {@link Ext.data.DataProxy} that processes data requests within the same\r
@@ -39,13 +45,13 @@ Ext.data.HttpProxy = function(conn){
 \r
     // nullify the connection url.  The url param has been copied to 'this' above.  The connection\r
     // url will be set during each execution of doRequest when buildUrl is called.  This makes it easier for users to override the\r
-    // connection url during beforeaction events (ie: beforeload, beforesave, etc).  The connection url will be nullified\r
-    // after each request as well.  Url is always re-defined during doRequest.\r
+    // connection url during beforeaction events (ie: beforeload, beforewrite, etc).\r
+    // Url is always re-defined during doRequest.\r
     this.conn.url = null;\r
 \r
     this.useAjax = !conn || !conn.events;\r
 \r
-    //private.  A hash containing active requests, keyed on action [Ext.data.Api.actions.create|read|update|destroy]\r
+    // A hash containing active requests, keyed on action [Ext.data.Api.actions.create|read|update|destroy]\r
     var actions = Ext.data.Api.actions;\r
     this.activeRequest = {};\r
     for (var verb in actions) {\r
@@ -54,40 +60,6 @@ Ext.data.HttpProxy = function(conn){
 };\r
 \r
 Ext.extend(Ext.data.HttpProxy, Ext.data.DataProxy, {\r
-    <div id="cfg-Ext.data.HttpProxy-restful"></div>/**\r
-     * @cfg {Boolean} restful\r
-     * <p>If set to <tt>true</tt>, a {@link Ext.data.Record#phantom non-phantom} record's\r
-     * {@link Ext.data.Record#id id} will be appended to the url (defaults to <tt>false</tt>).</p><br>\r
-     * <p>The url is built based upon the action being executed <tt>[load|create|save|destroy]</tt>\r
-     * using the commensurate <tt>{@link #api}</tt> property, or if undefined default to the\r
-     * configured {@link Ext.data.Store}.{@link Ext.data.Store#url url}.</p><br>\r
-     * <p>Some MVC (e.g., Ruby on Rails, Merb and Django) support this style of segment based urls\r
-     * where the segments in the URL follow the Model-View-Controller approach.</p><pre><code>\r
-     * someSite.com/controller/action/id\r
-     * </code></pre>\r
-     * Where the segments in the url are typically:<div class="mdetail-params"><ul>\r
-     * <li>The first segment : represents the controller class that should be invoked.</li>\r
-     * <li>The second segment : represents the class function, or method, that should be called.</li>\r
-     * <li>The third segment : represents the ID (a variable typically passed to the method).</li>\r
-     * </ul></div></p>\r
-     * <p>For example:</p>\r
-     * <pre><code>\r
-api: {\r
-    load :    '/controller/load',\r
-    create :  '/controller/new',  // Server MUST return idProperty of new record\r
-    save :    '/controller/update',\r
-    destroy : '/controller/destroy_action'\r
-}\r
-\r
-// Alternatively, one can use the object-form to specify each API-action\r
-api: {\r
-    load: {url: 'read.php', method: 'GET'},\r
-    create: 'create.php',\r
-    destroy: 'destroy.php',\r
-    save: 'update.php'\r
-}\r
-     */\r
-\r
     <div id="method-Ext.data.HttpProxy-getConnection"></div>/**\r
      * Return the {@link Ext.data.Connection} object being used by this Proxy.\r
      * @return {Connection} The Connection object. This object may be used to subscribe to events on\r
@@ -111,6 +83,7 @@ api: {
         this.conn.url = url;\r
         if (makePermanent === true) {\r
             this.url = url;\r
+            this.api = null;\r
             Ext.data.Api.prepare(this);\r
         }\r
     },\r
@@ -144,10 +117,14 @@ api: {
             callback : this.createCallback(action, rs),\r
             scope: this\r
         };\r
-        // Sample the request data:  If it's an object, then it hasn't been json-encoded yet.\r
-        // Transmit data using jsonData config of Ext.Ajax.request\r
-        if (typeof(params[reader.meta.root]) === 'object') {\r
-            o.jsonData = params;\r
+\r
+        // If possible, transmit data using jsonData || xmlData on Ext.Ajax.request (An installed DataWriter would have written it there.).\r
+        // Use std HTTP params otherwise.\r
+        // TODO wrap into 1 Ext.apply now?\r
+        if (params.jsonData) {\r
+            o.jsonData = params.jsonData;\r
+        } else if (params.xmlData) {\r
+            o.xmlData = params.xmlData;\r
         } else {\r
             o.params = params || {};\r
         }\r
@@ -157,7 +134,7 @@ api: {
         if (this.conn.url === null) {\r
             this.conn.url = this.buildUrl(action, rs);\r
         }\r
-        else if (this.restful === true && rs instanceof Ext.data.Record && !rs.phantom) {\r
+        else if (this.restful === true && rs instanceof Ext.data.Record && !rs.phantom) { // <-- user must have intervened with #setApi or #setUrl\r
             this.conn.url += '/' + rs.id;\r
         }\r
         if(this.useAjax){\r
@@ -166,7 +143,10 @@ api: {
 \r
             // If a currently running request is found for this action, abort it.\r
             if (this.activeRequest[action]) {\r
+                ////\r
                 // Disabled aborting activeRequest while implementing REST.  activeRequest[action] will have to become an array\r
+                // TODO ideas anyone?\r
+                //\r
                 //Ext.Ajax.abort(this.activeRequest[action]);\r
             }\r
             this.activeRequest[action] = Ext.Ajax.request(o);\r
@@ -190,6 +170,7 @@ api: {
             if (!success) {\r
                 if (action === Ext.data.Api.actions.read) {\r
                     // @deprecated: fire loadexception for backwards compat.\r
+                    // TODO remove in 3.1\r
                     this.fireEvent('loadexception', this, o, response);\r
                 }\r
                 this.fireEvent('exception', this, 'response', action, o, response);\r
@@ -209,6 +190,9 @@ api: {
      * @param {String} action Action name as per {@link Ext.data.Api.actions#read}.\r
      * @param {Object} o The request transaction object\r
      * @param {Object} res The server response\r
+     * @fires loadexception (deprecated)\r
+     * @fires exception\r
+     * @fires load\r
      * @private\r
      */\r
     onRead : function(action, o, response) {\r
@@ -217,13 +201,16 @@ api: {
             result = o.reader.read(response);\r
         }catch(e){\r
             // @deprecated: fire old loadexception for backwards-compat.\r
+            // TODO remove in 3.1\r
             this.fireEvent('loadexception', this, o, response, e);\r
+\r
             this.fireEvent('exception', this, 'response', action, o, response, e);\r
             o.request.callback.call(o.request.scope, null, o.request.arg, false);\r
             return;\r
         }\r
         if (result.success === false) {\r
             // @deprecated: fire old loadexception for backwards-compat.\r
+            // TODO remove in 3.1\r
             this.fireEvent('loadexception', this, o, response);\r
 \r
             // Get DataReader read-back a response-object to pass along to exception event\r
@@ -233,6 +220,9 @@ api: {
         else {\r
             this.fireEvent('load', this, o, o.request.arg);\r
         }\r
+        // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance\r
+        // the calls to request.callback(...) in each will have to be made identical.\r
+        // NOTE reader.readResponse does not currently return Ext.data.Response\r
         o.request.callback.call(o.request.scope, result, o.request.arg, result.success);\r
     },\r
     /**\r
@@ -240,6 +230,8 @@ api: {
      * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]\r
      * @param {Object} trans The request transaction object\r
      * @param {Object} res The server response\r
+     * @fires exception\r
+     * @fires write\r
      * @private\r
      */\r
     onWrite : function(action, o, response, rs) {\r
@@ -252,12 +244,15 @@ api: {
             o.request.callback.call(o.request.scope, null, o.request.arg, false);\r
             return;\r
         }\r
-        if (res[reader.meta.successProperty] === false) {\r
+        if (res.success === false) {\r
             this.fireEvent('exception', this, 'remote', action, o, res, rs);\r
         } else {\r
-            this.fireEvent('write', this, action, res[reader.meta.root], res, rs, o.request.arg);\r
+            this.fireEvent('write', this, action, res.data, res, rs, o.request.arg);\r
         }\r
-        o.request.callback.call(o.request.scope, res[reader.meta.root], res, res[reader.meta.successProperty]);\r
+        // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance\r
+        // the calls to request.callback(...) in each will have to be made similar.\r
+        // NOTE reader.readResponse does not currently return Ext.data.Response\r
+        o.request.callback.call(o.request.scope, res.data, res, res.success);\r
     },\r
 \r
     // inherit docs\r
@@ -274,6 +269,6 @@ api: {
         }\r
         Ext.data.HttpProxy.superclass.destroy.call(this);\r
     }\r
-});</pre>    \r
-</body>\r
+});</pre>
+</body>
 </html>
\ No newline at end of file