Docs/Request/Request.HTML.md

   1 Class: Request.HTML {#Request-HTML}
   2 ===================================
   3
   4 Request Specifically made for receiving HTML.
   5
   6 ### Extends:
   7
   8 [Request][]
   9
  10 ### Syntax:
  11
  12         var myHTMLRequest = new Request.HTML([options]);
  13
  14 ### Arguments:
  15
  16 1. options - (*object*, optional) See options below.  Also inherited are all the options from [Request][].
  17
  18 ### Options:
  19
  20 * evalScripts  - (*boolean*: defaults to true) If set to true, `script` tags inside the response will be evaluated. This overrides the `false` default from Request.
  21 * update - (*element*: defaults to null) The Element to insert the response text of the Request into upon completion of the request.
  22 * append - (*element*: defaults to null) The Element to append the response text of the Request into upon completion of the request.
  23 * filter - (*mixed*: defaults to null) To filter the response tree by a selector or function. See [Elements:filter][]
  24
  25 ### Events:
  26
  27 #### success
  28
  29 * (*function*) Function to execute when the HTML request completes. This overrides the signature of the Request success event.
  30
  31 ##### Signature:
  32
  33         onSuccess(responseTree, responseElements, responseHTML, responseJavaScript)
  34
  35 ##### Arguments:
  36
  37 1. responseTree           - (*element*) The node list of the remote response.
  38 2. responseElements   - (*array*)   An array containing all elements of the remote response.
  39 3. responseHTML           - (*string*)  The content of the remote response.
  40 4. responseJavaScript - (*string*)  The portion of JavaScript from the remote response.
  41
  42 ### Returns:
  43
  44 * (*object*) A new Request.HTML instance.
  45
  46 ### Examples:
  47
  48 #### Simple GET Request:
  49
  50         var myHTMLRequest = new Request.HTML().get('myPage.html');
  51
  52 #### POST Request with data as String:
  53
  54         var myHTMLRequest = new Request.HTML({url: 'myPage.html'}).post('user_id=25&save=true');
  55
  56 #### Data from Object Passed via GET:
  57
  58         //Loads "load/?user_id=25".
  59         var myHTMLRequest = new Request.HTML({url: 'load/'}).get({'user_id': 25});
  60
  61 #### Data from Element via POST:
  62
  63 ##### HTML
  64
  65         <form action="save/" method="post" id="user-form">
  66                 <p>
  67                         Search: <input type="text" name="search" />
  68                         Search in description: <input type="checkbox" name="search_description" value="yes" />
  69                         <input type="submit" />
  70                 </p>
  71         </form>
  72
  73 ##### JavaScript
  74
  75         //Needs to be in a submit event or the form handler.
  76         var myHTMLRequest = new Request.HTML({url: 'save/'}).post($('user-form'));
  77
  78 ### See Also:
  79
  80 [Request][]
  81
  82
  83 Object: Element.Properties {#Element-Properties}
  84 ==============================================
  85
  86 see [Element.Properties][]
  87
  88 Element Property: load {#Element-Properties:load}
  89 -------------------------------------------------
  90
  91 ### Setter
  92
  93 Sets a default Request.HTML instance for an Element.
  94
  95 #### Syntax:
  96
  97         el.set('load'[, options]);
  98
  99 #### Arguments:
 100
 101 1. options - (*object*) The Request options.
 102
 103 #### Returns:
 104
 105 * (*element*) The target Element.
 106
 107 #### Example:
 108
 109         el.set('load', {evalScripts: true});
 110         el.load('some/request/uri');
 111
 112
 113 ### Getter
 114
 115 Returns either the previously set Request.HTML instance or a new one with default options.
 116
 117 #### Syntax:
 118
 119         el.get('load');
 120
 121 #### Arguments:
 122
 123 1. property - (*string*) the Request.HTML property argument.
 124
 125 #### Returns:
 126
 127 * (*object*) The Request instance.
 128
 129 #### Example:
 130
 131         el.set('load', {method: 'get'});
 132         el.load('test.html');
 133         // the getter returns the Request.HTML instance, making its class methods available.
 134         el.get('load').post('http://localhost/script');
 135
 136
 137
 138 Type: Element {#Element}
 139 ========================
 140
 141 Custom Type to allow all of its methods to be used with any DOM element via the dollar function [$][].
 142
 143 Element Method: load {#Element:load}
 144 ------------------------------------
 145
 146 Updates the content of the Element with a Request.HTML GET request.
 147
 148 ### Syntax:
 149
 150         myElement.load(url);
 151
 152 ### Arguments:
 153
 154 1. url - (*string*) The URL pointing to the server-side document.
 155
 156 ### Returns:
 157
 158 * (*element*) The target Element.
 159
 160 ### Example:
 161
 162 ##### HTML
 163
 164         <div id="content">Loading content...</div>
 165
 166 ##### JavaScript
 167
 168         $('content').load('page_1.html');
 169
 170 ### Cross-Origin Resource Sharing (CORS) note:
 171
 172 The Request.HTML 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:
 173
 174         Access-Control-Allow-Headers: X-Requested-With
 175
 176 ### See Also:
 177
 178 - [$][], [Request](/core/Request/Request)
 179
 180 [Request]: /core/Request/Request
 181 [$]: /core/Element/Element/#Window:dollar
 182 [Element.Properties]: /core/Element/Element/#Element-Properties
 183 [Elements:filter]: /core/Element/Element#Elements:filter