docs/source/Rest.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-data-proxy-Rest'>/**
  19 </span> * @author Ed Spencer
  20  * @class Ext.data.proxy.Rest
  21  * @extends Ext.data.proxy.Ajax
  22  *
  23  * &lt;p&gt;RestProxy is a specialization of the {@link Ext.data.proxy.Ajax AjaxProxy} which simply maps the four actions
  24  * (create, read, update and destroy) to RESTful HTTP verbs. For example, let's set up a {@link Ext.data.Model Model}
  25  * with an inline RestProxy&lt;/p&gt;
  26  *
  27 &lt;pre&gt;&lt;code&gt;
  28 Ext.define('User', {
  29     extend: 'Ext.data.Model',
  30     fields: ['id', 'name', 'email'],
  31
  32     proxy: {
  33         type: 'rest',
  34         url : '/users'
  35     }
  36 });
  37 &lt;/code&gt;&lt;/pre&gt;
  38  *
  39  * &lt;p&gt;Now we can create a new User instance and save it via the RestProxy. Doing this will cause the Proxy to send a
  40  * POST request to '/users':
  41  *
  42 &lt;pre&gt;&lt;code&gt;
  43 var user = Ext.ModelManager.create({name: 'Ed Spencer', email: 'ed@sencha.com'}, 'User');
  44
  45 user.save(); //POST /users
  46 &lt;/code&gt;&lt;/pre&gt;
  47  *
  48  * &lt;p&gt;Let's expand this a little and provide a callback for the {@link Ext.data.Model#save} call to update the Model
  49  * once it has been created. We'll assume the creation went successfully and that the server gave this user an ID of
  50  * 123:&lt;/p&gt;
  51  *
  52 &lt;pre&gt;&lt;code&gt;
  53 user.save({
  54     success: function(user) {
  55         user.set('name', 'Khan Noonien Singh');
  56
  57         user.save(); //PUT /users/123
  58     }
  59 });
  60 &lt;/code&gt;&lt;/pre&gt;
  61  *
  62  * &lt;p&gt;Now that we're no longer creating a new Model instance, the request method is changed to an HTTP PUT, targeting
  63  * the relevant url for that user. Now let's delete this user, which will use the DELETE method:&lt;/p&gt;
  64  *
  65 &lt;pre&gt;&lt;code&gt;
  66     user.destroy(); //DELETE /users/123
  67 &lt;/code&gt;&lt;/pre&gt;
  68  *
  69  * &lt;p&gt;Finally, when we perform a load of a Model or Store, RestProxy will use the GET method:&lt;/p&gt;
  70  *
  71 &lt;pre&gt;&lt;code&gt;
  72 //1. Load via Store
  73
  74 //the Store automatically picks up the Proxy from the User model
  75 var store = new Ext.data.Store({
  76     model: 'User'
  77 });
  78
  79 store.load(); //GET /users
  80
  81 //2. Load directly from the Model
  82
  83 //GET /users/123
  84 Ext.ModelManager.getModel('User').load(123, {
  85     success: function(user) {
  86         console.log(user.getId()); //outputs 123
  87     }
  88 });
  89 &lt;/code&gt;&lt;/pre&gt;
  90  *
  91  * &lt;p&gt;&lt;u&gt;Url generation&lt;/u&gt;&lt;/p&gt;
  92  *
  93  * &lt;p&gt;RestProxy is able to automatically generate the urls above based on two configuration options - {@link #appendId}
  94  * and {@link #format}. If appendId is true (it is by default) then RestProxy will automatically append the ID of the
  95  * Model instance in question to the configured url, resulting in the '/users/123' that we saw above.&lt;/p&gt;
  96  *
  97  * &lt;p&gt;If the request is not for a specific Model instance (e.g. loading a Store), the url is not appended with an id.
  98  * RestProxy will automatically insert a '/' before the ID if one is not already present.&lt;/p&gt;
  99  *
 100 &lt;pre&gt;&lt;code&gt;
 101 new Ext.data.proxy.Rest({
 102     url: '/users',
 103     appendId: true //default
 104 });
 105
 106 // Collection url: /users
 107 // Instance url  : /users/123
 108 &lt;/code&gt;&lt;/pre&gt;
 109  *
 110  * &lt;p&gt;RestProxy can also optionally append a format string to the end of any generated url:&lt;/p&gt;
 111  *
 112 &lt;pre&gt;&lt;code&gt;
 113 new Ext.data.proxy.Rest({
 114     url: '/users',
 115     format: 'json'
 116 });
 117
 118 // Collection url: /users.json
 119 // Instance url  : /users/123.json
 120 &lt;/code&gt;&lt;/pre&gt;
 121  *
 122  * &lt;p&gt;If further customization is needed, simply implement the {@link #buildUrl} method and add your custom generated
 123  * url onto the {@link Ext.data.Request Request} object that is passed to buildUrl. See
 124  * &lt;a href=&quot;source/RestProxy.html#method-Ext.data.proxy.Rest-buildUrl&quot;&gt;RestProxy's implementation&lt;/a&gt; for an example of
 125  * how to achieve this.&lt;/p&gt;
 126  *
 127  * &lt;p&gt;Note that RestProxy inherits from {@link Ext.data.proxy.Ajax AjaxProxy}, which already injects all of the sorter,
 128  * filter, group and paging options into the generated url. See the {@link Ext.data.proxy.Ajax AjaxProxy docs} for more
 129  * details.&lt;/p&gt;
 130  */
 131 Ext.define('Ext.data.proxy.Rest', {
 132     extend: 'Ext.data.proxy.Ajax',
 133     alternateClassName: 'Ext.data.RestProxy',
 134     alias : 'proxy.rest',
 135
 136 <span id='Ext-data-proxy-Rest-cfg-appendId'>    /**
 137 </span>     * @cfg {Boolean} appendId True to automatically append the ID of a Model instance when performing a request based
 138      * on that single instance. See RestProxy intro docs for more details. Defaults to true.
 139      */
 140     appendId: true,
 141
 142 <span id='Ext-data-proxy-Rest-cfg-format'>    /**
 143 </span>     * @cfg {String} format Optional data format to send to the server when making any request (e.g. 'json'). See the
 144      * RestProxy intro docs for full details. Defaults to undefined.
 145      */
 146
 147 <span id='Ext-data-proxy-Rest-cfg-batchActions'>    /**
 148 </span>     * @cfg {Boolean} batchActions True to batch actions of a particular type when synchronizing the store.
 149      * Defaults to &lt;tt&gt;false&lt;/tt&gt;.
 150      */
 151     batchActions: false,
 152
 153 <span id='Ext-data-proxy-Rest-method-buildUrl'>    /**
 154 </span>     * Specialized version of buildUrl that incorporates the {@link #appendId} and {@link #format} options into the
 155      * generated url. Override this to provide further customizations, but remember to call the superclass buildUrl
 156      * so that additional parameters like the cache buster string are appended
 157      */
 158     buildUrl: function(request) {
 159         var me        = this,
 160             operation = request.operation,
 161             records   = operation.records || [],
 162             record    = records[0],
 163             format    = me.format,
 164             url       = me.getUrl(request),
 165             id        = record ? record.getId() : operation.id;
 166
 167         if (me.appendId &amp;&amp; id) {
 168             if (!url.match(/\/$/)) {
 169                 url += '/';
 170             }
 171
 172             url += id;
 173         }
 174
 175         if (format) {
 176             if (!url.match(/\.$/)) {
 177                 url += '.';
 178             }
 179
 180             url += format;
 181         }
 182
 183         request.url = url;
 184
 185         return me.callParent(arguments);
 186     }
 187 }, function() {
 188     Ext.apply(this.prototype, {
 189 <span id='Ext-data-proxy-Rest-property-actionMethods'>        /**
 190 </span>         * Mapping of action name to HTTP request method. These default to RESTful conventions for the 'create', 'read',
 191          * 'update' and 'destroy' actions (which map to 'POST', 'GET', 'PUT' and 'DELETE' respectively). This object should
 192          * not be changed except globally via {@link Ext#override Ext.override} - the {@link #getMethod} function can be overridden instead.
 193          * @property actionMethods
 194          * @type Object
 195          */
 196         actionMethods: {
 197             create : 'POST',
 198             read   : 'GET',
 199             update : 'PUT',
 200             destroy: 'DELETE'
 201         }
 202     });
 203 });
 204 </pre>
 205 </body>
 206 </html>