--- /dev/null
+<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.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
+ * This class is intended to be extended and should not be created directly. For existing implementations,\r
+ * see {@link Ext.data.DirectProxy}, {@link Ext.data.HttpProxy}, {@link Ext.data.ScriptTagProxy} and\r
+ * {@link Ext.data.MemoryProxy}.</p>\r
+ * <p>DataProxy implementations are usually used in conjunction with an implementation of {@link Ext.data.DataReader}\r
+ * (of the appropriate type which knows how to parse the data object) to provide a block of\r
+ * {@link Ext.data.Records} to an {@link Ext.data.Store}.</p>\r
+ * <p>The parameter to a DataProxy constructor may be an {@link Ext.data.Connection} or can also be the\r
+ * config object to an {@link Ext.data.Connection}.</p>\r
+ * <p>Custom implementations must implement either the <code><b>doRequest</b></code> method (preferred) or the\r
+ * <code>load</code> method (deprecated). See\r
+ * {@link Ext.data.HttpProxy}.{@link Ext.data.HttpProxy#doRequest doRequest} or\r
+ * {@link Ext.data.HttpProxy}.{@link Ext.data.HttpProxy#load load} for additional details.</p>\r
+ * <p><b><u>Example 1</u></b></p>\r
+ * <pre><code>\r
+proxy: new Ext.data.ScriptTagProxy({\r
+ {@link Ext.data.Connection#url url}: 'http://extjs.com/forum/topics-remote.php'\r
+}),\r
+ * </code></pre>\r
+ * <p><b><u>Example 2</u></b></p>\r
+ * <pre><code>\r
+proxy : new Ext.data.HttpProxy({\r
+ {@link Ext.data.Connection#method method}: 'GET',\r
+ {@link Ext.data.HttpProxy#prettyUrls prettyUrls}: false,\r
+ {@link Ext.data.Connection#url url}: 'local/default.php', // see options parameter for {@link Ext.Ajax#request}\r
+ {@link #api}: {\r
+ // all actions except the following will use above url\r
+ create : 'local/new.php',\r
+ update : 'local/update.php'\r
+ }\r
+}),\r
+ * </code></pre>\r
+ */\r
+Ext.data.DataProxy = function(conn){\r
+ // make sure we have a config object here to support ux proxies.\r
+ // All proxies should now send config into superclass constructor.\r
+ conn = conn || {};\r
+\r
+ // This line caused a bug when people use custom Connection object having its own request method.\r
+ // http://extjs.com/forum/showthread.php?t=67194. Have to set DataProxy config\r
+ //Ext.applyIf(this, conn);\r
+\r
+ this.api = conn.api;\r
+ this.url = conn.url;\r
+ this.restful = conn.restful;\r
+ this.listeners = conn.listeners;\r
+\r
+ // deprecated\r
+ this.prettyUrls = conn.prettyUrls;\r
+\r
+ <div id="cfg-Ext.data.DataProxy-api"></div>/**\r
+ * @cfg {Object} api\r
+ * Specific urls to call on CRUD action methods "read", "create", "update" and "destroy".\r
+ * Defaults to:<pre><code>\r
+api: {\r
+ read : undefined,\r
+ create : undefined,\r
+ update : undefined,\r
+ destroy : undefined\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
+ * property should be modified before the action is requested using the corresponding before\r
+ * action event. For example to modify the URL associated with the load action:\r
+ * <pre><code>\r
+// modify the url for the action\r
+myStore.on({\r
+ beforeload: {\r
+ fn: function (store, options) {\r
+ // use <tt>{@link Ext.data.HttpProxy#setUrl setUrl}</tt> to change the URL for *just* this request.\r
+ store.proxy.setUrl('changed1.php');\r
+\r
+ // set optional second parameter to true to make this URL change\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
+\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
+ // API -- not just a specific action of it.\r
+ store.proxy.setApi({\r
+ read : 'changed_read.php',\r
+ create : 'changed_create.php',\r
+ update : 'changed_update.php',\r
+ destroy : 'changed_destroy.php'\r
+ });\r
+ }\r
+ }\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
+ * <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
+ * <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></li>\r
+ * <li>remote-request <b>succeeded</b> : <div class="sub-desc">\r
+ * The remote-request succeeded but the reader could not read the response.\r
+ * This means the server returned data, but the configured Reader threw an\r
+ * error while reading the response. In this case, this event will be\r
+ * raised and the caught error will be passed along into this event.\r
+ * </div></li>\r
+ * </ul></div>\r
+ * <br><p>This event fires with two different contexts based upon the 2nd\r
+ * parameter <tt>type [remote|response]</tt>. The first four parameters\r
+ * are identical between the two contexts -- only the final two parameters\r
+ * differ.</p>\r
+ * @param {DataProxy} this The proxy that sent the request\r
+ * @param {String} type\r
+ * <p>The value of this parameter will be either <tt>'response'</tt> or <tt>'remote'</tt>.</p>\r
+ * <div class="mdetail-params"><ul>\r
+ * <li><b><tt>'response'</tt></b> : <div class="sub-desc">\r
+ * <p>An <b>invalid</b> response from the server was returned: either 404,\r
+ * 500 or the response meta-data does not match that defined in the DataReader\r
+ * (e.g.: root, idProperty, successProperty).</p>\r
+ * </div></li>\r
+ * <li><b><tt>'remote'</tt></b> : <div class="sub-desc">\r
+ * <p>A <b>valid</b> response was returned from the server having\r
+ * successProperty === false. This response might contain an error-message\r
+ * sent from the server. For example, the user may have failed\r
+ * authentication/authorization or a database validation error occurred.</p>\r
+ * </div></li>\r
+ * </ul></div>\r
+ * @param {String} action Name of the action (see {@link Ext.data.Api#actions}.\r
+ * @param {Object} options The options for the action that were specified in the {@link #request}.\r
+ * @param {Object} response\r
+ * <p>The value of this parameter depends on the value of the <code>type</code> parameter:</p>\r
+ * <div class="mdetail-params"><ul>\r
+ * <li><b><tt>'response'</tt></b> : <div class="sub-desc">\r
+ * <p>The raw browser response object (e.g.: XMLHttpRequest)</p>\r
+ * </div></li>\r
+ * <li><b><tt>'remote'</tt></b> : <div class="sub-desc">\r
+ * <p>The decoded response object sent from the server.</p>\r
+ * </div></li>\r
+ * </ul></div>\r
+ * @param {Mixed} arg\r
+ * <p>The type and value of this parameter depends on the value of the <code>type</code> parameter:</p>\r
+ * <div class="mdetail-params"><ul>\r
+ * <li><b><tt>'response'</tt></b> : Error<div class="sub-desc">\r
+ * <p>The JavaScript Error object caught if the configured Reader could not read the data.\r
+ * If the remote request returns success===false, this parameter will be null.</p>\r
+ * </div></li>\r
+ * <li><b><tt>'remote'</tt></b> : Record/Record[]<div class="sub-desc">\r
+ * <p>This parameter will only exist if the <tt>action</tt> was a <b>write</b> action\r
+ * (Ext.data.Api.actions.create|update|destroy).</p>\r
+ * </div></li>\r
+ * </ul></div>\r
+ */\r
+ 'exception',\r
+ <div id="event-Ext.data.DataProxy-beforeload"></div>/**\r
+ * @event beforeload\r
+ * Fires before a request to retrieve a data object.\r
+ * @param {DataProxy} this The proxy for the request\r
+ * @param {Object} params The params object passed to the {@link #request} function\r
+ */\r
+ 'beforeload',\r
+ <div id="event-Ext.data.DataProxy-load"></div>/**\r
+ * @event load\r
+ * Fires before the load method's callback is called.\r
+ * @param {DataProxy} this The proxy for the request\r
+ * @param {Object} o The request transaction object\r
+ * @param {Object} options The callback's <tt>options</tt> property as passed to the {@link #request} function\r
+ */\r
+ 'load',\r
+ <div id="event-Ext.data.DataProxy-loadexception"></div>/**\r
+ * @event loadexception\r
+ * <p>This event is <b>deprecated</b>. The signature of the loadexception event\r
+ * varies depending on the proxy, use the catch-all {@link #exception} event instead.\r
+ * This event will fire in addition to the {@link #exception} event.</p>\r
+ * @param {misc} misc See {@link #exception}.\r
+ * @deprecated\r
+ */\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
+ * @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 {Object} params The request <code>params</code> object. Edit <code>params</code> to add parameters to the request.\r
+ */\r
+ 'beforewrite',\r
+ <div id="event-Ext.data.DataProxy-write"></div>/**\r
+ * @event write\r
+ * Fires before the request-callback is called\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 {Object} response The decoded response from server\r
+ * @param {Record/Record{}} rs The records from Store\r
+ * @param {Object} options The callback's <tt>options</tt> property as passed to the {@link #request} function\r
+ */\r
+ 'write'\r
+ );\r
+ Ext.data.DataProxy.superclass.constructor.call(this);\r
+};\r
+\r
+Ext.extend(Ext.data.DataProxy, Ext.util.Observable, {\r
+ <div id="cfg-Ext.data.DataProxy-restful"></div>/**\r
+ * @cfg {Boolean} restful\r
+ * <p>Defaults to <tt>false</tt>. Set to <tt>true</tt> to operate in a RESTful manner.</p>\r
+ * <br><p> Note: this parameter will automatically be set to <tt>true</tt> if the\r
+ * {@link Ext.data.Store} it is plugged into is set to <code>restful: true</code>. If the\r
+ * Store is RESTful, there is no need to set this option on the proxy.</p>\r
+ * <br><p>RESTful implementations enable the serverside framework to automatically route\r
+ * actions sent to one url based upon the HTTP method, for example:\r
+ * <pre><code>\r
+store: new Ext.data.Store({\r
+ restful: true,\r
+ proxy: new Ext.data.HttpProxy({url:'/users'}); // all requests sent to /users\r
+ ...\r
+)}\r
+ * </code></pre>\r
+ * 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
+<u>Method</u> <u>url</u> <u>action</u>\r
+POST /users create\r
+GET /users read\r
+PUT /users/23 update\r
+DESTROY /users/23 delete\r
+ * </pre></p>\r
+ */\r
+ restful: false,\r
+\r
+ <div id="method-Ext.data.DataProxy-setApi"></div>/**\r
+ * <p>Redefines the Proxy's API or a single action of an API. Can be called with two method signatures.</p>\r
+ * <p>If called with an object as the only parameter, the object should redefine the <b>entire</b> API, e.g.:</p><pre><code>\r
+proxy.setApi({\r
+ read : '/users/read',\r
+ create : '/users/create',\r
+ update : '/users/update',\r
+ destroy : '/users/destroy'\r
+});\r
+</code></pre>\r
+ * <p>If called with two parameters, the first parameter should be a string specifying the API action to\r
+ * redefine and the second parameter should be the URL (or function if using DirectProxy) to call for that action, e.g.:</p><pre><code>\r
+proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');\r
+</code></pre>\r
+ * @param {String/Object} api An API specification object, or the name of an action.\r
+ * @param {String/Function} url The URL (or function if using DirectProxy) to call for the action.\r
+ */\r
+ setApi : function() {\r
+ if (arguments.length == 1) {\r
+ var valid = Ext.data.Api.isValid(arguments[0]);\r
+ if (valid === true) {\r
+ this.api = arguments[0];\r
+ }\r
+ else {\r
+ throw new Ext.data.Api.Error('invalid', valid);\r
+ }\r
+ }\r
+ else if (arguments.length == 2) {\r
+ if (!Ext.data.Api.isAction(arguments[0])) {\r
+ throw new Ext.data.Api.Error('invalid', arguments[0]);\r
+ }\r
+ this.api[arguments[0]] = arguments[1];\r
+ }\r
+ Ext.data.Api.prepare(this);\r
+ },\r
+\r
+ <div id="method-Ext.data.DataProxy-isApiAction"></div>/**\r
+ * Returns true if the specified action is defined as a unique action in the api-config.\r
+ * request. If all API-actions are routed to unique urls, the xaction parameter is unecessary. However, if no api is defined\r
+ * and all Proxy actions are routed to DataProxy#url, the server-side will require the xaction parameter to perform a switch to\r
+ * the corresponding code for CRUD action.\r
+ * @param {String [Ext.data.Api.CREATE|READ|UPDATE|DESTROY]} action\r
+ * @return {Boolean}\r
+ */\r
+ isApiAction : function(action) {\r
+ return (this.api[action]) ? true : false;\r
+ },\r
+\r
+ <div id="method-Ext.data.DataProxy-request"></div>/**\r
+ * All proxy actions are executed through this method. Automatically fires the "before" + action event\r
+ * @param {String} action Name of the action\r
+ * @param {Ext.data.Record/Ext.data.Record[]/null} rs Will be null when action is 'load'\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} 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
+ if (!this.api[action] && !this.load) {\r
+ throw new Ext.data.DataProxy.Error('action-undefined', action);\r
+ }\r
+ params = params || {};\r
+ if ((action === Ext.data.Api.actions.read) ? this.fireEvent("beforeload", this, params) : this.fireEvent("beforewrite", this, action, rs, params) !== false) {\r
+ this.doRequest.apply(this, arguments);\r
+ }\r
+ else {\r
+ callback.call(scope || this, null, options, false);\r
+ }\r
+ },\r
+\r
+\r
+ <div id="method-Ext.data.DataProxy-load"></div>/**\r
+ * <b>Deprecated</b> load method using old method signature. See {@doRequest} for preferred method.\r
+ * @deprecated\r
+ * @param {Object} params\r
+ * @param {Object} reader\r
+ * @param {Object} callback\r
+ * @param {Object} scope\r
+ * @param {Object} arg\r
+ */\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
+ * (e.g.: {@link Ext.data.HttpProxy#doRequest HttpProxy.doRequest},\r
+ * {@link Ext.data.DirectProxy#doRequest DirectProxy.doRequest}).\r
+ */\r
+ doRequest : function(action, rs, params, reader, callback, scope, options) {\r
+ // default implementation of doRequest for backwards compatibility with 2.0 proxies.\r
+ // If we're executing here, the action is probably "load".\r
+ // Call with the pre-3.0 method signature.\r
+ this.load(params, reader, callback, scope, options);\r
+ },\r
+\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
+ * url will be built Rails-style, as in "/controller/action/32". restful will aply iff the supplied record is an\r
+ * instance of Ext.data.Record rather than an Array of them.\r
+ * @param {String} action The api action being executed [read|create|update|destroy]\r
+ * @param {Ext.data.Record/Array[Ext.data.Record]} The record or Array of Records being acted upon.\r
+ * @return {String} url\r
+ * @private\r
+ */\r
+ buildUrl : function(action, record) {\r
+ record = record || null;\r
+ var 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
+ var format = null;\r
+ var m = url.match(/(.*)(\.\w+)$/); // <-- look for urls with "provides" suffix, e.g.: /users.json, /users.xml, etc\r
+ if (m) {\r
+ format = m[2];\r
+ url = m[1];\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
+ 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
+ },\r
+\r
+ <div id="method-Ext.data.DataProxy-destroy"></div>/**\r
+ * Destroys the proxy by purging any event listeners and cancelling any active requests.\r
+ */\r
+ destroy: function(){\r
+ this.purgeListeners();\r
+ }\r
+});\r
+\r
+<div id="cls-Ext.data.DataProxy.Error"></div>/**\r
+ * @class Ext.data.DataProxy.Error\r
+ * @extends Ext.Error\r
+ * DataProxy Error extension.\r
+ * constructor\r
+ * @param {String} name\r
+ * @param {Record/Array[Record]/Array}\r
+ */\r
+Ext.data.DataProxy.Error = Ext.extend(Ext.Error, {\r
+ constructor : function(message, arg) {\r
+ this.arg = arg;\r
+ Ext.Error.call(this, message);\r
+ },\r
+ name: 'Ext.data.DataProxy'\r
+});\r
+Ext.apply(Ext.data.DataProxy.Error.prototype, {\r
+ lang: {\r
+ 'action-undefined': "DataProxy attempted to execute an API-action but found an undefined url / function. Please review your Proxy url/api-configuration.",\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
+</pre> \r
+</body>\r
+</html>
\ No newline at end of file
git.ithinksw.org / extjs.git / blobdiff