git.ithinksw.org / extjs.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / DataProxy.html
diff --git a/docs/source/DataProxy.html b/docs/source/DataProxy.html
index c37e14a..37888cb 100644 (file)
--- a/docs/source/DataProxy.html
+++ b/docs/source/DataProxy.html
@@ -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
@@ -40,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
@@ -68,7 +88,27 @@ api: {
     update  : undefined,\r
     destroy : undefined\r
 }\r
     update  : undefined,\r
     destroy : undefined\r
 }\r
-</code></pre>\r
+     * </code></pre>\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>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
+     * </code></pre>\r
      * <p>If the specific URL for a given CRUD action is undefined, the CRUD action request\r
      * will be directed to the configured <tt>{@link Ext.data.Connection#url url}</tt>.</p>\r
      * <br><p><b>Note</b>: To modify the URL for an action dynamically the appropriate API\r
      * <p>If the specific URL for a given CRUD action is undefined, the CRUD action request\r
      * will be directed to the configured <tt>{@link Ext.data.Connection#url url}</tt>.</p>\r
      * <br><p><b>Note</b>: To modify the URL for an action dynamically the appropriate API\r
@@ -86,22 +126,9 @@ myStore.on({
             // permanent, applying this URL for all subsequent requests.\r
             store.proxy.setUrl('changed1.php', true);\r
 \r
             // permanent, applying this URL for all subsequent requests.\r
             store.proxy.setUrl('changed1.php', true);\r
 \r
-            // manually set the <b>private</b> connection URL.\r
-            // <b>Warning:</b>  Accessing the private URL property should be avoided.\r
-            // Use the public method <tt>{@link Ext.data.HttpProxy#setUrl setUrl}</tt> instead, shown above.\r
-            // It should be noted that changing the URL like this will affect\r
-            // the URL for just this request.  Subsequent requests will use the\r
-            // API or URL defined in your initial proxy configuration.\r
-            store.proxy.conn.url = 'changed1.php';\r
-\r
-            // proxy URL will be superseded by API (only if proxy created to use ajax):\r
-            // It should be noted that proxy API changes are permanent and will\r
-            // be used for all subsequent requests.\r
-            store.proxy.api.load = 'changed2.php';\r
-\r
-            // However, altering the proxy API should be done using the public\r
-            // method <tt>{@link Ext.data.DataProxy#setApi setApi}</tt> instead.\r
-            store.proxy.setApi('load', 'changed2.php');\r
+            // Altering the proxy API should be done using the public\r
+            // method <tt>{@link Ext.data.DataProxy#setApi setApi}</tt>.\r
+            store.proxy.setApi('read', 'changed2.php');\r
 \r
             // Or set the entire API with a config-object.\r
             // When using the config-object option, you must redefine the <b>entire</b>\r
 \r
             // Or set the entire API with a config-object.\r
             // When using the config-object option, you must redefine the <b>entire</b>\r
@@ -118,23 +145,17 @@ myStore.on({
      * </code></pre>\r
      * </p>\r
      */\r
      * </code></pre>\r
      * </p>\r
      */\r
-    // Prepare the proxy api.  Ensures all API-actions are defined with the Object-form.\r
-    try {\r
-        Ext.data.Api.prepare(this);\r
-    } catch (e) {\r
-        if (e instanceof Ext.data.Api.Error) {\r
-            e.toConsole();\r
-        }\r
-    }\r
 \r
     this.addEvents(\r
         <div id="event-Ext.data.DataProxy-exception"></div>/**\r
          * @event exception\r
 \r
     this.addEvents(\r
         <div id="event-Ext.data.DataProxy-exception"></div>/**\r
          * @event exception\r
-         * <p>Fires if an exception occurs in the Proxy during a remote request.\r
-         * This event is relayed through a corresponding\r
-         * {@link Ext.data.Store}.{@link Ext.data.Store#exception exception},\r
-         * so any Store instance may observe this event.\r
-         * This event can be fired for one of two reasons:</p>\r
+         * <p>Fires if an exception occurs in the Proxy during a remote request. This event is relayed\r
+         * through a corresponding {@link Ext.data.Store}.{@link Ext.data.Store#exception exception},\r
+         * so any Store instance may observe this event.</p>\r
+         * <p>In addition to being fired through the DataProxy instance that raised the event, this event is also fired\r
+         * through the Ext.data.DataProxy <i>class</i> to allow for centralized processing of exception events from <b>all</b>\r
+         * DataProxies by attaching a listener to the Ext.data.Proxy class itself.</p>\r
+         * <p>This event can be fired for one of two reasons:</p>\r
          * <div class="mdetail-params"><ul>\r
          * <li>remote-request <b>failed</b> : <div class="sub-desc">\r
          * The server did not return status === 200.\r
          * <div class="mdetail-params"><ul>\r
          * <li>remote-request <b>failed</b> : <div class="sub-desc">\r
          * The server did not return status === 200.\r
@@ -218,7 +239,10 @@ myStore.on({
         'loadexception',\r
         <div id="event-Ext.data.DataProxy-beforewrite"></div>/**\r
          * @event beforewrite\r
         'loadexception',\r
         <div id="event-Ext.data.DataProxy-beforewrite"></div>/**\r
          * @event beforewrite\r
-         * Fires before a request is generated for one of the actions Ext.data.Api.actions.create|update|destroy\r
+         * <p>Fires before a request is generated for one of the actions Ext.data.Api.actions.create|update|destroy</p>\r
+         * <p>In addition to being fired through the DataProxy instance that raised the event, this event is also fired\r
+         * through the Ext.data.DataProxy <i>class</i> to allow for centralized processing of beforewrite events from <b>all</b>\r
+         * DataProxies by attaching a listener to the Ext.data.Proxy class itself.</p>\r
          * @param {DataProxy} this The proxy for the request\r
          * @param {String} action [Ext.data.Api.actions.create|update|destroy]\r
          * @param {Record/Array[Record]} rs The Record(s) to create|update|destroy.\r
          * @param {DataProxy} this The proxy for the request\r
          * @param {String} action [Ext.data.Api.actions.create|update|destroy]\r
          * @param {Record/Array[Record]} rs The Record(s) to create|update|destroy.\r
@@ -227,7 +251,10 @@ myStore.on({
         'beforewrite',\r
         <div id="event-Ext.data.DataProxy-write"></div>/**\r
          * @event write\r
         'beforewrite',\r
         <div id="event-Ext.data.DataProxy-write"></div>/**\r
          * @event write\r
-         * Fires before the request-callback is called\r
+         * <p>Fires before the request-callback is called</p>\r
+         * <p>In addition to being fired through the DataProxy instance that raised the event, this event is also fired\r
+         * through the Ext.data.DataProxy <i>class</i> to allow for centralized processing of write events from <b>all</b>\r
+         * DataProxies by attaching a listener to the Ext.data.Proxy class itself.</p>\r
          * @param {DataProxy} this The proxy that sent the request\r
          * @param {String} action [Ext.data.Api.actions.create|upate|destroy]\r
          * @param {Object} data The data object extracted from the server-response\r
          * @param {DataProxy} this The proxy that sent the request\r
          * @param {String} action [Ext.data.Api.actions.create|upate|destroy]\r
          * @param {Object} data The data object extracted from the server-response\r
@@ -238,6 +265,17 @@ myStore.on({
         'write'\r
     );\r
     Ext.data.DataProxy.superclass.constructor.call(this);\r
         'write'\r
     );\r
     Ext.data.DataProxy.superclass.constructor.call(this);\r
+\r
+    // Prepare the proxy api.  Ensures all API-actions are defined with the Object-form.\r
+    try {\r
+        Ext.data.Api.prepare(this);\r
+    } catch (e) {\r
+        if (e instanceof Ext.data.Api.Error) {\r
+            e.toConsole();\r
+        }\r
+    }\r
+    // relay each proxy's events onto Ext.data.DataProxy class for centralized Proxy-listening\r
+    Ext.data.DataProxy.relayEvents(this, ['beforewrite', 'write', 'exception']);\r
 };\r
 \r
 Ext.extend(Ext.data.DataProxy, Ext.util.Observable, {\r
 };\r
 \r
 Ext.extend(Ext.data.DataProxy, Ext.util.Observable, {\r
@@ -256,7 +294,7 @@ store: new Ext.data.Store({
     ...\r
 )}\r
      * </code></pre>\r
     ...\r
 )}\r
      * </code></pre>\r
-     * There is no <code>{@link #api}</code> specified in the configuration of the proxy,\r
+     * If there is no <code>{@link #api}</code> specified in the configuration of the proxy,\r
      * all requests will be marshalled to a single RESTful url (/users) so the serverside\r
      * framework can inspect the HTTP Method and act accordingly:\r
      * <pre>\r
      * all requests will be marshalled to a single RESTful url (/users) so the serverside\r
      * framework can inspect the HTTP Method and act accordingly:\r
      * <pre>\r
@@ -266,6 +304,18 @@ GET      /users     read
 PUT      /users/23  update\r
 DESTROY  /users/23  delete\r
      * </pre></p>\r
 PUT      /users/23  update\r
 DESTROY  /users/23  delete\r
      * </pre></p>\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. Some MVC (e.g., Ruby on Rails,\r
+     * Merb and Django) support segment based urls where the segments in the URL follow the\r
+     * Model-View-Controller approach:<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
+     * <br><p>Refer to <code>{@link Ext.data.DataProxy#api}</code> for additional information.</p>\r
      */\r
     restful: false,\r
 \r
      */\r
     restful: false,\r
 \r
@@ -324,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
@@ -353,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
@@ -364,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
@@ -376,25 +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
-        var format = null;\r
-        var m = url.match(/(.*)(\.\w+)$/);  // <-- look for urls with "provides" suffix, 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
+        var provides = null;\r
+        var m = url.match(/(.*)(\.json|\.xml|\.html)$/);\r
         if (m) {\r
         if (m) {\r
-            format = m[2];\r
-            url = m[1];\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
@@ -405,6 +483,11 @@ proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
     }\r
 });\r
 \r
     }\r
 });\r
 \r
+// Apply the Observable prototype to the DataProxy class so that proxy instances can relay their\r
+// events to the class.  Allows for centralized listening of all proxy instances upon the DataProxy class.\r
+Ext.apply(Ext.data.DataProxy, Ext.util.Observable.prototype);\r
+Ext.util.Observable.call(Ext.data.DataProxy);\r
+\r
 <div id="cls-Ext.data.DataProxy.Error"></div>/**\r
  * @class Ext.data.DataProxy.Error\r
  * @extends Ext.Error\r
 <div id="cls-Ext.data.DataProxy.Error"></div>/**\r
  * @class Ext.data.DataProxy.Error\r
  * @extends Ext.Error\r
@@ -426,6 +509,8 @@ Ext.apply(Ext.data.DataProxy.Error.prototype, {
         'api-invalid': 'Recieved an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions from Ext.data.Api.actions.'\r
     }\r
 });\r
         'api-invalid': 'Recieved an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions from Ext.data.Api.actions.'\r
     }\r
 });\r
+\r
+\r
 </pre>    \r
 </body>\r
 </html>
\ No newline at end of file
 </pre>    \r
 </body>\r
 </html>
\ No newline at end of file
Mirror of ExtJS by Sencha Inc. <http://www.sencha.com/>.