Section 2.1. XMLHttpRequest Overview

2.1. XMLHttpRequest Overview

Originally, Microsoft designed XMLHttpRequest to allow Internet Explorer (IE) to load XML documents from JavaScript. Even though it has XML in its name, XMLHttpRequest really is a generic HTTP client for JavaScript. With it, JavaScript can make GET and POST HTTP requests. (For POST requests, data can be sent to the server in a format of your choosing.) The main limitations to XMLHttpRequest are due to the browser security sandbox. It can make only HTTP(S) requests (file URLs, for example, won't work), and it can make requests only to the same domain as the currently loaded page.

The security limitations of XMLHttpRequest do limit the ways in which you can use it, but the trade-off in added security is well worth it. Most attacks against JavaScript applications center around injecting malicious code into the Web page. If XMLHttpRequest allowed requests to any Web site, it would become a major player in these attacks. The security sandbox reduces these potential problems. In addition, it simplifies the programming model because the JavaScript code can implicitly trust any data it loads from XMLHttpRequest. It can trust the data because the new data is just as secure as the page that loaded the initial page.

Despite the fact that XMLHttpRequest provides only a small API and just a handful of methods and properties, it has its differences between browsers. These differences are mainly in event handling and object instantiation (in IE, XMLHttpRequest is actually an ActiveX object), so they aren't hard to work around. In the following overview of the XMLHttpRequest API, the Mozilla syntax for XMLHttpRequest instantiation is used. If you want to run the examples in IE, you need to replace new XMLHttpRequest(); with either new ActiveXObject("MSXML2.XMLHTTP.3.0"); or the full cross-browser instantiation method shown in the "Cross-Browser XMLHttpRequest" section of this chapter.

XMLHttpRequest is the most-used method for AJAX communications because it provides two unique features. The first feature provides the ability to load new content without that content being changed in any way, which makes it extremely easy to fit AJAX into your normal development patterns. The second feature allows JavaScript to make synchronous calls. A synchronous call stops all other operations until it's complete, and while this isn't an option that is usually used, it can be useful in cases in which the current request must be completed before further actions are taken.

2.1.1. XMLHttpRequest::Open()

The open method is used to set the request type (GET, POST, PUT, or PROPFIND), the URL of the page being requested, and whether the call will be asynchronous. A username and password for HTTP authentication can also be optionally passed. The URL can be either a relative path (such as page.html) or a complete one that includes the server's address (such as http://blog.joshuaeichorn.com/page.html). The basic method signature is:

open(type,url,isAsync,username,password)

In the JavaScript environment, security restrictions are in place. These security restrictions cause the open method to throw an exception if the URL is from a different domain than the current page. The following example uses open to set up a synchronous GET request to index.html:

1 var req = new XMLHttpRequest(); 2 req.open('GET', 'index.html', false); 3 req.send(null); 4 if(req.status == 200) 5 alert(req.responseText);

2.1.2. XMLHttpRequest::Send()

The send method makes the connection to the URL specified in open. If the request is asynchronous, the call will return it immediately; otherwise, the call will block further execution until the page has been downloaded. If the request type is POST, the payload will be sent as the body of the request that is sent to the server. The method signature is:

send(payload)

When you make a POST request, you will need to set the Content-type header. This way, the server knows what to do with the uploaded content. To mimic sending a form using HTTP POST, you set the content type to application/x-www-form-urlencoded. URLencoded data is the same format that you see in a URL after the "?". You can see an example of this encoded data by making a form and setting its method to GET. The following example shows a synchronous POST request to index.php that is sending a URLencoded payload. If index.php contains <?php var_dump($_POST); ?>, you can see the submitted data translated as if it's a normal form in the alert:

1 var req = new XMLHttpRequest(); 2 req.open('POST', 'index.php', false); 3 req.setRequestHeader('Content-type', 4            'application/x-www-form-urlencoded;charset=UTF-8;'); 5 req.send('hello=world&XMLHttpRequest=test'); 6 if(req.status == 200) 7   alert(req.responseText);

2.1.3. XMLHttpRequest::setRequestHeader()

There are many different cases in which setting a header on a request might be useful. The most common use of setRequestHeader() is to set the Content-type, because most Web applications already know how to deal with certain types, such as URLencoded. The setRequestHeader method signature takes two parameters: the header to set and its value:

setRequestHeader(header,value)

Because requests sent using XMLHttpRequest send the same standard headers, including cookie headers and HTTP authentication headers, as a normal browser request, the header name will usually be the name of the HTTP header that you want to override. In addition to overriding default headers, setRequestHeader is useful for setting custom, application-specific headers. Custom headers are generally prefixed with X- to distinguish them from standard ones. The following example makes a synchronous GET request adding a header called X-foo to test.php. If test.php contains <?php var_dump($_SERVER); ?>, you will see the submitted header in the alert:

1 var req = new XMLHttpRequest(); 2 req.open('GET', 'test.php', false); 3 req.setRequestHeader('X-foo','bar'); 4 req.send(null); 5 6 if(req.status == 200) 7      alert(req.responseText);

2.1.4. XMLHttpRequest::getResponseHeader() and getAllResponseHeaders()

The geTResponseHeader method allows you to get a single header from the response; this is especially useful when all you need is a header like Content-type; note that the specified header is case-insensitive. The method signature is as follows:

getResponseHeader(header)

getAllResponseHeaders returns all the headers from the response in a single string; this is useful for debugging or searching for a value. The following example makes a synchronous GET request to test.html. When the client receives a response, the Content-type is alerted and all the headers are alerted:

1 var req = new XMLHttpRequest(); 2 req.open('GET', 'test.html', false); 3 req.send(null); 4 5 if(req.status == 200) { 6     alert(req.getResponseHeader('Content-type')); 7       alert(req.getAllResponseHeaders()); 8 }

2.1.5. Other XMLHttpRequest Methods

All browsers implement an abort() method, which is used to cancel an in-progress asynchronous request. (An example of this is shown in the "Sending Asynchronous Requests" section in this chapter.) Mozilla-based browsers also offer some extra methods on top of the basic API; for instance, addEventListener() and removeEventListener() provide a way to catch status events without using the on* properties. There is also an overrideMimeType() method that makes it possible to force the Content-type to text/xml so that it will be parsed into a DOM document even if the server doesn't report it as such. The Mozilla-specific methods can be useful in certain circumstances, but in most cases, you should stay away from them because not all browsers support them.

2.1.6. XMLHttpRequest Properties

XMLHttpRequest provides a number of properties that provide information or results about the request. Most of the properties are self-explanatory; you simply read the value and act on it. The on* properties are event handlers that are used by assigning a function to them. A list of all the properties follows:

• status. The HTTP status code of the request response.

• statusText. The HTTP status code that goes with the code.

• readyState. The state of the request. (See Table 2-1 in the next section of this chapter for values.)

• responseText. Unparsed text of the response.

• responseXML. Response parsed into a DOM Document object; happens only if Content-type is text/xml.

• onreadystatechange. Event handler that is called when readyState changes.

• onerror. Mozilla-only event handler that is called when an error happens during a request.

• onprogress. Mozilla-only event handler that is called at an interval as content is loaded.

• onload. Mozilla-only event handler that is called when the document is finished loading.

Note

Mozilla resets event handlers, such as onreadystatechange, after a request is completed, so you need to reset them if you are making multiple calls with the same object.

2.1.7. readyState Reference

Table 2-1 shows the possible values for the readyState variable. It will return a number representing the current state of the object. Each request will progress through the list of readyStates.

Table 2-1. readyState Levels

readyState Status Code	Status of the XMLHttpRequest Object
(0) UNINITIALIZED	The object has been created but not initialized. (The open method has not been called.)
(1) LOADING	The object has been created, but the send method has not been called.
(2) LOADED	The send method has been called, but the status and headers are not yet available.
(3) INTERACTIVE	Some data has been received. Calling the responseBody and responseText properties at this state to obtain partial results will return an error, because status and response headers are not fully available.
(4) COMPLETED	All the data has been received, and the complete data is available in the responseBody and responseText properties.

The readyState variable and the onreadystatechange event handler are linked in such a way that each time the readyState variable is changed, the onreadystatechange event handler is called.