docs/source/Api.html

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