Getting Started

This article guides you through the AJAX basics and gives you two simple hands-on examples to get you started.

What's AJAX?

AJAX stands for Asynchronous JavaScript and XML. In a nutshell, it is the use of the XMLHttpRequest object to communicate with server-side scripts. It can send as well as receive information in a variety of formats, including JSON, XML, HTML, and even text files. AJAX’s most appealing characteristic, however, is its "asynchronous" nature, which means it can do all of this without having to refresh the page. This lets you update portions of a page based upon user events.

The two major features of AJAX allow you to do the following:

• Make requests to the server without reloading the page
• Receive and work with data from the server

Step 1 – How to make an HTTP request

In order to make an HTTP request to the server using JavaScript, you need an instance of a class that provides this functionality. This is where XMLHttpRequest comes in. Such a class was originally introduced in Internet Explorer as an ActiveX object called XMLHTTP. Then, Mozilla, Safari and other browsers followed, implementing an XMLHttpRequest class that supports the methods and properties of Microsoft's original ActiveX object. Meanwhile Microsoft has implemented XMLHttpRequest as well.

// Old compatibility code, no longer needed.
if (window.XMLHttpRequest) { // Mozilla, Safari, IE7+ ...
    httpRequest = new XMLHttpRequest();
} else if (window.ActiveXObject) { // IE 6 and older
    httpRequest = new ActiveXObject("Microsoft.XMLHTTP");
}

Next, you need to decide what you want to do after you receive the server response to your request. At this stage, you just need to tell the HTTP request object which JavaScript function will handle processing the response. This is done by setting the onreadystatechange property of the object to the name of the JavaScript function that should be called when the state of the request changes, like this:

httpRequest.onreadystatechange = nameOfTheFunction;

Note that there are no parentheses after the function name and no parameters passed, because you're simply assigning a reference to the function, rather than actually calling it. Also, instead of giving a function name, you can use the JavaScript technique of defining functions on the fly (called "anonymous functions") and define the actions that will process the response right away, like this:

httpRequest.onreadystatechange = function(){
    // process the server response
};

Next, after you've declared what will happen as soon as you receive the response, you need to actually make the request. You need to call the open() and send() methods of the HTTP request class, like this:

httpRequest.open('GET', 'https://www.example.org/some.file', true);
httpRequest.send(null);

• The first parameter of the call to open() is the HTTP request method – GET, POST, HEAD or any other method you want to use and that is supported by your server. Keep the method capitalized as per the HTTP standard; otherwise some browsers (like Firefox) might not process the request. For more information on the possible HTTP request methods you can check the W3C specs.
• The second parameter is the URL of the page you're requesting. As a security feature, you cannot call pages on 3rd-party domains. Be sure to use the exact domain name on all of your pages or you will get a "permission denied" error when you call open(). A common pitfall is accessing your site by domain.tld, but attempting to call pages with www.domain.tld. If you really need to send a request to another domain, see HTTP access control.
• The optional third parameter sets whether the request is asynchronous. If TRUE (the default), the execution of the JavaScript function will continue while the response of the server has not yet arrived. This is the A in AJAX.

The parameter to the send() method can be any data you want to send to the server if POST-ing the request. Form data should be sent in a format that the server can parse easily. This can be as a query string, like:

"name=value&anothername="+encodeURIComponent(myVar)+"&so=on"

or in several other formats, including JSON, SOAP, etc.

Note that if you want to POST data, you may have to set the MIME type of the request. For example, use the following line before calling send() for form data sent as a query string:

httpRequest.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');

Step 2 – Handling the server response

Remember that when you were sending the request, you provided the name of a JavaScript function that is designed to handle the response.

httpRequest.onreadystatechange = nameOfTheFunction;

Let's see what this function should do. First, the function needs to check for the state of the request. If the state has the value of XMLHttpRequest.DONE (evaluating to 4), that means that the full server response has been received and it's OK for you to continue processing it.

if (httpRequest.readyState === XMLHttpRequest.DONE) {
    // everything is good, the response is received
} else {
    // still not ready
}

The full list of the readyState values is documented at XMLHTTPRequest.readyState and is as follows:

• 0 (uninitialized)
• 1 (loading)
• 2 (loaded)
• 3 (interactive)
• 4 (complete)

(Source)

The next thing to check is the response code of the HTTP server response. All the possible codes are listed on the W3C site. In the following example, we differentiate between a successful or unsuccessful AJAX call by checking for a  200 OK response code.

if (httpRequest.status === 200) {
    // perfect!
} else {
    // there was a problem with the request,
    // for example the response may contain a 404 (Not Found)
    // or 500 (Internal Server Error) response code
}

Now after you've checked the state of the request and the HTTP status code of the response, it's up to you to do whatever you want with the data the server has sent to you. You have two options to access that data:

• httpRequest.responseText – returns the server response as a string of text
• httpRequest.responseXML – returns the response as an XMLDocument object you can traverse using the JavaScript DOM functions

