Introduction to XMLHttpRequest Level 2

FormData

FormData

Introduction

XMLHttpRequest

XMLHttpRequest

document.domain

iframe

What's new in XMLHttpRequest

FormData

Setting and handling timeouts

timeout

function makeRequest() {
var url = 'data.json';
var onLoadHandler = function(event){
// Parse the JSON and build a list.
}
var onTimeOutHandler = function(event){
var content = document.getElementById('content'),
p = document.createElement('p'),
msg = document.createTextNode('Just a little bit longer!');
p.appendChild(msg);
content.appendChild(p);

// Restarts the request.
event.target.open('GET',url);

// Optionally, set a longer timeout to override the original.
event.target.timeout = 6000;
event.target.send();
}
var xhr = new XMLHttpRequest();
xhr.open('GET',url);
xhr.timeout = 3000;
xhr.onload = onLoadHandler;
xhr.ontimeout = onTimeOutHandler;
xhr.send();
}

window.addEventListener('DOMContentLoaded', makeRequest, false);

timeout

XDomainRequest

Requesting data from another domain

XMLHttpRequest

XDomainRequest

var xhr = new XMLHttpRequest();
var onLoadHandler = function(event) {
/* do something with the response */
}
xhr.open('GET','http://other.server/and/path/to/script');
xhr.onload = onLoadHandler;
xhr.send();

Access-Control-Allow-Origin

An overview of cross-origin resource sharing

Origin

Access-Control-Allow-Origin

The origin header

Origin

GET /data.xml HTTP/1.1
User-Agent: Opera/9.80 (Macintosh; Intel Mac OS X 10.6.8; U; en) Presto/2.10.289 Version/12.00
Host: datahost.example
Accept: text/html, application/xml;q=0.9, application/xhtml+xml, image/png, image/webp, image/jpeg, image/gif, image/x-xbitmap, */*;q=0.1
Accept-Language: en,en-US
Accept-Encoding: gzip, deflate
Referer: http://requestingserver.example/path/to/askingdocument.html Connection: Keep-Alive
Origin: http://requestingserver.example[/code] 
Origin
 typically contains the
scheme, host name, and port of the requesting document. It is not an author request header, meaning it can’t be set or modified using the
setRequestHeader()
 method;
user agents will ignore it if you try. Its entire purpose is to inform the target server about the origins of this request. Bear in mind that there is no trailing slash.

The 
Access-Control-Allow-Origin
 response header
The 
Access-Control-Allow-Origin
 header
is sent by the target server in response to a cross-origin request. It tells the user agent whether access should be granted to the requesting origin. DOM
operations involving a cross-origin XHR request will not be completed unless the requested URL allows it. An example follows:
HTTP/1.1 200 OK
Date: Fri, 27 May 2011 21:27:14 GMT
Server: Apache/2
Last-Modified: Fri, 27 May 2011 19:29:00 GMT
Accept-Ranges: bytes
Content-Length: 1830
Keep-Alive: timeout=15, max=97
Connection: Keep-Alive
Content-Type:  application/xml; charset=UTF-8
Access-Control-Allow-Origin: *


In this case, we’re using a wild card (*) to allow access from any origin.
This is fine if you are offering a public-facing API.
For most other uses, you'll want to set a more specific origin value.

Sending user credentials with cross-domain requests
There may be occasions when you will want to send cookie data along with your cross-domain request. That’s where the 
withCredentials
 attribute
comes in handy. It is a boolean attribute that alerts the browser that it should send user
credentials along with the request. By default, the credentials flag is 
false
.
In the code below, let’s assume that our request is going from http://foo.example to http://other.server: 
var xhr = new XMLHttpRequest();
var onLoadHandler = function(event) {
doSomething(event.target.responseText);
}
xhr.open('GET','http://other.server/and/path/to/script');
xhr.withCredentials = true;
xhr.onload = onLoadHandler;
xhr.send();


In our XHR
credentials demo, we are using a counter cookie to track the number of visits. If you examine the request and response data (you can do this with Dragonfly' Network panel), you will see that the browser is sending request cookies and receiving response
cookies. Our server-side script will return text containing the new visit count, and update the value of the cookie.

Keep the following in mind when making requests with credentials:

withCredentials
 is only necessary
for cross-origin requests.

The 
Access-Control-Allow-Origin
 header
of the requested URI can not contain a wildcard (*).

The 
Access-Control-Allow-Credentials
 header
of the requested URI must be set to
true
.

Only a subset of response headers will be available to 
getAllRequestHeaders()
,
unless the 
Access-Control-Expose-Headers
 header
has been set.

Same-origin requests will ignore the credentials flag. A wildcard 
Access-Control-Allow-Origin
 header
value will cause an exception. If the value of 
Access-Control-Allow-Credentials
 is 
false
, cookies
will still be sent and received, however they will not be available to the DOM.

Sending data as key-value pairs with 
FormData
 objects
In previous implementations, data sent via XHR had to be submitted as a string, either using URL-encoding, or JSON (with 
JSON.stringify()
).
The example below uses URL-encoding:
var msg = 'field1=foo&field2=bar';
var xhr = new XMLHttpRequest();
xhr.open('POST','/processing_script');
xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
xhr.send(msg);


Now, we can use the 
FormData
 object,
and its ordered, key-value pairs. The syntax offers three benefits:

Scripts are more readable

Data is sent in key-value pairs, as with regular HTML forms

FormData
 objects are sent with 
multipart/form-data
 encoding,
making it possible to use XHR for sending binary data.

If you've ever worked with 
URLVariables in
ActionScript 3.0, 
FormData
 will
feel familiar. First create a 
FormData
 object,
then add data using the 
append()
 method.
The 
append()
 method requires
two parameters: 
key
 and 
value
.
Each 
FormData
 key becomes a
variable name available to your server-side script. An example follows:
var xhr = new XMLHttpRequest();
var dataToSend = new FormData(); // create a new FormData object

xhr.open('POST','/processing_script');

dataToSend.append('name','Joseph Q. Public'); // add data to the object
dataToSend.append('age','52');
dataToSend.append('hobby','knitting');

xhr.send(dataToSend); // send the object


We’ve passed the 
FormData
 object
as the argument of the 
send()
 method:
xhr.send(dataToSend)
.
We did not set a 
Content-Type
 header
on our 
XMLHttpRequest
object.
Let's take a look at the request headers sent by Opera:
POST /processing_script HTTP/1.1
User-Agent: Opera/9.80 (Macintosh; Intel Mac OS X 10.6.8) Presto/2.10.289 Version/12.00
Host: datahost.example
Accept: text/html, application/xml;q=0.9, application/xhtml+xml, image/png, image/webp, image/jpeg, image/gif, image/x-xbitmap, */*;q=0.1
Accept-Language: en,en-US
Accept-Encoding: gzip, deflate
Expect: 100-continue
Referer: http://datahost.example/upload/ Connection: Keep-Alive
Content-Length: 4281507
Content-Type: multipart/form-data; boundary=----------J2GMKTyAkjRjNgFzKv3VBJ


