X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/ee06f37b0f6f6d94cd05a6ffae556660f7c4a2bc..c930e9176a5a85509c5b0230e2bff5c22a591432:/docs/source/DataProxy.html diff --git a/docs/source/DataProxy.html b/docs/source/DataProxy.html new file mode 100644 index 00000000..c37e14a2 --- /dev/null +++ b/docs/source/DataProxy.html @@ -0,0 +1,431 @@ + +
+/** + * @class Ext.data.DataProxy + * @extends Ext.util.Observable + *+ + \ No newline at end of fileAbstract base class for implementations which provide retrieval of unformatted data objects. + * This class is intended to be extended and should not be created directly. For existing implementations, + * see {@link Ext.data.DirectProxy}, {@link Ext.data.HttpProxy}, {@link Ext.data.ScriptTagProxy} and + * {@link Ext.data.MemoryProxy}.
+ *DataProxy implementations are usually used in conjunction with an implementation of {@link Ext.data.DataReader} + * (of the appropriate type which knows how to parse the data object) to provide a block of + * {@link Ext.data.Records} to an {@link Ext.data.Store}.
+ *The parameter to a DataProxy constructor may be an {@link Ext.data.Connection} or can also be the + * config object to an {@link Ext.data.Connection}.
+ *Custom implementations must implement either the
+ *doRequest
method (preferred) or the + *load
method (deprecated). See + * {@link Ext.data.HttpProxy}.{@link Ext.data.HttpProxy#doRequest doRequest} or + * {@link Ext.data.HttpProxy}.{@link Ext.data.HttpProxy#load load} for additional details.Example 1
+ *+ *+proxy: new Ext.data.ScriptTagProxy({ + {@link Ext.data.Connection#url url}: 'http://extjs.com/forum/topics-remote.php' +}), + *
Example 2
+ *+ */ +Ext.data.DataProxy = function(conn){ + // make sure we have a config object here to support ux proxies. + // All proxies should now send config into superclass constructor. + conn = conn || {}; + + // This line caused a bug when people use custom Connection object having its own request method. + // http://extjs.com/forum/showthread.php?t=67194. Have to set DataProxy config + //Ext.applyIf(this, conn); + + this.api = conn.api; + this.url = conn.url; + this.restful = conn.restful; + this.listeners = conn.listeners; + + // deprecated + this.prettyUrls = conn.prettyUrls; + + /** + * @cfg {Object} api + * Specific urls to call on CRUD action methods "read", "create", "update" and "destroy". + * Defaults to:+proxy : new Ext.data.HttpProxy({ + {@link Ext.data.Connection#method method}: 'GET', + {@link Ext.data.HttpProxy#prettyUrls prettyUrls}: false, + {@link Ext.data.Connection#url url}: 'local/default.php', // see options parameter for {@link Ext.Ajax#request} + {@link #api}: { + // all actions except the following will use above url + create : 'local/new.php', + update : 'local/update.php' + } +}), + *
+ *+api: { + read : undefined, + create : undefined, + update : undefined, + destroy : undefined +} +
If the specific URL for a given CRUD action is undefined, the CRUD action request + * will be directed to the configured {@link Ext.data.Connection#url url}.
+ *Note: To modify the URL for an action dynamically the appropriate API + * property should be modified before the action is requested using the corresponding before + * action event. For example to modify the URL associated with the load action: + *
+ * + */ + // Prepare the proxy api. Ensures all API-actions are defined with the Object-form. + try { + Ext.data.Api.prepare(this); + } catch (e) { + if (e instanceof Ext.data.Api.Error) { + e.toConsole(); + } + } + + this.addEvents( + /** + * @event exception + *+// modify the url for the action +myStore.on({ + beforeload: { + fn: function (store, options) { + // use {@link Ext.data.HttpProxy#setUrl setUrl} to change the URL for *just* this request. + store.proxy.setUrl('changed1.php'); + + // set optional second parameter to true to make this URL change + // permanent, applying this URL for all subsequent requests. + store.proxy.setUrl('changed1.php', true); + + // manually set the private connection URL. + // Warning: Accessing the private URL property should be avoided. + // Use the public method {@link Ext.data.HttpProxy#setUrl setUrl} instead, shown above. + // It should be noted that changing the URL like this will affect + // the URL for just this request. Subsequent requests will use the + // API or URL defined in your initial proxy configuration. + store.proxy.conn.url = 'changed1.php'; + + // proxy URL will be superseded by API (only if proxy created to use ajax): + // It should be noted that proxy API changes are permanent and will + // be used for all subsequent requests. + store.proxy.api.load = 'changed2.php'; + + // However, altering the proxy API should be done using the public + // method {@link Ext.data.DataProxy#setApi setApi} instead. + store.proxy.setApi('load', 'changed2.php'); + + // Or set the entire API with a config-object. + // When using the config-object option, you must redefine the entire + // API -- not just a specific action of it. + store.proxy.setApi({ + read : 'changed_read.php', + create : 'changed_create.php', + update : 'changed_update.php', + destroy : 'changed_destroy.php' + }); + } + } +}); + *
Fires if an exception occurs in the Proxy during a remote request. + * This event is relayed through a corresponding + * {@link Ext.data.Store}.{@link Ext.data.Store#exception exception}, + * so any Store instance may observe this event. + * This event can be fired for one of two reasons:
+ *+ *+ *
- remote-request failed :
+ *+ * The server did not return status === 200. + *- remote-request succeeded :
+ *+ * The remote-request succeeded but the reader could not read the response. + * This means the server returned data, but the configured Reader threw an + * error while reading the response. In this case, this event will be + * raised and the caught error will be passed along into this event. + *This event fires with two different contexts based upon the 2nd + * parameter type [remote|response]. The first four parameters + * are identical between the two contexts -- only the final two parameters + * differ.
+ * @param {DataProxy} this The proxy that sent the request + * @param {String} type + *The value of this parameter will be either 'response' or 'remote'.
+ *+ * @param {String} action Name of the action (see {@link Ext.data.Api#actions}. + * @param {Object} options The options for the action that were specified in the {@link #request}. + * @param {Object} response + *+ *
- 'response' :
+ *+ *An invalid response from the server was returned: either 404, + * 500 or the response meta-data does not match that defined in the DataReader + * (e.g.: root, idProperty, successProperty).
+ *- 'remote' :
+ *+ *A valid response was returned from the server having + * successProperty === false. This response might contain an error-message + * sent from the server. For example, the user may have failed + * authentication/authorization or a database validation error occurred.
+ *The value of this parameter depends on the value of the
+ *type
parameter:+ * @param {Mixed} arg + *+ *
- 'response' :
+ *+ *The raw browser response object (e.g.: XMLHttpRequest)
+ *- 'remote' :
+ *+ *The decoded response object sent from the server.
+ *The type and value of this parameter depends on the value of the
+ *type
parameter:+ */ + 'exception', + /** + * @event beforeload + * Fires before a request to retrieve a data object. + * @param {DataProxy} this The proxy for the request + * @param {Object} params The params object passed to the {@link #request} function + */ + 'beforeload', + /** + * @event load + * Fires before the load method's callback is called. + * @param {DataProxy} this The proxy for the request + * @param {Object} o The request transaction object + * @param {Object} options The callback's options property as passed to the {@link #request} function + */ + 'load', + /** + * @event loadexception + *+ *
- 'response' : Error
+ *+ *The JavaScript Error object caught if the configured Reader could not read the data. + * If the remote request returns success===false, this parameter will be null.
+ *- 'remote' : Record/Record[]
+ *+ *This parameter will only exist if the action was a write action + * (Ext.data.Api.actions.create|update|destroy).
+ *This event is deprecated. The signature of the loadexception event + * varies depending on the proxy, use the catch-all {@link #exception} event instead. + * This event will fire in addition to the {@link #exception} event.
+ * @param {misc} misc See {@link #exception}. + * @deprecated + */ + 'loadexception', + /** + * @event beforewrite + * Fires before a request is generated for one of the actions Ext.data.Api.actions.create|update|destroy + * @param {DataProxy} this The proxy for the request + * @param {String} action [Ext.data.Api.actions.create|update|destroy] + * @param {Record/Array[Record]} rs The Record(s) to create|update|destroy. + * @param {Object} params The requestparams
object. Editparams
to add parameters to the request. + */ + 'beforewrite', + /** + * @event write + * Fires before the request-callback is called + * @param {DataProxy} this The proxy that sent the request + * @param {String} action [Ext.data.Api.actions.create|upate|destroy] + * @param {Object} data The data object extracted from the server-response + * @param {Object} response The decoded response from server + * @param {Record/Record{}} rs The records from Store + * @param {Object} options The callback's options property as passed to the {@link #request} function + */ + 'write' + ); + Ext.data.DataProxy.superclass.constructor.call(this); +}; + +Ext.extend(Ext.data.DataProxy, Ext.util.Observable, { + /** + * @cfg {Boolean} restful + *Defaults to false. Set to true to operate in a RESTful manner.
+ *Note: this parameter will automatically be set to true if the + * {@link Ext.data.Store} it is plugged into is set to
+ *restful: true
. If the + * Store is RESTful, there is no need to set this option on the proxy.RESTful implementations enable the serverside framework to automatically route + * actions sent to one url based upon the HTTP method, for example: + *
+ * There is no+store: new Ext.data.Store({ + restful: true, + proxy: new Ext.data.HttpProxy({url:'/users'}); // all requests sent to /users + ... +)} + *
{@link #api}
specified in the configuration of the proxy, + * all requests will be marshalled to a single RESTful url (/users) so the serverside + * framework can inspect the HTTP Method and act accordingly: + *+Method url action +POST /users create +GET /users read +PUT /users/23 update +DESTROY /users/23 delete + *+ */ + restful: false, + + /** + *Redefines the Proxy's API or a single action of an API. Can be called with two method signatures.
+ *If called with an object as the only parameter, the object should redefine the entire API, e.g.:
+ *+proxy.setApi({ + read : '/users/read', + create : '/users/create', + update : '/users/update', + destroy : '/users/destroy' +}); +
If called with two parameters, the first parameter should be a string specifying the API action to + * redefine and the second parameter should be the URL (or function if using DirectProxy) to call for that action, e.g.:
+ * @param {String/Object} api An API specification object, or the name of an action. + * @param {String/Function} url The URL (or function if using DirectProxy) to call for the action. + */ + setApi : function() { + if (arguments.length == 1) { + var valid = Ext.data.Api.isValid(arguments[0]); + if (valid === true) { + this.api = arguments[0]; + } + else { + throw new Ext.data.Api.Error('invalid', valid); + } + } + else if (arguments.length == 2) { + if (!Ext.data.Api.isAction(arguments[0])) { + throw new Ext.data.Api.Error('invalid', arguments[0]); + } + this.api[arguments[0]] = arguments[1]; + } + Ext.data.Api.prepare(this); + }, + + /** + * Returns true if the specified action is defined as a unique action in the api-config. + * request. If all API-actions are routed to unique urls, the xaction parameter is unecessary. However, if no api is defined + * and all Proxy actions are routed to DataProxy#url, the server-side will require the xaction parameter to perform a switch to + * the corresponding code for CRUD action. + * @param {String [Ext.data.Api.CREATE|READ|UPDATE|DESTROY]} action + * @return {Boolean} + */ + isApiAction : function(action) { + return (this.api[action]) ? true : false; + }, + + /** + * All proxy actions are executed through this method. Automatically fires the "before" + action event + * @param {String} action Name of the action + * @param {Ext.data.Record/Ext.data.Record[]/null} rs Will be null when action is 'load' + * @param {Object} params + * @param {Ext.data.DataReader} reader + * @param {Function} callback + * @param {Object} scope Scope with which to call the callback (defaults to the Proxy object) + * @param {Object} options Any options specified for the action (e.g. see {@link Ext.data.Store#load}. + */ + request : function(action, rs, params, reader, callback, scope, options) { + if (!this.api[action] && !this.load) { + throw new Ext.data.DataProxy.Error('action-undefined', action); + } + params = params || {}; + if ((action === Ext.data.Api.actions.read) ? this.fireEvent("beforeload", this, params) : this.fireEvent("beforewrite", this, action, rs, params) !== false) { + this.doRequest.apply(this, arguments); + } + else { + callback.call(scope || this, null, options, false); + } + }, + + + /** + * Deprecated load method using old method signature. See {@doRequest} for preferred method. + * @deprecated + * @param {Object} params + * @param {Object} reader + * @param {Object} callback + * @param {Object} scope + * @param {Object} arg + */ + load : null, + + /** + * @cfg {Function} doRequest Abstract method that should be implemented in all subclasses + * (e.g.: {@link Ext.data.HttpProxy#doRequest HttpProxy.doRequest}, + * {@link Ext.data.DirectProxy#doRequest DirectProxy.doRequest}). + */ + doRequest : function(action, rs, params, reader, callback, scope, options) { + // default implementation of doRequest for backwards compatibility with 2.0 proxies. + // If we're executing here, the action is probably "load". + // Call with the pre-3.0 method signature. + this.load(params, reader, callback, scope, options); + }, + + /** + * buildUrl + * Sets the appropriate url based upon the action being executed. If restful is true, and only a single record is being acted upon, + * url will be built Rails-style, as in "/controller/action/32". restful will aply iff the supplied record is an + * instance of Ext.data.Record rather than an Array of them. + * @param {String} action The api action being executed [read|create|update|destroy] + * @param {Ext.data.Record/Array[Ext.data.Record]} The record or Array of Records being acted upon. + * @return {String} url + * @private + */ + buildUrl : function(action, record) { + record = record || null; + var url = (this.api[action]) ? this.api[action].url : this.url; + if (!url) { + throw new Ext.data.Api.Error('invalid-url', action); + } + + var format = null; + var m = url.match(/(.*)(\.\w+)$/); // <-- look for urls with "provides" suffix, e.g.: /users.json, /users.xml, etc + if (m) { + format = m[2]; + url = m[1]; + } + // prettyUrls is deprectated in favor of restful-config + if ((this.prettyUrls === true || this.restful === true) && record instanceof Ext.data.Record && !record.phantom) { + url += '/' + record.id; + } + if (format) { // <-- append the request format if exists (ie: /users/update/69[.json]) + url += format; + } + return url; + }, + + /** + * Destroys the proxy by purging any event listeners and cancelling any active requests. + */ + destroy: function(){ + this.purgeListeners(); + } +}); + +/** + * @class Ext.data.DataProxy.Error + * @extends Ext.Error + * DataProxy Error extension. + * constructor + * @param {String} name + * @param {Record/Array[Record]/Array} + */ +Ext.data.DataProxy.Error = Ext.extend(Ext.Error, { + constructor : function(message, arg) { + this.arg = arg; + Ext.Error.call(this, message); + }, + name: 'Ext.data.DataProxy' +}); +Ext.apply(Ext.data.DataProxy.Error.prototype, { + lang: { + 'action-undefined': "DataProxy attempted to execute an API-action but found an undefined url / function. Please review your Proxy url/api-configuration.", + 'api-invalid': 'Recieved an invalid API-configuration. Please ensure your proxy API-configuration contains only the actions from Ext.data.Api.actions.' + } +}); ++proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url'); +