Request

XMLHTTPRequest with appropriate fallback, response validation and callback.

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 occurred.

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 cadependencies 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.

Return values

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.

Dependencies

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

Main file

u-request.js

Segment support files

u-request-desktop_light.js

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_ie.js + u-string.js u-events.js
desktop_ie9: u-request.js + u-dom.js + u-dom-desktop_ie.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