Docs/Request/Request.md

   1 Class: Request {#Request}
   2 =========================
   3
   4 An XMLHttpRequest Wrapper.
   5
   6 ### Implements:
   7
   8 [Chain][], [Class.Thenable][], [Events][], [Options][]
   9
  10 ### Syntax:
  11
  12         var myRequest = new Request([options]);
  13
  14 ### Arguments:
  15
  16 2. options - (*object*, optional) See below.
  17
  18 ### Options:
  19
  20 * url        - (*string*: defaults to *null*) The URL to request. (Note, this can also be an instance of [URI][])
  21 * data       - (*mixed*: defaults to '') The default data for [Request:send][], used when no data is given. Can be an Element, Object or String. If an Object is passed the [Object:toQueryString][] method will be used to convert the object to a string. If an Element is passed the [Element:toQueryString][] method will be used to convert the Element to a string.
  22 * format     - (*string*: defaults to '') If passed, an additional key 'format' will be appended to 'data' with the passed value. e.g. '&format=json'
  23 * link       - (*string*: defaults to 'ignore') Can be 'ignore', 'cancel' and 'chain'.
  24         * 'ignore' - Any calls made to start while the request is running will be ignored. (Synonymous with 'wait': true from 1.11)
  25         * 'cancel' - Any calls made to start while the request is running will take precedence over the currently running request. The new request will start immediately, canceling the one that is currently running. (Synonymous with 'wait': false from 1.11)
  26         * 'chain'  - Any calls made to start while the request is running will be chained up, and will take place as soon as the current request has finished, one after another. [Take care][resetThenable-note] when using "chain" in combination with Request's thenable properties.
  27 * method     - (*string*: defaults to 'post') The HTTP method for the request, can be either 'post' or 'get'.
  28 * emulation  - (*boolean*: defaults to *true*) If set to true, other methods than 'post' or 'get' are appended as post-data named '\_method' (as used in rails)
  29 * async      - (*boolean*: defaults to *true*) If set to false, the requests will be synchronous and freeze the browser during request.
  30 * timeout    - (*integer*: defaults to 0) In conjunction with `onTimeout` event, it determines the amount of milliseconds before considering a connection timed out. (It's suggested to not use timeout with big files and only when knowing what's expected.)
  31 * headers    - (*object*) An object to use in order to set the request headers.
  32 * urlEncoded - (*boolean*: defaults to *true*) If set to true, the content-type header is set to www-form-urlencoded + encoding
  33 * encoding   - (*string*: defaults to 'utf-8') The encoding to be set in the request header.
  34 * noCache    - (*boolean*; defaults to *false*) If *true*, appends a unique *noCache* value to the request to prevent caching. (IE and iOS 6 have a bad habit of caching ajax request values. Including this script and setting the *noCache* value to true will prevent it from caching. The server should ignore the *noCache* value.)
  35 * isSuccess  - (*function*) Overrides the built-in isSuccess function.
  36 * evalScripts  - (*boolean*: defaults to *false*) If set to true, `script` tags inside the response will be evaluated.
  37 * evalResponse - (*boolean*: defaults to *false*) If set to true, the entire response will be evaluated. Responses with javascript content-type will be evaluated automatically.
  38 * user       - (*string*: defaults to *null*) The username to use for http basic authentication.
  39 * password   - (*string*: defaults to *null*) You can use this option together with the `user` option to set authentication credentials when necessary. Note that the password will be passed as plain text and is therefore readable by anyone through the source code. It is therefore encouraged to use this option carefully
  40 * withCredentials   - (*boolean*: defaults to *false*) If set to true, xhr.withCredentials will be set to true allowing cookies/auth to be passed for cross origin requests
  41
  42 ### Thenable:
  43
  44 Request implements `Class.Thenable` to make a Request instance "thenable", i.e. `myRequest.send().then(function(response){ console.log(response.text); });`. See [Class.Thenable][] for more information.
  45
  46 ### Events:
  47
  48 #### request
  49
  50 Fired when the Request is sent.
  51
  52 ##### Signature:
  53
  54         onRequest()
  55
  56 #### loadstart
  57
  58 Fired when the Request loaded, right before any progress starts. (This is limited to Browsers that support the event. At this time: Gecko and WebKit).
  59
  60 ##### Signature:
  61
  62         onLoadstart(event, xhr)
  63
  64 ##### Arguments:
  65
  66 1. event - (Event) The loadstart event.
  67 2. xhr - (XMLHttpRequest) The transport instance.
  68
  69 #### progress
  70
  71 Fired when the Request is making progresses in the download or upload. (This is limited to Browsers that support the event. At this time: Gecko and WebKit).
  72
  73 ##### Signature:
  74
  75         onProgress(event, xhr)
  76
  77 ##### Arguments:
  78
  79 1. event - (Event) The progress event, containing currently downloaded bytes and total bytes.
  80 2. xhr - (XMLHttpRequest) The transport instance.
  81
  82 ### Example:
  83
  84         var myRequest = new Request({
  85                 url: 'image.jpg',
  86                 onProgress: function(event, xhr){
  87                         var loaded = event.loaded, total = event.total;
  88
  89                         console.log(parseInt(loaded / total * 100, 10));
  90                 }
  91         });
  92
  93         myRequest.send();
  94
  95 ### Cross-Origin Resource Sharing (CORS) note:
  96
  97 The Request class will (by default) add a custom header that, if used for a cross-origin request, will have to be reported as allowed in the preflight request, in addition to any other headers you may set yourself:
  98
  99         Access-Control-Allow-Headers: X-Requested-With
 100
 101 ### See Also:
 102
 103  - [MDN: nsIDOMProgressEvent](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIDOMProgressEvent)
 104
 105 #### complete
 106
 107 Fired when the Request is completed.
 108
 109 ##### Signature:
 110
 111         onComplete()
 112
 113 #### cancel
 114
 115 Fired when a request has been cancelled.
 116
 117 ##### Signature:
 118
 119         onCancel()
 120
 121 #### success
 122
 123 Fired when the Request is completed successfully.
 124
 125 ##### Signature:
 126
 127         onSuccess(responseText, responseXML)
 128
 129 ##### Arguments:
 130
 131 1. responseText - (*string*) The returned text from the request.
 132 2. responseXML  - (*mixed*) The response XML from the request.
 133
 134 #### failure
 135
 136 Fired when the request failed (error status code).
 137
 138 ##### Signature:
 139
 140         onFailure(xhr)
 141
 142 ##### Arguments:
 143
 144 xhr - (XMLHttpRequest) The transport instance.
 145
 146 #### exception
 147
 148 Fired when setting a request header fails.
 149
 150 ##### Signature:
 151
 152         onException(headerName, value)
 153
 154 ##### Arguments:
 155
 156 1. headerName - (*string*) The name of the failing header.
 157 2. value      - (*string*) The value of the failing header.
 158
 159 ### Properties:
 160
 161 * response - (*object*) Object with text and XML as keys. You can access this property in the 'success' event.
 162
 163 ### Returns:
 164
 165 * (*object*) A new Request instance.
 166
 167 ### Example:
 168
 169         var myRequest = new Request({method: 'get', url: 'requestHandler.php'});
 170         myRequest.send('name=john&lastname=dorian');
 171
 172 ### See Also:
 173
 174  - [Wikipedia: XMLHttpRequest](http://en.wikipedia.org/wiki/XMLHttpRequest)
 175
 176 #### timeout
 177
 178 Fired when a request doesn't change state for `options.timeout` milliseconds.
 179
 180 ##### Signature:
 181
 182         onTimeout()
 183
 184
 185 ### Example:
 186
 187 This example fetches some text with Request. When the user clicks the link, the returned text by the server is used to update
 188 the element's text. It uses the `onRequest`, `onSuccess` and `onFailure` events to inform the user about the current state of
 189 the request. The `method` option is set to `get` because we get some text instead of posting it to the server. It gets the
 190 data-userid attribute of the clicked link, which will be used for the querystring.
 191
 192         var myElement = document.id('myElement');
 193
 194         var myRequest = new Request({
 195                 url: 'getMyText.php',
 196                 method: 'get',
 197                 onRequest: function(){
 198                         myElement.set('text', 'loading...');
 199                 },
 200                 onSuccess: function(responseText){
 201                         myElement.set('text', responseText);
 202                 },
 203                 onFailure: function(){
 204                         myElement.set('text', 'Sorry, your request failed :(');
 205                 }
 206         });
 207
 208         document.id('myLink').addEvent('click', function(event){
 209                 event.stop();
 210                 myRequest.send('userid=' + this.get('data-userid'));
 211         });
 212
 213
 214
 215 Request Method: setHeader {#Request:setHeader}
 216 --------------------------------------
 217
 218 Add or modify a header for the request. It will not override headers from the options.
 219
 220 ### Syntax:
 221
 222         myRequest.setHeader(name, value);
 223
 224 ### Arguments:
 225
 226 1. name  - (*string*) The name for the header.
 227 2. value - (*string*) The value to be assigned.
 228
 229 ### Returns:
 230
 231 * (*object*) This Request instance.
 232
 233 ### Example:
 234
 235         var myRequest = new Request({url: 'getData.php', method: 'get', headers: {'X-Request': 'JSON'}});
 236         myRequest.setHeader('Last-Modified', 'Sat, 1 Jan 2005 05:00:00 GMT');
 237
 238 Request Method: getHeader {#Request:getHeader}
 239 --------------------------------------
 240
 241 Returns the given response header or null if not found.
 242
 243 ### Syntax:
 244
 245         myRequest.getHeader(name);
 246
 247 ### Arguments:
 248
 249 1. name - (*string*) The name of the header to retrieve the value of.
 250
 251 ### Returns:
 252
 253 * (*string*) The value of the retrieved header.
 254 * (*null*) `null` if the header is not found.
 255
 256 ### Example:
 257
 258         var myRequest = new Request({url: 'getData.php', method: 'get', onSuccess: function(responseText, responseXML){
 259                 alert(this.getHeader('Date')); // alerts the server date (for example, 'Thu, 26 Feb 2009 20:26:06 GMT')
 260         }});
 261
 262 Request Method: send {#Request:send}
 263 ----------------------------
 264
 265 Opens the Request connection and sends the provided data with the specified options.
 266
 267 ### Syntax:
 268
 269         myRequest.send([options]);
 270
 271 ### Arguments:
 272
 273 1. options - (*object*, optional) The options for the sent Request.  Will also accept data as a query string for compatibility reasons.
 274
 275 ### Returns:
 276
 277 * (*object*) This Request instance.
 278
 279 ### Examples:
 280
 281         var myRequest = new Request({
 282                 url: 'http://localhost/some_url'
 283         }).send('save=username&name=John');
 284
 285
 286 Request Methods: send aliases {#Request:send-aliases}
 287 -----------------------------------------------------
 288
 289 MooTools provides several aliases for [Request:send][] to make it easier to use different methods.
 290
 291 These aliases are:
 292
 293 - `post()` and `POST()`
 294 - `get()` and `GET()`
 295 - `put()` and `PUT()`
 296 - `delete()` and `DELETE()`
 297 - `patch()` and `PATCH()`
 298 - `head()` and `HEAD()`
 299
 300 ### Syntax:
 301
 302         myRequest.post([data]);
 303
 304 ### Arguments:
 305
 306 1. data - (*string*, optional) Equivalent with the `data` option of Request.
 307
 308 ### Returns:
 309
 310 * (*object*) This Request instance.
 311
 312 ### Examples:
 313
 314         var myRequest = new Request({url: 'http://localhost/some_url'});
 315
 316         myRequest.post('save=username&name=John');
 317         //...is equivalent to:
 318         myRequest.send({
 319                 method: 'post',
 320                 data: 'save=username&name=John'
 321         });
 322
 323         myRequest.get('save=username&name=John');
 324         //...is equivalent to:
 325         myRequest.send({
 326                 method: 'get',
 327                 data: 'save=username&name=John'
 328         });
 329
 330 ### Note:
 331
 332 By default the emulation option is set to true, so the *put*, *delete* and *patch* send methods are emulated and will actually send as *post* while the method name is sent as e.g. `_method=delete`.
 333
 334 `Async` and `timeout` options are mutually exclusive. If you set `async` to `false`, then there's no need to set the `timeout` since the server and browser will set their own timeouts to return executing the rest of your script.
 335
 336
 337 Request Method: cancel {#Request:cancel}
 338 --------------------------------
 339
 340 Cancels the currently running request, if any.
 341
 342 ### Syntax:
 343
 344         myRequest.cancel();
 345
 346 ### Returns:
 347
 348 * (*object*) This Request instance.
 349
 350 ### Example:
 351
 352         var myRequest = new Request({url: 'mypage.html', method: 'get'}).send('some=data');
 353         myRequest.cancel();
 354
 355 Request Method: isRunning {#Request:isRunning}
 356 --------------------------------
 357
 358 Returns true if the request is currently running
 359
 360 ### Syntax:
 361
 362         myRequest.isRunning()
 363
 364 ### Returns:
 365
 366 * (*boolean*) True if the request is running
 367
 368 ### Example:
 369
 370         var myRequest = new Request({url: 'mypage.html', method: 'get'}).send('some=data');
 371
 372         if (myRequest.isRunning()) // It runs!
 373
 374
 375 Object: Element.Properties {#Element-Properties}
 376 ==============================================
 377
 378 see [Element.Properties][]
 379
 380 Element Property: send {#Element-Properties:send}
 381 -------------------------------------------------
 382
 383 ### Setter
 384
 385 Sets a default Request instance for an Element.  This is useful when handling forms.
 386
 387 #### Syntax:
 388
 389         el.set('send'[, options]);
 390
 391 #### Arguments:
 392
 393 1. options - (*object*) The Request options.
 394
 395 #### Returns:
 396
 397 * (*element*) The original element.
 398
 399 #### Example:
 400
 401         myForm.set('send', {url: 'contact.php', method: 'get'});
 402         myForm.send(); //Sends the form.
 403
 404 ### Getter
 405
 406 Returns the previously set Request instance (or a new one with default options).
 407
 408 #### Syntax:
 409
 410         el.get('send');
 411
 412 #### Arguments:
 413
 414 1. property - (*string*) the Request property argument.
 415
 416 ### Returns:
 417
 418 * (*object*) The Request instance.
 419
 420 #### Example:
 421
 422         el.set('send', {method: 'get'});
 423         el.send();
 424         el.get('send'); // returns the Request instance.
 425
 426 Type: Element {#Element}
 427 ========================
 428
 429 Custom Type to allow all of its methods to be used with any DOM element via the dollar function [$][].
 430
 431
 432 Element Method: send {#Element:send}
 433 ------------------------------------
 434
 435 Sends a form or a container of inputs with an HTML request.
 436
 437 ### Syntax:
 438
 439         myElement.send(url);
 440
 441 ### Arguments:
 442
 443 1. url - (*string*, optional) The url you want to send the form or the "container of inputs" to. If url is omitted, the action of the form will be used. url cannot be omitted for "container of inputs".
 444
 445 ### Returns:
 446
 447 * (element) This Element.
 448
 449 ### Example:
 450
 451 ##### HTML
 452
 453         <form id="myForm" action="submit.php">
 454                 <p>
 455                         <input name="email" value="bob@bob.com" />
 456                         <input name="zipCode" value="90210" />
 457                 </p>
 458         </form>
 459
 460 ##### JavaScript
 461
 462         $('myForm').send();
 463
 464 ### Note:
 465
 466 * The URL is taken from the action attribute of the form.
 467
 468
 469
 470 [$]: /core/Element/Element/#Window:dollar
 471 [Request:send]: #Request:send
 472 [Element.Properties]: /core/Element/Element/#Element-Properties
 473 [URI]: /more/Types/URI
 474 [Chain]: /core/Class/Class.Extras#Chain
 475 [Class.Thenable]: /core/Class/Class.Thenable
 476 [Events]: /core/Class/Class.Extras#Events
 477 [Options]: /core/Class/Class.Extras#Options
 478 [Object:toQueryString]: /core/Types/Object#Object:Object-toQueryString
 479 [Element:toQueryString]: /core/Element/Element#Element:toQueryString
 480 [resetThenable-note]: /core/Class/Class.Thenable#Class.Thenable:resetThenable-note