Upgrade to ExtJS 3.0.0 - Released 07/06/2009
[extjs.git] / docs / source / Api.html
1 <html>\r
2 <head>\r
3   <title>The source code</title>\r
4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
6 </head>\r
7 <body  onload="prettyPrint();">\r
8     <pre class="prettyprint lang-js"><div id="cls-Ext.data.Api"></div>/**
9  * @class Ext.data.Api
10  * @extends Object
11  * Ext.data.Api is a singleton designed to manage the data API including methods
12  * for validating a developer's DataProxy API.  Defines variables for CRUD actions
13  * create, read, update and destroy in addition to a mapping of RESTful HTTP methods
14  * GET, POST, PUT and DELETE to CRUD actions.
15  * @singleton
16  */
17 Ext.data.Api = (function() {
18
19     // private validActions.  validActions is essentially an inverted hash of Ext.data.Api.actions, where value becomes the key.
20     // Some methods in this singleton (e.g.: getActions, getVerb) will loop through actions with the code <code>for (var verb in this.actions)</code>
21     // For efficiency, some methods will first check this hash for a match.  Those methods which do acces validActions will cache their result here.
22     // We cannot pre-define this hash since the developer may over-ride the actions at runtime.
23     var validActions = {};
24
25     return {
26         <div id="prop-Ext.data.Api-actions"></div>/**
27          * Defined actions corresponding to remote actions:
28          * <pre><code>
29 actions: {
30     create  : 'create',  // Text representing the remote-action to create records on server.
31     read    : 'read',    // Text representing the remote-action to read/load data from server.
32     update  : 'update',  // Text representing the remote-action to update records on server.
33     destroy : 'destroy'  // Text representing the remote-action to destroy records on server.
34 }
35          * </code></pre>
36          * @property actions
37          * @type Object
38          */
39         actions : {
40             create  : 'create',
41             read    : 'read',
42             update  : 'update',
43             destroy : 'destroy'
44         },
45
46         <div id="prop-Ext.data.Api-restActions"></div>/**
47          * Defined {CRUD action}:{HTTP method} pairs to associate HTTP methods with the
48          * corresponding actions for {@link Ext.data.DataProxy#restful RESTful proxies}.
49          * Defaults to:
50          * <pre><code>
51 restActions : {
52     create  : 'POST',
53     read    : 'GET',
54     update  : 'PUT',
55     destroy : 'DELETE'
56 },
57          * </code></pre>
58          */
59         restActions : {
60             create  : 'POST',
61             read    : 'GET',
62             update  : 'PUT',
63             destroy : 'DELETE'
64         },
65
66         <div id="method-Ext.data.Api-isAction"></div>/**
67          * Returns true if supplied action-name is a valid API action defined in <code>{@link #actions}</code> constants
68          * @param {String} action
69          * @param {String[]}(Optional) List of available CRUD actions.  Pass in list when executing multiple times for efficiency.
70          * @return {Boolean}
71          */
72         isAction : function(action) {
73             return (Ext.data.Api.actions[action]) ? true : false;
74         },
75
76         <div id="method-Ext.data.Api-getVerb"></div>/**
77          * Returns the actual CRUD action KEY "create", "read", "update" or "destroy" from the supplied action-name.  This method is used internally and shouldn't generally
78          * need to be used directly.  The key/value pair of Ext.data.Api.actions will often be identical but this is not necessarily true.  A developer can override this naming
79          * convention if desired.  However, the framework internally calls methods based upon the KEY so a way of retreiving the the words "create", "read", "update" and "destroy" is
80          * required.  This method will cache discovered KEYS into the private validActions hash.
81          * @param {String} name The runtime name of the action.
82          * @return {String||null} returns the action-key, or verb of the user-action or null if invalid.
83          * @nodoc
84          */
85         getVerb : function(name) {
86             if (validActions[name]) {
87                 return validActions[name];  // <-- found in cache.  return immediately.
88             }
89             for (var verb in this.actions) {
90                 if (this.actions[verb] === name) {
91                     validActions[name] = verb;
92                     break;
93                 }
94             }
95             return (validActions[name] !== undefined) ? validActions[name] : null;
96         },
97
98         <div id="method-Ext.data.Api-isValid"></div>/**
99          * Returns true if the supplied API is valid; that is, check that all keys match defined actions
100          * otherwise returns an array of mistakes.
101          * @return {String[]||true}
102          */
103         isValid : function(api){
104             var invalid = [];
105             var crud = this.actions; // <-- cache a copy of the actions.
106             for (var action in api) {
107                 if (!(action in crud)) {
108                     invalid.push(action);
109                 }
110             }
111             return (!invalid.length) ? true : invalid;
112         },
113
114         <div id="method-Ext.data.Api-hasUniqueUrl"></div>/**
115          * Returns true if the supplied verb upon the supplied proxy points to a unique url in that none of the other api-actions
116          * point to the same url.  The question is important for deciding whether to insert the "xaction" HTTP parameter within an
117          * Ajax request.  This method is used internally and shouldn't generally need to be called directly.
118          * @param {Ext.data.DataProxy} proxy
119          * @param {String} verb
120          * @return {Boolean}
121          */
122         hasUniqueUrl : function(proxy, verb) {
123             var url = (proxy.api[verb]) ? proxy.api[verb].url : null;
124             var unique = true;
125             for (var action in proxy.api) {
126                 if ((unique = (action === verb) ? true : (proxy.api[action].url != url) ? true : false) === false) {
127                     break;
128                 }
129             }
130             return unique;
131         },
132
133         <div id="method-Ext.data.Api-prepare"></div>/**
134          * This method is used internally by <tt>{@link Ext.data.DataProxy DataProxy}</tt> and should not generally need to be used directly.
135          * Each action of a DataProxy api can be initially defined as either a String or an Object.  When specified as an object,
136          * one can explicitly define the HTTP method (GET|POST) to use for each CRUD action.  This method will prepare the supplied API, setting
137          * each action to the Object form.  If your API-actions do not explicitly define the HTTP method, the "method" configuration-parameter will
138          * be used.  If the method configuration parameter is not specified, POST will be used.
139          <pre><code>
140 new Ext.data.HttpProxy({
141     method: "POST",     // <-- default HTTP method when not specified.
142     api: {
143         create: 'create.php',
144         load: 'read.php',
145         save: 'save.php',
146         destroy: 'destroy.php'
147     }
148 });
149
150 // Alternatively, one can use the object-form to specify the API
151 new Ext.data.HttpProxy({
152     api: {
153         load: {url: 'read.php', method: 'GET'},
154         create: 'create.php',
155         destroy: 'destroy.php',
156         save: 'update.php'
157     }
158 });
159         </code></pre>
160          *
161          * @param {Ext.data.DataProxy} proxy
162          */
163         prepare : function(proxy) {
164             if (!proxy.api) {
165                 proxy.api = {}; // <-- No api?  create a blank one.
166             }
167             for (var verb in this.actions) {
168                 var action = this.actions[verb];
169                 proxy.api[action] = proxy.api[action] || proxy.url || proxy.directFn;
170                 if (typeof(proxy.api[action]) == 'string') {
171                     proxy.api[action] = {
172                         url: proxy.api[action]
173                     };
174                 }
175             }
176         },
177
178         <div id="method-Ext.data.Api-restify"></div>/**
179          * Prepares a supplied Proxy to be RESTful.  Sets the HTTP method for each api-action to be one of
180          * GET, POST, PUT, DELETE according to the defined {@link #restActions}.
181          * @param {Ext.data.DataProxy} proxy
182          */
183         restify : function(proxy) {
184             proxy.restful = true;
185             for (var verb in this.restActions) {
186                 proxy.api[this.actions[verb]].method = this.restActions[verb];
187             }
188             // TODO: perhaps move this interceptor elsewhere?  like into DataProxy, perhaps?  Placed here
189             // to satisfy initial 3.0 final release of REST features.
190             proxy.onWrite = proxy.onWrite.createInterceptor(function(action, o, response, rs) {
191                 var reader = o.reader;
192                 var res = {};
193                 switch (response.status) {
194                     case 200:   // standard 200 response, send control back to HttpProxy#onWrite
195                         return true;
196                         break;
197                     case 201:   // entity created but no response returned
198                         res[reader.meta.successProperty] = true;
199                         break;
200                     case 204:  // no-content.  Create a fake response.
201                         res[reader.meta.successProperty] = true;
202                         res[reader.meta.root] = null;
203                         break;
204                     default:
205                         return true;
206                         break;
207                 }
208                 if (res[reader.meta.successProperty] === true) {
209                     this.fireEvent("write", this, action, res[reader.meta.root], res, rs, o.request.arg);
210                 } else {
211                     this.fireEvent('exception', this, 'remote', action, o, res, rs);
212                 }
213                 o.request.callback.call(o.request.scope, res[reader.meta.root], res, res[reader.meta.successProperty]);
214
215                 return false;   // <-- false to prevent intercepted function from running.
216             }, proxy);
217         }
218     };
219 })();
220
221 <div id="cls-Ext.data.Api.Error"></div>/**
222  * @class Ext.data.Api.Error
223  * @extends Ext.Error
224  * Error class for Ext.data.Api errors
225  */
226 Ext.data.Api.Error = Ext.extend(Ext.Error, {
227     constructor : function(message, arg) {
228         this.arg = arg;
229         Ext.Error.call(this, message);
230     },
231     name: 'Ext.data.Api'
232 });
233 Ext.apply(Ext.data.Api.Error.prototype, {
234     lang: {
235         'action-url-undefined': 'No fallback url defined for this action.  When defining a DataProxy api, please be sure to define an url for each CRUD action in Ext.data.Api.actions or define a default url in addition to your api-configuration.',
236         'invalid': 'received an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions defined in Ext.data.Api.actions',
237         'invalid-url': 'Invalid url.  Please review your proxy configuration.',
238         'execute': 'Attempted to execute an unknown action.  Valid API actions are defined in Ext.data.Api.actions"'
239     }
240 });
241 </pre>    \r
242 </body>\r
243 </html>