Opera has added the 
Content-Type
 header
for us because we are using a 
FormData
 object.
Other browsers do the same.

Using 
FormData
 with an HTML form
You can also send the values from a form with 
FormData
,
by passing the form to the
FormData
 object
as shown below (view
an XHR FormData demo).
var submitHandler = function(event) {
var dataToSend = new FormData(event.target), xhr = new XMLHttpRequest();
xhr.open('POST','/processing_script');
xhr.send(dataToSend);
}

var form = document.getElementById('myform');

form.addEventListener('submit',submitHandler,false);


FormData
 is still untrusted
data. Treat input from a 
FormData
 object
as you would any other kind of form submission.

Monitoring data transfers with progress events
XMLHttpRequest now provides progress event attributes that allow us to monitor data transfers. Previously, we would listen to the 
readystatechange
 event,
as in the example below:
var xhr = new XMLHttpRequest();
var onReadyStateHandler = function(event) {
if( event.target.readyState == 4 && event.target.status == 200){
/* handle the response */
}
}
xhr.open('GET','/path_to_data');
xhr.onreadystatechange = onReadyStateHandler;
xhr.send();


Though it works well for alerting us that all of our data has downloaded, 
readystatechange
doesn’t
tell us anything about how much data has been received. For backward compatibility, it remains a part of the specification. The 
ProgressEvent
 interface,
however, is far more robust. It adds seven events that are available to both the 
XMLHttpRequest
 and
the
XMLHttpRequestUpload
 objects.

The different 
XMLHttpRequest
 Progress
Events are as follows:

ProgressEvent
 inherits from
the DOM,
Level 2 
EventTarget
 interface
so we can either use event attributes such as 
onload
,
or the 
addEventListener
 method
in our code. In the examples above, we've used event attributes. In our next example, we’ll use
addEventListener
.

Monitoring uploads
All 
XMLHttpRequest
-based file
uploads create an 
XMLHttpRequestUpload
 object,
which we can reference with the 
upload
 attribute
of 
XMLHttpRequest
. To monitor
upload progress, we’ll need to listen for events on the 
XMLHttpRequestUpload
 object.

