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