Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / HttpProxy.html
index c042893..5ae9fa8 100644 (file)
@@ -1,5 +1,6 @@
 <html>\r
 <head>\r
 <html>\r
 <head>\r
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \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
   <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
@@ -18,7 +19,7 @@
  * @constructor\r
  * @param {Object} conn\r
  * An {@link Ext.data.Connection} object, or options parameter to {@link Ext.Ajax#request}.\r
  * @constructor\r
  * @param {Object} conn\r
  * An {@link Ext.data.Connection} object, or options parameter to {@link Ext.Ajax#request}.\r
- * <p>Note that if this HttpProxy is being used by a (@link Ext.data.Store Store}, then the\r
+ * <p>Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the\r
  * Store's call to {@link #load} will override any specified <tt>callback</tt> and <tt>params</tt>\r
  * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters,\r
  * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be\r
  * Store's call to {@link #load} will override any specified <tt>callback</tt> and <tt>params</tt>\r
  * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters,\r
  * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be\r
@@ -39,13 +40,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
 \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
     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
     var actions = Ext.data.Api.actions;\r
     this.activeRequest = {};\r
     for (var verb in actions) {\r
@@ -54,40 +55,6 @@ Ext.data.HttpProxy = function(conn){
 };\r
 \r
 Ext.extend(Ext.data.HttpProxy, Ext.data.DataProxy, {\r
 };\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
     <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 +78,7 @@ api: {
         this.conn.url = url;\r
         if (makePermanent === true) {\r
             this.url = url;\r
         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
             Ext.data.Api.prepare(this);\r
         }\r
     },\r
@@ -129,8 +97,9 @@ api: {
      * <li><tt>r</tt> : Ext.data.Record[] The block of Ext.data.Records.</li>\r
      * <li><tt>options</tt>: Options object from the action request</li>\r
      * <li><tt>success</tt>: Boolean success indicator</li></ul></p></div>\r
      * <li><tt>r</tt> : Ext.data.Record[] The block of Ext.data.Records.</li>\r
      * <li><tt>options</tt>: Options object from the action request</li>\r
      * <li><tt>success</tt>: Boolean success indicator</li></ul></p></div>\r
-     * @param {Object} scope The scope in which to call the callback\r
+     * @param {Object} scope The scope (<code>this</code> reference) in which the callback function is executed. Defaults to the browser window.\r
      * @param {Object} arg An optional argument which is passed to the callback as its second parameter.\r
      * @param {Object} arg An optional argument which is passed to the callback as its second parameter.\r
+     * @protected\r
      */\r
     doRequest : function(action, rs, params, reader, cb, scope, arg) {\r
         var  o = {\r
      */\r
     doRequest : function(action, rs, params, reader, cb, scope, arg) {\r
         var  o = {\r
@@ -144,29 +113,31 @@ api: {
             callback : this.createCallback(action, rs),\r
             scope: this\r
         };\r
             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
+        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
         // Set the connection url.  If this.conn.url is not null here,\r
         } else {\r
             o.params = params || {};\r
         }\r
         // Set the connection url.  If this.conn.url is not null here,\r
-        // the user may have overridden the url during a beforeaction event-handler.\r
+        // the user must have overridden the url during a beforewrite/beforeload event-handler.\r
         // this.conn.url is nullified after each request.\r
         // this.conn.url is nullified after each request.\r
-        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
-            this.conn.url += '/' + rs.id;\r
-        }\r
+        this.conn.url = this.buildUrl(action, rs);\r
+\r
         if(this.useAjax){\r
 \r
             Ext.applyIf(o, this.conn);\r
 \r
             // If a currently running request is found for this action, abort it.\r
             if (this.activeRequest[action]) {\r
         if(this.useAjax){\r
 \r
             Ext.applyIf(o, this.conn);\r
 \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
                 // 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
                 //Ext.Ajax.abort(this.activeRequest[action]);\r
             }\r
             this.activeRequest[action] = Ext.Ajax.request(o);\r
@@ -190,6 +161,7 @@ api: {
             if (!success) {\r
                 if (action === Ext.data.Api.actions.read) {\r
                     // @deprecated: fire loadexception for backwards compat.\r
             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
                     this.fireEvent('loadexception', this, o, response);\r
                 }\r
                 this.fireEvent('exception', this, 'response', action, o, response);\r
@@ -204,12 +176,15 @@ api: {
         }\r
     },\r
 \r
         }\r
     },\r
 \r
-    /**\r
+    <div id="method-Ext.data.HttpProxy-onRead"></div>/**\r
      * Callback for read action\r
      * @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
      * Callback for read action\r
      * @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
-     * @private\r
+     * @fires loadexception (deprecated)\r
+     * @fires exception\r
+     * @fires load\r
+     * @protected\r
      */\r
     onRead : function(action, o, response) {\r
         var result;\r
      */\r
     onRead : function(action, o, response) {\r
         var result;\r
@@ -217,13 +192,16 @@ api: {
             result = o.reader.read(response);\r
         }catch(e){\r
             // @deprecated: fire old loadexception for backwards-compat.\r
             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
             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
             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
             this.fireEvent('loadexception', this, o, response);\r
 \r
             // Get DataReader read-back a response-object to pass along to exception event\r
@@ -233,14 +211,19 @@ api: {
         else {\r
             this.fireEvent('load', this, o, o.request.arg);\r
         }\r
         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
         o.request.callback.call(o.request.scope, result, o.request.arg, result.success);\r
     },\r
-    /**\r
+    <div id="method-Ext.data.HttpProxy-onWrite"></div>/**\r
      * Callback for write actions\r
      * @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
      * Callback for write actions\r
      * @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
-     * @private\r
+     * @fires exception\r
+     * @fires write\r
+     * @protected\r
      */\r
     onWrite : function(action, o, response, rs) {\r
         var reader = o.reader;\r
      */\r
     onWrite : function(action, o, response, rs) {\r
         var reader = o.reader;\r
@@ -252,12 +235,15 @@ api: {
             o.request.callback.call(o.request.scope, null, o.request.arg, false);\r
             return;\r
         }\r
             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('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
         }\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
     },\r
 \r
     // inherit docs\r