Request

XMLHTTPRequest with appropriate fallback, response validation and callback.

Functions

Util.request

Definition

Name
Util.request
Shorthand
u.request
Syntax
Void = Util.request( Node node, String url [, JSON _options ] );

Description

Make a server request using XMLHttpRequest with GET, POST, PUT or PATCH or <script> injection in <head>.

Response is validated before being returned to callback function, to make sure response callback always receives something useful.

Makes callback to node.response(response, request_id) when valid response is received. Declare this function on node to receive callback. response parameter will be DOM- or JSON-object, or text-string. DOM-object has response.isHTML variable declared. JSON-object has response.isJSON variable declared, to make testing for response type easier.

Makes callback to node.responseError(response, request_id) if request fails - on security exceptions, page not found, timeout or server error. Declare this function on node to receive callback. If node.responseError is not declared, response error will be returned to node.response.

A request object, containing all request settings, is mapped to node[request_id]. This object will also contain information about exceptions and if timeout occured.

See Util.Form.getParams to know more about retrieving values from a form.

Parameters

node
Node node to attach request to. Response callback will be made to this node.
url
String url to make request to.
_options
JSON Optional - additional request settings.
Options
method
POST, GET, PUT, PATCH, SCRIPT - default GET. SCRIPT causes a script injection in <head> and responder must wrap result in callback function, which is appended to url as callback. Default: GET.
data
Parameters to send. Can be string of parameters or JSON-object with variables. If GET or SCRIPT request, JSON object is automatically converted to string of parameters and appended to url. When using POST, PUT or PATCH a JSON object will be sent as a JSON-string.
async
Send async - default true. Does not apply to SCRIPT injection.
timeout
Add timeout to request - default none. Does not apply to synchronous requests.
headers
JSON object containing additional headers to include in request.
Note: Safari 4 converts all custom header names to Propercase, turning "test" into "Test" and "content-text" into "Content-Text". IE 6-8 lowercases them. This cannot be altered and receiving scripts should be aware of this difference if depending on custom headers.
Headers cannot be used with SCRIPT injection.
credentials
Make the request with credentials, default false
responseType
Set responseType for request, default text
callback
Response callback function name, default: response
error_callback
Response error callback function name, default: responseError
jsonp_callback
Jsonp requests callback function name parameter. Appended to request in case receiving end does not use default callback parameter. Default: callback.

Returns

Void

Callbacks

node.response(response [, request_id])
when response is received
node.responseError(response)
if request fails

Examples

JSON GET Request
var node = u.qs("#content"); node.response = function(response) { var name = response.name; } u.request(node, "/json-url");

Makes GET request to /json and gets the name variable from the received JSON-object.

Post Request with parameters
var node = u.qs("#content"); node.response = function(response) { alert(response); } u.request(node, "/post-url", {"method":"post", "data":"name=martin"});

Makes POST request to /post and alerts the the response string.

Post Request with headers
var node = u.qs("#content"); node.response = function(response) { alert(response); } u.request(node, "/post-url", {"method":"post", "headers":{"Accept":"application/json"});

Makes POST request to /post and sends header Accept=application/json.

GET Request with custom callback
var node = u.qs("#content"); node.customCallback = function(response) { alert(response); } u.request(node, "/get-url", {"callback":"customCallback");

Makes GET request to /get and returns response to node.customCallback.

Make a SCRIPT injection for a JSONP Request
var node = u.qs("#content"); node.response = function(response) { var name = response.name; } u.request(node, "/jsonp-url", {"method":"SCRIPT"});

Makes SCRIPT injection request to /jsonp and gets the name variable from the received JSON-object.

Catching a response error
var node = u.qs("#content"); node.responseError = function(request) { if(response.exception) { alert(response.exception); } else { alert(response.status); } } u.request(node, "http://someotherdomain.com/jsonp", {"method":"POST"});

Makes POST request to other domain (not allowed), and alerts the exception.

Uses

JavaScript
  • XMLHttpRequest/ActiveXObject
  • String.match
  • String.replace
  • String.trim
  • String.substr
  • try ... catch
  • Number
  • Number.toString
  • JSON.parse
  • JSON.stringify
Manipulator
  • Util.querySelector
  • Util.appendElement
  • Util.randomString
  • Util.isStringHTML
  • Util.isStringJSON
  • Util.Timer
  • Util.Events

Files

Main file

  • u-request.js

Segment support files

  • u-request-desktop_light.js

Segment dependencies

desktop_edge
u-request.js + u-dom.js + u-string.js
desktop_ie11
u-request.js + u-dom.js + u-string.js u-events.js
desktop
u-request.js + u-dom.js + u-string.js u-events.js
desktop_ie10
u-request.js + u-dom.js + u-dom-desktop_ie10.js + u-string.js u-events.js
desktop_ie9
u-request.js + u-dom.js + u-dom-desktop_ie10.js + u-string.js u-events.js
desktop_light
u-request.js + u-request-desktop_light.js + u-array-desktop_light.js + u-dom.js + u-dom-desktop_light.js + u-string.js + u-string-desktop_light.js u-events.js
tablet
u-request.js + u-dom.js + u-string.js
tablet_lignt
u-request.js + u-dom.js + u-string.js
smartphone
u-request.js + u-dom.js + u-string.js
mobile
not tested
mobile_light
not tested
tv
u-request.js + u-request-desktop_light.js + u-array-desktop_light.js + u-dom.js + u-dom-desktop_light.js + u-string.js + u-string-desktop_light.js
seo
not supported