docs/source/Api.html

   1 <html>
   2 <head>
   3   <title>The source code</title>
   4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   6 </head>
   7 <body  onload="prettyPrint();">
   8     <pre class="prettyprint lang-js">/*!
   9  * Ext JS Library 3.0.3
  10  * Copyright(c) 2006-2009 Ext JS, LLC
  11  * licensing@extjs.com
  12  * http://www.extjs.com/license
  13  */
  14
  15 <div id="cls-Ext.data.Api"></div>/**
  16  * @class Ext.data.Api
  17  * @extends Object
  18  * Ext.data.Api is a singleton designed to manage the data API including methods
  19  * for validating a developer's DataProxy API.  Defines variables for CRUD actions
  20  * create, read, update and destroy in addition to a mapping of RESTful HTTP methods
  21  * GET, POST, PUT and DELETE to CRUD actions.
  22  * @singleton
  23  */
  24 Ext.data.Api = (function() {
  25
  26     // private validActions.  validActions is essentially an inverted hash of Ext.data.Api.actions, where value becomes the key.
  27     // Some methods in this singleton (e.g.: getActions, getVerb) will loop through actions with the code <code>for (var verb in this.actions)</code>
  28     // For efficiency, some methods will first check this hash for a match.  Those methods which do acces validActions will cache their result here.
  29     // We cannot pre-define this hash since the developer may over-ride the actions at runtime.
  30     var validActions = {};
  31
  32     return {
  33         <div id="prop-Ext.data.Api-actions"></div>/**
  34          * Defined actions corresponding to remote actions:
  35          * <pre><code>
  36 actions: {
  37     create  : 'create',  // Text representing the remote-action to create records on server.
  38     read    : 'read',    // Text representing the remote-action to read/load data from server.
  39     update  : 'update',  // Text representing the remote-action to update records on server.
  40     destroy : 'destroy'  // Text representing the remote-action to destroy records on server.
  41 }
  42          * </code></pre>
  43          * @property actions
  44          * @type Object
  45          */
  46         actions : {
  47             create  : 'create',
  48             read    : 'read',
  49             update  : 'update',
  50             destroy : 'destroy'
  51         },
  52
  53         <div id="prop-Ext.data.Api-restActions"></div>/**
  54          * Defined {CRUD action}:{HTTP method} pairs to associate HTTP methods with the
  55          * corresponding actions for {@link Ext.data.DataProxy#restful RESTful proxies}.
  56          * Defaults to:
  57          * <pre><code>
  58 restActions : {
  59     create  : 'POST',
  60     read    : 'GET',
  61     update  : 'PUT',
  62     destroy : 'DELETE'
  63 },
  64          * </code></pre>
  65          */
  66         restActions : {
  67             create  : 'POST',
  68             read    : 'GET',
  69             update  : 'PUT',
  70             destroy : 'DELETE'
  71         },
  72
  73         <div id="method-Ext.data.Api-isAction"></div>/**
  74          * Returns true if supplied action-name is a valid API action defined in <code>{@link #actions}</code> constants
  75          * @param {String} action
  76          * @param {String[]}(Optional) List of available CRUD actions.  Pass in list when executing multiple times for efficiency.
  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                     };
 181                 }
 182             }
 183         },
 184
 185         <div id="method-Ext.data.Api-restify"></div>/**
 186          * Prepares a supplied Proxy to be RESTful.  Sets the HTTP method for each api-action to be one of
 187          * GET, POST, PUT, DELETE according to the defined {@link #restActions}.
 188          * @param {Ext.data.DataProxy} proxy
 189          */
 190         restify : function(proxy) {
 191             proxy.restful = true;
 192             for (var verb in this.restActions) {
 193                 proxy.api[this.actions[verb]].method = this.restActions[verb];
 194             }
 195             // TODO: perhaps move this interceptor elsewhere?  like into DataProxy, perhaps?  Placed here
 196             // to satisfy initial 3.0 final release of REST features.
 197             proxy.onWrite = proxy.onWrite.createInterceptor(function(action, o, response, rs) {
 198                 var reader = o.reader;
 199                 var res = new Ext.data.Response({
 200                     action: action,
 201                     raw: response
 202                 });
 203
 204                 switch (response.status) {
 205                     case 200:   // standard 200 response, send control back to HttpProxy#onWrite
 206                         return true;
 207                         break;
 208                     case 201:   // entity created but no response returned
 209                         //res[reader.meta.successProperty] = true;
 210                         res.success = true;
 211                         break;
 212                     case 204:  // no-content.  Create a fake response.
 213                         //res[reader.meta.successProperty] = true;
 214                         //res[reader.meta.root] = null;
 215                         res.success = true;
 216                         res.data = null;
 217                         break;
 218                     default:
 219                         return true;
 220                         break;
 221                 }
 222                 /*
 223                 if (res[reader.meta.successProperty] === true) {
 224                     this.fireEvent("write", this, action, res[reader.meta.root], res, rs, o.request.arg);
 225                 } else {
 226                     this.fireEvent('exception', this, 'remote', action, o, res, rs);
 227                 }
 228                 */
 229                 if (res.success === true) {
 230                     this.fireEvent("write", this, action, res.data, res, rs, o.request.arg);
 231                 } else {
 232                     this.fireEvent('exception', this, 'remote', action, o, res, rs);
 233                 }
 234                 o.request.callback.call(o.request.scope, res.data, res, res.success);
 235
 236                 return false;   // <-- false to prevent intercepted function from running.
 237             }, proxy);
 238         }
 239     };
 240 })();
 241
 242 <div id="method-Ext.data.Api-Response"></div>/**
 243  * Ext.data.Response
 244  * Experimental.  Do not use directly.
 245  */
 246 Ext.data.Response = function(params, response) {
 247     Ext.apply(this, params, {
 248         raw: response
 249     });
 250 };
 251 Ext.data.Response.prototype = {
 252     message : null,
 253     success : false,
 254     status : null,
 255     root : null,
 256     raw : null,
 257
 258     getMessage : function() {
 259         return this.message;
 260     },
 261     getSuccess : function() {
 262         return this.success;
 263     },
 264     getStatus : function() {
 265         return this.status
 266     },
 267     getRoot : function() {
 268         return this.root;
 269     },
 270     getRawResponse : function() {
 271         return this.raw;
 272     }
 273 };
 274
 275 <div id="cls-Ext.data.Api.Error"></div>/**
 276  * @class Ext.data.Api.Error
 277  * @extends Ext.Error
 278  * Error class for Ext.data.Api errors
 279  */
 280 Ext.data.Api.Error = Ext.extend(Ext.Error, {
 281     constructor : function(message, arg) {
 282         this.arg = arg;
 283         Ext.Error.call(this, message);
 284     },
 285     name: 'Ext.data.Api'
 286 });
 287 Ext.apply(Ext.data.Api.Error.prototype, {
 288     lang: {
 289         '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.',
 290         'invalid': 'received an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions defined in Ext.data.Api.actions',
 291         'invalid-url': 'Invalid url.  Please review your proxy configuration.',
 292         'execute': 'Attempted to execute an unknown action.  Valid API actions are defined in Ext.data.Api.actions"'
 293     }
 294 });
 295
 296
 297 </pre>
 298 </body>
 299 </html>