Abstract 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
- *
-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: - *
-// 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:
- *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'.
- *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).
- *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:
The raw browser response object (e.g.: XMLHttpRequest)
- *The decoded response object sent from the server.
- *The type and value of this parameter depends on the value of the type parameter:
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.
- *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. Edit params 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: - *
-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.:
-proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
-Abstract 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
+ *
+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'
+ }
+}),
+ * And new in Ext version 3, attach centralized event-listeners upon the DataProxy class itself! This is a great place + * to implement a messaging system to centralize your application's user-feedback and error-handling.
+ *
+// Listen to all "beforewrite" event fired by all proxies.
+Ext.data.DataProxy.on('beforewrite', function(proxy, action) {
+ console.log('beforewrite: ', action);
+});
+
+// Listen to "write" event fired by all proxies
+Ext.data.DataProxy.on('write', function(proxy, action, data, res, rs) {
+ console.info('write: ', action);
+});
+
+// Listen to "exception" event fired by all proxies
+Ext.data.DataProxy.on('exception', function(proxy, type, action) {
+ console.error(type + action + ' exception);
+});
+ *
+api: {
+ read : undefined,
+ create : undefined,
+ update : undefined,
+ destroy : undefined
+}
+ * The url is built based upon the action being executed [load|create|save|destroy] + * using the commensurate {@link #api} property, or if undefined default to the + * configured {@link Ext.data.Store}.{@link Ext.data.Store#url url}.
For example:
+ *
+api: {
+ load : '/controller/load',
+ create : '/controller/new', // Server MUST return idProperty of new record
+ save : '/controller/update',
+ destroy : '/controller/destroy_action'
+}
+
+// Alternatively, one can use the object-form to specify each API-action
+api: {
+ load: {url: 'read.php', method: 'GET'},
+ create: 'create.php',
+ destroy: 'destroy.php',
+ save: 'update.php'
+}
+ * 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: + *
+// 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);
+
+ // Altering the proxy API should be done using the public
+ // method {@link Ext.data.DataProxy#setApi setApi}.
+ store.proxy.setApi('read', '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.
+ *In addition to being fired through the DataProxy instance that raised the event, this event is also fired + * through the Ext.data.DataProxy class to allow for centralized processing of exception events from all + * DataProxies by attaching a listener to the Ext.data.Proxy class itself.
+ *This event can be fired for one of two reasons:
+ *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'.
+ *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).
+ *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:
The raw browser response object (e.g.: XMLHttpRequest)
+ *The decoded response object sent from the server.
+ *The type and value of this parameter depends on the value of the type parameter:
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.
+ *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
+ *In addition to being fired through the DataProxy instance that raised the event, this event is also fired + * through the Ext.data.DataProxy class to allow for centralized processing of beforewrite events from all + * DataProxies by attaching a listener to the Ext.data.Proxy class itself.
+ * @param {DataProxy} this The proxy for the request + * @param {String} action [Ext.data.Api.actions.create|update|destroy] + * @param {Record/Record[]} rs The Record(s) to create|update|destroy. + * @param {Object} params The requestparams object. Edit params to add parameters to the request.
+ */
+ 'beforewrite',
+ /**
+ * @event write
+ * Fires before the request-callback is called
+ *In addition to being fired through the DataProxy instance that raised the event, this event is also fired + * through the Ext.data.DataProxy class to allow for centralized processing of write events from all + * DataProxies by attaching a listener to the Ext.data.Proxy class itself.
+ * @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 Record(s) 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); + + // 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(); + } + } + // relay each proxy's events onto Ext.data.DataProxy class for centralized Proxy-listening + Ext.data.DataProxy.relayEvents(this, ['beforewrite', 'write', 'exception']); +}; + +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: + *
+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 + *+ *
If set to true, a {@link Ext.data.Record#phantom non-phantom} record's + * {@link Ext.data.Record#id id} will be appended to the url. Some MVC (e.g., Ruby on Rails, + * Merb and Django) support segment based urls where the segments in the URL follow the + * Model-View-Controller approach:
+ * someSite.com/controller/action/id
+ * Refer to {@link Ext.data.DataProxy#api} for additional information.
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.:
+proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
+this reference) in which the callback function is executed. 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. Note: Should only be used by custom-proxy developers.
+ * (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);
+ },
+
+ /**
+ * @cfg {Function} onRead Abstract method that should be implemented in all subclasses. Note: Should only be used by custom-proxy developers. Callback for read {@link Ext.data.Api#actions action}.
+ * @param {String} action Action name as per {@link Ext.data.Api.actions#read}.
+ * @param {Object} o The request transaction object
+ * @param {Object} res The server response
+ * @fires loadexception (deprecated)
+ * @fires exception
+ * @fires load
+ * @protected
+ */
+ onRead : Ext.emptyFn,
+ /**
+ * @cfg {Function} onWrite Abstract method that should be implemented in all subclasses. Note: Should only be used by custom-proxy developers. Callback for create, update and destroy {@link Ext.data.Api#actions actions}.
+ * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]
+ * @param {Object} trans The request transaction object
+ * @param {Object} res The server response
+ * @fires exception
+ * @fires write
+ * @protected
+ */
+ onWrite : Ext.emptyFn,
+ /**
+ * 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/Ext.data.Record[]} record The record or Array of Records being acted upon.
+ * @return {String} url
+ * @private
+ */
+ buildUrl : function(action, record) {
+ record = record || null;
+
+ // conn.url gets nullified after each request. If it's NOT null here, that means the user must have intervened with a call
+ // to DataProxy#setUrl or DataProxy#setApi and changed it before the request was executed. If that's the case, use conn.url,
+ // otherwise, build the url from the api or this.url.
+ var url = (this.conn && this.conn.url) ? this.conn.url : (this.api[action]) ? this.api[action].url : this.url;
+ if (!url) {
+ throw new Ext.data.Api.Error('invalid-url', action);
+ }
+
+ // look for urls having "provides" suffix used in some MVC frameworks like Rails/Merb and others. The provides suffice informs
+ // the server what data-format the client is dealing with and returns data in the same format (eg: application/json, application/xml, etc)
+ // e.g.: /users.json, /users.xml, etc.
+ // with restful routes, we need urls like:
+ // PUT /users/1.json
+ // DELETE /users/1.json
+ var provides = null;
+ var m = url.match(/(.*)(\.json|\.xml|\.html)$/);
+ if (m) {
+ provides = m[2]; // eg ".json"
+ url = m[1]; // eg: "/users"
+ }
+ // prettyUrls is deprectated in favor of restful-config
+ if ((this.restful === true || this.prettyUrls === true) && record instanceof Ext.data.Record && !record.phantom) {
+ url += '/' + record.id;
+ }
+ return (provides === null) ? url : url + provides;
+ },
+
+ /**
+ * Destroys the proxy by purging any event listeners and cancelling any active requests.
+ */
+ destroy: function(){
+ this.purgeListeners();
+ }
+});
+
+// Apply the Observable prototype to the DataProxy class so that proxy instances can relay their
+// events to the class. Allows for centralized listening of all proxy instances upon the DataProxy class.
+Ext.apply(Ext.data.DataProxy, Ext.util.Observable.prototype);
+Ext.util.Observable.call(Ext.data.DataProxy);
+
+/**
+ * @class Ext.data.DataProxy.Error
+ * @extends Ext.Error
+ * DataProxy Error extension.
+ * constructor
+ * @param {String} message Message describing the error.
+ * @param {Record/Record[]} arg
+ */
+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.'
+ }
+});
+
+