Docs/Request/Request.JSON.md

   1 Class: Request.JSON {#Request-JSON}
   2 =================================
   3
   4 Wrapped Request with automated receiving of JavaScript Objects in JSON Format.
   5
   6 ### Extends:
   7
   8 [Request](/core/Request/Request)
   9
  10 ### Syntax:
  11
  12         var myJSONRemote = new Request.JSON([options]);
  13
  14 ### Arguments:
  15
  16 1. options - (*object*, optional) See below.
  17
  18 ### Options:
  19
  20 * secure  - (*boolean*: defaults to true) If set to true, a syntax check will be done on the result JSON (see [JSON.decode](/Utilities/JSON#JSON:decode)).
  21
  22 ### Events:
  23
  24 #### success
  25
  26 Fired when the request completes. This overrides the signature of the Request success event.
  27
  28 ##### Signature:
  29
  30         onSuccess(responseJSON, responseText)
  31
  32 ##### Arguments:
  33
  34 1. responseJSON - (*object*) The JSON response object from the remote request.
  35 2. responseText - (*string*) The JSON response as string.
  36
  37 #### error
  38
  39 Fired when the parsed JSON is not valid and the secure option is set.
  40
  41 ##### Signature:
  42
  43         onError(text, error)
  44
  45 ##### Arguments:
  46
  47 1. text - (string) The response text.
  48 2. error - (string) The error message.
  49
  50 #### failure
  51
  52 Fired when the request failed (error status code).
  53
  54 ##### Signature:
  55
  56         onFailure(xhr)
  57
  58 ##### Arguments:
  59
  60 xhr - (XMLHttpRequest) The transport instance.
  61
  62 ### Returns:
  63
  64 * (*object*) A new Request.JSON instance.
  65
  66 ### Example:
  67
  68         // this code will send a data object via a GET request and alert the retrieved data.
  69         var jsonRequest = new Request.JSON({url: 'http://site.com/tellMeAge.php', onSuccess: function(person){
  70                 alert(person.age);    // alerts "25 years".
  71                 alert(person.height); // alerts "170 cm".
  72                 alert(person.weight); // alerts "120 kg".
  73         }}).get({'firstName': 'John', 'lastName': 'Doe'});
  74
  75 ### Cross-Origin Resource Sharing (CORS) note:
  76
  77 The Request.JSON class will (by default) add two custom headers 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:
  78
  79         Access-Control-Allow-Headers: X-Requested-With, X-Request
  80
  81 ### See Also:
  82
  83 [Request](/core/Request/Request)