docs/source/Ajax2.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="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/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-Ajax-method-constructor'><span id='Ext-data-proxy-Ajax'>/**
  19 </span></span> * @author Ed Spencer
  20  *
  21  * AjaxProxy is one of the most widely-used ways of getting data into your application. It uses AJAX requests to load
  22  * data from the server, usually to be placed into a {@link Ext.data.Store Store}. Let's take a look at a typical setup.
  23  * Here we're going to set up a Store that has an AjaxProxy. To prepare, we'll also set up a {@link Ext.data.Model
  24  * Model}:
  25  *
  26  *     Ext.define('User', {
  27  *         extend: 'Ext.data.Model',
  28  *         fields: ['id', 'name', 'email']
  29  *     });
  30  *
  31  *     //The Store contains the AjaxProxy as an inline configuration
  32  *     var store = Ext.create('Ext.data.Store', {
  33  *         model: 'User',
  34  *         proxy: {
  35  *             type: 'ajax',
  36  *             url : 'users.json'
  37  *         }
  38  *     });
  39  *
  40  *     store.load();
  41  *
  42  * Our example is going to load user data into a Store, so we start off by defining a {@link Ext.data.Model Model} with
  43  * the fields that we expect the server to return. Next we set up the Store itself, along with a
  44  * {@link Ext.data.Store#proxy proxy} configuration. This configuration was automatically turned into an
  45  * Ext.data.proxy.Ajax instance, with the url we specified being passed into AjaxProxy's constructor.
  46  * It's as if we'd done this:
  47  *
  48  *     new Ext.data.proxy.Ajax({
  49  *         url: 'users.json',
  50  *         model: 'User',
  51  *         reader: 'json'
  52  *     });
  53  *
  54  * A couple of extra configurations appeared here - {@link #model} and {@link #reader}. These are set by default when we
  55  * create the proxy via the Store - the Store already knows about the Model, and Proxy's default {@link
  56  * Ext.data.reader.Reader Reader} is {@link Ext.data.reader.Json JsonReader}.
  57  *
  58  * Now when we call store.load(), the AjaxProxy springs into action, making a request to the url we configured
  59  * ('users.json' in this case). As we're performing a read, it sends a GET request to that url (see
  60  * {@link #actionMethods} to customize this - by default any kind of read will be sent as a GET request and any kind of write
  61  * will be sent as a POST request).
  62  *
  63  * # Limitations
  64  *
  65  * AjaxProxy cannot be used to retrieve data from other domains. If your application is running on http://domainA.com it
  66  * cannot load data from http://domainB.com because browsers have a built-in security policy that prohibits domains
  67  * talking to each other via AJAX.
  68  *
  69  * If you need to read data from another domain and can't set up a proxy server (some software that runs on your own
  70  * domain's web server and transparently forwards requests to http://domainB.com, making it look like they actually came
  71  * from http://domainA.com), you can use {@link Ext.data.proxy.JsonP} and a technique known as JSON-P (JSON with
  72  * Padding), which can help you get around the problem so long as the server on http://domainB.com is set up to support
  73  * JSON-P responses. See {@link Ext.data.proxy.JsonP JsonPProxy}'s introduction docs for more details.
  74  *
  75  * # Readers and Writers
  76  *
  77  * AjaxProxy can be configured to use any type of {@link Ext.data.reader.Reader Reader} to decode the server's response.
  78  * If no Reader is supplied, AjaxProxy will default to using a {@link Ext.data.reader.Json JsonReader}. Reader
  79  * configuration can be passed in as a simple object, which the Proxy automatically turns into a {@link
  80  * Ext.data.reader.Reader Reader} instance:
  81  *
  82  *     var proxy = new Ext.data.proxy.Ajax({
  83  *         model: 'User',
  84  *         reader: {
  85  *             type: 'xml',
  86  *             root: 'users'
  87  *         }
  88  *     });
  89  *
  90  *     proxy.getReader(); //returns an {@link Ext.data.reader.Xml XmlReader} instance based on the config we supplied
  91  *
  92  * # Url generation
  93  *
  94  * AjaxProxy automatically inserts any sorting, filtering, paging and grouping options into the url it generates for
  95  * each request. These are controlled with the following configuration options:
  96  *
  97  * - {@link #pageParam} - controls how the page number is sent to the server (see also {@link #startParam} and {@link #limitParam})
  98  * - {@link #sortParam} - controls how sort information is sent to the server
  99  * - {@link #groupParam} - controls how grouping information is sent to the server
 100  * - {@link #filterParam} - controls how filter information is sent to the server
 101  *
 102  * Each request sent by AjaxProxy is described by an {@link Ext.data.Operation Operation}. To see how we can customize
 103  * the generated urls, let's say we're loading the Proxy with the following Operation:
 104  *
 105  *     var operation = new Ext.data.Operation({
 106  *         action: 'read',
 107  *         page  : 2
 108  *     });
 109  *
 110  * Now we'll issue the request for this Operation by calling {@link #read}:
 111  *
 112  *     var proxy = new Ext.data.proxy.Ajax({
 113  *         url: '/users'
 114  *     });
 115  *
 116  *     proxy.read(operation); //GET /users?page=2
 117  *
 118  * Easy enough - the Proxy just copied the page property from the Operation. We can customize how this page data is sent
 119  * to the server:
 120  *
 121  *     var proxy = new Ext.data.proxy.Ajax({
 122  *         url: '/users',
 123  *         pagePage: 'pageNumber'
 124  *     });
 125  *
 126  *     proxy.read(operation); //GET /users?pageNumber=2
 127  *
 128  * Alternatively, our Operation could have been configured to send start and limit parameters instead of page:
 129  *
 130  *     var operation = new Ext.data.Operation({
 131  *         action: 'read',
 132  *         start : 50,
 133  *         limit : 25
 134  *     });
 135  *
 136  *     var proxy = new Ext.data.proxy.Ajax({
 137  *         url: '/users'
 138  *     });
 139  *
 140  *     proxy.read(operation); //GET /users?start=50&amp;limit;=25
 141  *
 142  * Again we can customize this url:
 143  *
 144  *     var proxy = new Ext.data.proxy.Ajax({
 145  *         url: '/users',
 146  *         startParam: 'startIndex',
 147  *         limitParam: 'limitIndex'
 148  *     });
 149  *
 150  *     proxy.read(operation); //GET /users?startIndex=50&amp;limitIndex;=25
 151  *
 152  * AjaxProxy will also send sort and filter information to the server. Let's take a look at how this looks with a more
 153  * expressive Operation object:
 154  *
 155  *     var operation = new Ext.data.Operation({
 156  *         action: 'read',
 157  *         sorters: [
 158  *             new Ext.util.Sorter({
 159  *                 property : 'name',
 160  *                 direction: 'ASC'
 161  *             }),
 162  *             new Ext.util.Sorter({
 163  *                 property : 'age',
 164  *                 direction: 'DESC'
 165  *             })
 166  *         ],
 167  *         filters: [
 168  *             new Ext.util.Filter({
 169  *                 property: 'eyeColor',
 170  *                 value   : 'brown'
 171  *             })
 172  *         ]
 173  *     });
 174  *
 175  * This is the type of object that is generated internally when loading a {@link Ext.data.Store Store} with sorters and
 176  * filters defined. By default the AjaxProxy will JSON encode the sorters and filters, resulting in something like this
 177  * (note that the url is escaped before sending the request, but is left unescaped here for clarity):
 178  *
 179  *     var proxy = new Ext.data.proxy.Ajax({
 180  *         url: '/users'
 181  *     });
 182  *
 183  *     proxy.read(operation); //GET /users?sort=[{&quot;property&quot;:&quot;name&quot;,&quot;direction&quot;:&quot;ASC&quot;},{&quot;property&quot;:&quot;age&quot;,&quot;direction&quot;:&quot;DESC&quot;}]&amp;filter;=[{&quot;property&quot;:&quot;eyeColor&quot;,&quot;value&quot;:&quot;brown&quot;}]
 184  *
 185  * We can again customize how this is created by supplying a few configuration options. Let's say our server is set up
 186  * to receive sorting information is a format like &quot;sortBy=name#ASC,age#DESC&quot;. We can configure AjaxProxy to provide
 187  * that format like this:
 188  *
 189  *      var proxy = new Ext.data.proxy.Ajax({
 190  *          url: '/users',
 191  *          sortParam: 'sortBy',
 192  *          filterParam: 'filterBy',
 193  *
 194  *          //our custom implementation of sorter encoding - turns our sorters into &quot;name#ASC,age#DESC&quot;
 195  *          encodeSorters: function(sorters) {
 196  *              var length   = sorters.length,
 197  *                  sortStrs = [],
 198  *                  sorter, i;
 199  *
 200  *              for (i = 0; i &lt; length; i++) {
 201  *                  sorter = sorters[i];
 202  *
 203  *                  sortStrs[i] = sorter.property + '#' + sorter.direction
 204  *              }
 205  *
 206  *              return sortStrs.join(&quot;,&quot;);
 207  *          }
 208  *      });
 209  *
 210  *      proxy.read(operation); //GET /users?sortBy=name#ASC,age#DESC&amp;filterBy;=[{&quot;property&quot;:&quot;eyeColor&quot;,&quot;value&quot;:&quot;brown&quot;}]
 211  *
 212  * We can also provide a custom {@link #encodeFilters} function to encode our filters.
 213  *
 214  * @constructor
 215  * Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the Store's call to
 216  * {@link Ext.data.Store#load load} will override any specified callback and params options. In this case, use the
 217  * {@link Ext.data.Store Store}'s events to modify parameters, or react to loading events.
 218  *
 219  * @param {Object} config (optional) Config object.
 220  * If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make the request.
 221  */
 222 Ext.define('Ext.data.proxy.Ajax', {
 223     requires: ['Ext.util.MixedCollection', 'Ext.Ajax'],
 224     extend: 'Ext.data.proxy.Server',
 225     alias: 'proxy.ajax',
 226     alternateClassName: ['Ext.data.HttpProxy', 'Ext.data.AjaxProxy'],
 227
 228 <span id='Ext-data-proxy-Ajax-property-actionMethods'>    /**
 229 </span>     * @property {Object} actionMethods
 230      * Mapping of action name to HTTP request method. In the basic AjaxProxy these are set to 'GET' for 'read' actions
 231      * and 'POST' for 'create', 'update' and 'destroy' actions. The {@link Ext.data.proxy.Rest} maps these to the
 232      * correct RESTful methods.
 233      */
 234     actionMethods: {
 235         create : 'POST',
 236         read   : 'GET',
 237         update : 'POST',
 238         destroy: 'POST'
 239     },
 240
 241 <span id='Ext-data-proxy-Ajax-cfg-headers'>    /**
 242 </span>     * @cfg {Object} headers
 243      * Any headers to add to the Ajax request. Defaults to undefined.
 244      */
 245
 246 <span id='Ext-data-proxy-Ajax-method-doRequest'>    /**
 247 </span>     * @ignore
 248      */
 249     doRequest: function(operation, callback, scope) {
 250         var writer  = this.getWriter(),
 251             request = this.buildRequest(operation, callback, scope);
 252
 253         if (operation.allowWrite()) {
 254             request = writer.write(request);
 255         }
 256
 257         Ext.apply(request, {
 258             headers       : this.headers,
 259             timeout       : this.timeout,
 260             scope         : this,
 261             callback      : this.createRequestCallback(request, operation, callback, scope),
 262             method        : this.getMethod(request),
 263             disableCaching: false // explicitly set it to false, ServerProxy handles caching
 264         });
 265
 266         Ext.Ajax.request(request);
 267
 268         return request;
 269     },
 270
 271 <span id='Ext-data-proxy-Ajax-method-getMethod'>    /**
 272 </span>     * Returns the HTTP method name for a given request. By default this returns based on a lookup on
 273      * {@link #actionMethods}.
 274      * @param {Ext.data.Request} request The request object
 275      * @return {String} The HTTP method to use (should be one of 'GET', 'POST', 'PUT' or 'DELETE')
 276      */
 277     getMethod: function(request) {
 278         return this.actionMethods[request.action];
 279     },
 280
 281 <span id='Ext-data-proxy-Ajax-method-createRequestCallback'>    /**
 282 </span>     * @private
 283      * TODO: This is currently identical to the JsonPProxy version except for the return function's signature. There is a lot
 284      * of code duplication inside the returned function so we need to find a way to DRY this up.
 285      * @param {Ext.data.Request} request The Request object
 286      * @param {Ext.data.Operation} operation The Operation being executed
 287      * @param {Function} callback The callback function to be called when the request completes. This is usually the callback
 288      * passed to doRequest
 289      * @param {Object} scope The scope in which to execute the callback function
 290      * @return {Function} The callback function
 291      */
 292     createRequestCallback: function(request, operation, callback, scope) {
 293         var me = this;
 294
 295         return function(options, success, response) {
 296             me.processResponse(success, operation, request, response, callback, scope);
 297         };
 298     }
 299 }, function() {
 300     //backwards compatibility, remove in Ext JS 5.0
 301     Ext.data.HttpProxy = this;
 302 });
 303 </pre>
 304 </body>
 305 </html>