Note that the steps above are only valid if you used an asynchronous request (third parameter of open() was set to true). If you used an synchronous request you don't need to specify a function, you can access the data return by the server right after calling send(), because the script will stop and wait for the server answer.

Step 3 – A Simple Example

Let's put it all together and do a simple HTTP request. Our JavaScript will request an HTML document, test.html, which contains the text "I'm a test." and then we'll alert() the contents of the test.html file.  Note that this example uses only JavaScript (no jQuery is involved here).  Also, the HTML, XML and PHP files should be placed in the same directory.

<span id="ajaxButton" style="cursor: pointer; text-decoration: underline">
  Make a request
</span>
<script type="text/javascript">
(function() {
  var httpRequest;
  document.getElementById("ajaxButton").onclick = function() { makeRequest('test.html'); };

  function makeRequest(url) {
    httpRequest = new XMLHttpRequest();

    if (!httpRequest) {
      alert('Giving up :( Cannot create an XMLHTTP instance');
      return false;
    }
    httpRequest.onreadystatechange = alertContents;
    httpRequest.open('GET', url);
    httpRequest.send();
  }

  function alertContents() {
    if (httpRequest.readyState === XMLHttpRequest.DONE) {
      if (httpRequest.status === 200) {
        alert(httpRequest.responseText);
      } else {
        alert('There was a problem with the request.');
      }
    }
  }
})();
</script>

In this example:

• The user clicks the link "Make a request" in the browser;
• The event handler calls the makeRequest() function with a parameter – the name test.html of an HTML file in the same directory;
• The request is made and then (onreadystatechange) the execution is passed to alertContents();
• alertContents() checks if the response was received and it's an OK and then alert()s the contents of the test.html file.

In the event of a communication error (such as the webserver going down), an exception will be thrown in the onreadystatechange method when attempting to access the status field. To mitigate this problem, you could wrap your if...then statement in a try...catch:

function alertContents() {
  try {
    if (httpRequest.readyState === XMLHttpRequest.DONE) {
      if (httpRequest.status === 200) {
        alert(httpRequest.responseText);
      } else {
        alert('There was a problem with the request.');
      }
    }
  }
  catch( e ) {
    alert('Caught Exception: ' + e.description);
  }
}

Step 4 – Working with the XML response

In the previous example, after the response to the HTTP request was received we used the responseText property of the request object, which contained the contents of the test.html file. Now let's try the responseXML property.

First off, let's create a valid XML document that we'll request later on. The document (test.xml) contains the following:

<?xml version="1.0" ?>
<root>
    I'm a test.
</root>

In the script we only need to change the request line to:

...
onclick="makeRequest('test.xml')">
...

Then in alertContents(), we need to replace the line alert(httpRequest.responseText); with:

var xmldoc = httpRequest.responseXML;
var root_node = xmldoc.getElementsByTagName('root').item(0);
alert(root_node.firstChild.data);

This code takes the XMLDocument object given by responseXML and uses DOM methods to access some of the data contained in the XML document. You can see the test.xml here and the updated test script here.

Step 5 – Working with data

Finally, let's send some data to the server and receive a response. Our JavaScript will request a dynamic page this time, test.php, which will take the data we send and return a "computed" string - "Hello, [user data]!" - which we'll alert().

First we'll add a text box to our HTML so the user can enter their name:

<label>Your name: 
  <input type="text" id="ajaxTextbox" />
</label>
<span id="ajaxButton" style="cursor: pointer; text-decoration: underline">
  Make a request
</span>

We'll also add a line to our event handler to get the user's data from the text box and send it to the makeRequest() function along with the URL of our server-side script:

  document.getElementById("ajaxButton").onclick = function() { 
      var userName = document.getElementById("ajaxTextbox").value;
      makeRequest('test.php',userName); 
  };

We need to modify makeRequest() to accept the user data and pass it along to the server. We'll change the request method from GET to POST, and include our data as a parameter in the call to httpRequest.send():

  function makeRequest(url, userName) {

    ...

    httpRequest.onreadystatechange = alertContents;
    httpRequest.open('POST', url);
    httpRequest.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    httpRequest.send('userName=' + encodeURIComponent(userName));
  }

The function alertContents() can be written the same way it was in Step 3 to alert our computed string, if that's all the server returns. However, let's say the server is going to return both the computed string and the original user data. So if our user typed "Jane" in the text box, the server's response would look like this:

{"userData":"Jane","computedString":"Hi, Jane!"}

To use this data within alertContents(), we can't just alert the responseText, we have to parse it and alert computedString, the property we want:

function alertContents() {
  if (httpRequest.readyState === XMLHttpRequest.DONE) {
    if (httpRequest.status === 200) {
      var response = JSON.parse(httpRequest.responseText);
      alert(response.computedString);
    } else {
      alert('There was a problem with the request.');
    }
  }
}

The test.php file should contain the following:

$name = (isset($_POST['userName'])) ? $_POST['userName'] : 'no name';
$computedString = "Hi, " . $name;
$array = ['userName' => $name, 'computedString' => $computedString];
echo json_encode($array);

For more on DOM methods, be sure to check Mozilla's DOM implementation documents.