In the code below, we’re listening for the 
progress
, 
load
 and 
error
 events:
var onProgressHandler = function(event) {
if(event.lengthComputable) {
var howmuch = (event.loaded / event.total) * 100;
document.querySelector('progress').value = Math.ceil(howmuch);
} else {
console.log("Can't determine the size of the file.");
}
}

var onLoadHandler = function() {
displayLoadedMessage();
}

var onErrorHandler = function() {
displayErrorMesssage();
}

xhr.upload.addEventListener('progress', onProgressHandler, false);
xhr.upload.addEventListener('load', onLoadHandler, false);
xhr.upload.addEventListener('error', onErrorHandler, false);


Pay special attention to the 
lengthComputable
, 
loaded
 and 
total
 properties
used in the
onProgressHandler
 function.
Each of these are properties of the progress event object. The
lengthComputable
 property
reveals whether or not the browser can detect the input file size, while 
loaded
 and 
total
 reveal
how many bytes have been uploaded and the total size of the file. You can view
an XHR progress events demo.

These events only monitor the browser’s progress in sending data to or receiving data from the server. When uploading, you may experience a lag between when the 
load
 event
is fired and when the server sends a response. How long of a lag will depend on the size of the file, the server’s resources, and network speeds.

In the example above, we’re setting event listeners on the 
XMLHttpRequestUpload
 object.
To monitor file downloads, add event listeners to the 
XMLHttpRequest
 object
instead.

Enforcing a response MIME type
MIME-type mismatches are pretty common on the web. Sometimes XML data will have a
Content-type:
text/html
 response header, which will cause the value of
xhr.responseXML
 to
be 
null
.

To ensure that the browser handles such responses in the way we’d like, we can use the
overrideMimeType()
 method.
In the example below, data.xml returns the following response headers:
Date: Sat, 04 Jun 2011 03:11:31 GMT
Server: Apache/2.2.17
Access-Control-Allow-Origin: *
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/html; charset=UTF-8


That’s the wrong content type for an XML document. So let’s guarantee that the browser treats data.xml as
XML, and populates the 
responseXML
 attribute:
var xhr = new XMLHttpRequest();
xhr.open('GET','data.xml');
xhr.overrideMimeType('application/xml');
xhr.send();
xhr.addEventListener('load', function(event) {
console.log( event.target.responseXML );
}, false);


Now the value of 
xhr.responseXML
 is
a 
Document
 object, which means
we can parse the data as we would any other XML document. View
an XHR override MIME type demo.

Enforcing a response type
It's also possible to tell the browser to handle a response as 
text
, 
json
,
an 
arraybuffer
, a
blob
 or
and 
document
 using the 
responseType
 property.

As with 
overrideMimeType
, the 
responseType
 property
must be set before the request is sent. In the example below, we are telling Opera to treat the response as a 
document
,
and write the 
firstChild
 to
the console (view
an enforcing response type demo):
var xhr = new XMLHttpRequest();
xhr.open('GET','data.xml');
xhr.responseType = 'document';
xhr.send();

xhr.addEventListener('load', function(e) {
console.log( event.target.response.firstChild );
} false);


Though 
responseType
 allows developers
to, say, handle image data as a byte array instead of a binary string, it does not work miracles. Changing 
document
 to 
json
 in
the example above would cause our response property to be 
null
 because
XML is not JSON. Similarly, invalid JSON data will also cause 
response
 to
be 
null
. When setting a 
responseType
,
you still need to ensure that your data is both valid and compatible with the specified type.

Note: As of publication, Opera does not support 
blob
 as
a value, and only supports XML and not HTML for the 
document
 type.
Chrome and Safari do not yet support 
json
 as
a value.

Learn more
These XMLHttpRequest improvements are a leap forward for client-side interactivity. For more on XMLHttpRequest, CORS, and related APIs, see the following resources:

XMLHttpRequest
specification

DOM
access control using cross-origin resource sharing

The
W3C file API by Bruce Lawson

XDomainRequest
Object (Internet Explorer 8 & 9)

Note: Cover image — Ajax and Achilles Gaming —
by Sharon
Mollerus.
attribute
type
Explanation
onloadstart
loadstart
When the request starts.
onprogress
progress
While loading and sending data.
onabort
abort
When the request has been aborted, either by invoking the
abort()
 method
or navigating away from the page.
onerror
error
When the request has failed.
onload
load
When the request has successfully completed.
ontimeout
timeout
When the author specified timeout has passed before the request could complete.
onloadend
loadend
When the request has completed, regardless of whether or not it was successful.