Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / DataProxy.html
index 40f0303..37888cb 100644 (file)
@@ -1,17 +1,12 @@
-<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.DataProxy"></div>/**\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
+</head>\r
+<body  onload="prettyPrint();">\r
+    <pre class="prettyprint lang-js"><div id="cls-Ext.data.DataProxy"></div>/**\r
  * @class Ext.data.DataProxy\r
  * @extends Ext.util.Observable\r
  * <p>Abstract base class for implementations which provide retrieval of unformatted data objects.\r
  * @class Ext.data.DataProxy\r
  * @extends Ext.util.Observable\r
  * <p>Abstract base class for implementations which provide retrieval of unformatted data objects.\r
@@ -46,6 +41,25 @@ proxy : new Ext.data.HttpProxy({
     }\r
 }),\r
  * </code></pre>\r
     }\r
 }),\r
  * </code></pre>\r
+ * <p>And <b>new in Ext version 3</b>, attach centralized event-listeners upon the DataProxy class itself!  This is a great place\r
+ * to implement a <i>messaging system</i> to centralize your application's user-feedback and error-handling.</p>\r
+ * <pre><code>\r
+// Listen to all "beforewrite" event fired by all proxies.\r
+Ext.data.DataProxy.on('beforewrite', function(proxy, action) {\r
+    console.log('beforewrite: ', action);\r
+});\r
+\r
+// Listen to "write" event fired by all proxies\r
+Ext.data.DataProxy.on('write', function(proxy, action, data, res, rs) {\r
+    console.info('write: ', action);\r
+});\r
+\r
+// Listen to "exception" event fired by all proxies\r
+Ext.data.DataProxy.on('exception', function(proxy, type, action) {\r
+    console.error(type + action + ' exception);\r
+});\r
+ * </code></pre>\r
+ * <b>Note:</b> These three events are all fired with the signature of the corresponding <i>DataProxy instance</i> event {@link #beforewrite beforewrite}, {@link #write write} and {@link #exception exception}.\r
  */\r
 Ext.data.DataProxy = function(conn){\r
     // make sure we have a config object here to support ux proxies.\r
  */\r
 Ext.data.DataProxy = function(conn){\r
     // make sure we have a config object here to support ux proxies.\r
@@ -360,7 +374,7 @@ proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
      * @param {Object} params\r
      * @param {Ext.data.DataReader} reader\r
      * @param {Function} callback\r
      * @param {Object} params\r
      * @param {Ext.data.DataReader} reader\r
      * @param {Function} callback\r
-     * @param {Object} scope Scope with which to call the callback (defaults to the Proxy object)\r
+     * @param {Object} scope The scope (<code>this</code> reference) in which the callback function is executed. Defaults to the Proxy object.\r
      * @param {Object} options Any options specified for the action (e.g. see {@link Ext.data.Store#load}.\r
      */\r
     request : function(action, rs, params, reader, callback, scope, options) {\r
      * @param {Object} options Any options specified for the action (e.g. see {@link Ext.data.Store#load}.\r
      */\r
     request : function(action, rs, params, reader, callback, scope, options) {\r
@@ -389,7 +403,7 @@ proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
     load : null,\r
 \r
     <div id="cfg-Ext.data.DataProxy-doRequest"></div>/**\r
     load : null,\r
 \r
     <div id="cfg-Ext.data.DataProxy-doRequest"></div>/**\r
-     * @cfg {Function} doRequest Abstract method that should be implemented in all subclasses\r
+     * @cfg {Function} doRequest Abstract method that should be implemented in all subclasses.  <b>Note:</b> Should only be used by custom-proxy developers.\r
      * (e.g.: {@link Ext.data.HttpProxy#doRequest HttpProxy.doRequest},\r
      * {@link Ext.data.DirectProxy#doRequest DirectProxy.doRequest}).\r
      */\r
      * (e.g.: {@link Ext.data.HttpProxy#doRequest HttpProxy.doRequest},\r
      * {@link Ext.data.DirectProxy#doRequest DirectProxy.doRequest}).\r
      */\r
@@ -400,6 +414,27 @@ proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
         this.load(params, reader, callback, scope, options);\r
     },\r
 \r
         this.load(params, reader, callback, scope, options);\r
     },\r
 \r
+    <div id="cfg-Ext.data.DataProxy-onRead"></div>/**\r
+     * @cfg {Function} onRead Abstract method that should be implemented in all subclasses.  <b>Note:</b> Should only be used by custom-proxy developers.  Callback for read {@link Ext.data.Api#actions 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
+     * @fires loadexception (deprecated)\r
+     * @fires exception\r
+     * @fires load\r
+     * @protected\r
+     */\r
+    onRead : Ext.emptyFn,\r
+    <div id="cfg-Ext.data.DataProxy-onWrite"></div>/**\r
+     * @cfg {Function} onWrite Abstract method that should be implemented in all subclasses.  <b>Note:</b> Should only be used by custom-proxy developers.  Callback for <i>create, update and destroy</i> {@link Ext.data.Api#actions 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
+     * @fires exception\r
+     * @fires write\r
+     * @protected\r
+     */\r
+    onWrite : Ext.emptyFn,\r
     /**\r
      * buildUrl\r
      * Sets the appropriate url based upon the action being executed.  If restful is true, and only a single record is being acted upon,\r
     /**\r
      * buildUrl\r
      * Sets the appropriate url based upon the action being executed.  If restful is true, and only a single record is being acted upon,\r
@@ -412,30 +447,32 @@ proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
      */\r
     buildUrl : function(action, record) {\r
         record = record || null;\r
      */\r
     buildUrl : function(action, record) {\r
         record = record || null;\r
-        var url = (this.api[action]) ? this.api[action].url : this.url;\r
+\r
+        // conn.url gets nullified after each request.  If it's NOT null here, that means the user must have intervened with a call\r
+        // to DataProxy#setUrl or DataProxy#setApi and changed it before the request was executed.  If that's the case, use conn.url,\r
+        // otherwise, build the url from the api or this.url.\r
+        var url = (this.conn && this.conn.url) ? this.conn.url : (this.api[action]) ? this.api[action].url : this.url;\r
         if (!url) {\r
             throw new Ext.data.Api.Error('invalid-url', action);\r
         }\r
 \r
         if (!url) {\r
             throw new Ext.data.Api.Error('invalid-url', action);\r
         }\r
 \r
-        // look for urls having "provides" suffix (from Rails/Merb and others...),\r
-        // e.g.: /users.json, /users.xml, etc\r
+        // look for urls having "provides" suffix used in some MVC frameworks like Rails/Merb and others.  The provides suffice informs\r
+        // the server what data-format the client is dealing with and returns data in the same format (eg: application/json, application/xml, etc)\r
+        // e.g.: /users.json, /users.xml, etc.\r
         // with restful routes, we need urls like:\r
         // PUT /users/1.json\r
         // DELETE /users/1.json\r
         // with restful routes, we need urls like:\r
         // PUT /users/1.json\r
         // DELETE /users/1.json\r
-        var format = null;\r
+        var provides = null;\r
         var m = url.match(/(.*)(\.json|\.xml|\.html)$/);\r
         if (m) {\r
         var m = url.match(/(.*)(\.json|\.xml|\.html)$/);\r
         if (m) {\r
-            format = m[2];  // eg ".json"\r
-            url = m[1];     // eg: "/users"\r
+            provides = m[2];    // eg ".json"\r
+            url      = m[1];    // eg: "/users"\r
         }\r
         // prettyUrls is deprectated in favor of restful-config\r
         }\r
         // prettyUrls is deprectated in favor of restful-config\r
-        if ((this.prettyUrls === true || this.restful === true) && record instanceof Ext.data.Record && !record.phantom) {\r
+        if ((this.restful === true || this.prettyUrls === true) && record instanceof Ext.data.Record && !record.phantom) {\r
             url += '/' + record.id;\r
         }\r
             url += '/' + record.id;\r
         }\r
-        if (format) {   // <-- append the request format if exists (ie: /users/update/69[.json])\r
-            url += format;\r
-        }\r
-        return url;\r
+        return (provides === null) ? url : url + provides;\r
     },\r
 \r
     <div id="method-Ext.data.DataProxy-destroy"></div>/**\r
     },\r
 \r
     <div id="method-Ext.data.DataProxy-destroy"></div>/**\r
@@ -474,6 +511,6 @@ Ext.apply(Ext.data.DataProxy.Error.prototype, {
 });\r
 \r
 \r
 });\r
 \r
 \r
-</pre>
-</body>
+</pre>    \r
+</body>\r
 </html>
\ No newline at end of file
 </html>
\ No newline at end of file