Web 2.0 Primer: How Does Ajax Work? With Ajax Example

What is TWiki?

A leading open source enterprise wiki and Web 2.0 application platform used by 50,000 small businesses, many Fortune 500 companies, and millions of people.
Learn more.

"Ajax is a group of interrelated web development methods used on the client-side to create interactive web applications. With Ajax, web applications can retrieve data from the server asynchronously in the background without interfering with the display and behavior of the existing page. Data is usually retrieved using the XMLHttpRequest object."

Simply put, we have an HTML page where the user does some action, like pressing a button. This action calls a script on the server, and the output of that script is shown somewhere on the page, without reloading the whole page. In the Facebook image example, when you press the right arrow key, a call to the server is done to fetch and display the next image (this is a simplified view, images are pre-fetched for speed).

As an exercise, let's create an HTML form that has a form field and a button. The task is to load some data from the server when the button is pressed, without reloading the current page. For this exercise, basic understanding of HTML and some JavaScript is assumed.

There are three basic steps:

1. Create an HTML form with a form field and a button.
2. Create a server side script that is called when the button is pressed.
3. Create JavaScript code to do an Ajax call when the button is pressed.

Step 1: Create an HTML form with a form field and a button

<form name="form1">
 Demo:
 <input name="demo" type="text" />
 <input value="Go" type="button"
  onclick="JavaScript:alert( 'Value is: ' + this.form.demo.value )" />
</form>

For now, when the user presses the [Go] button, the onclick event simply pops up an alert box with the value of the text field. In step 3 we change that to an Ajax action.

Step 2: Create a server side script that is called when the button is pressed

The script can be created in any language. If you do not bother about dynamic content it can even be a static HTML page or a page fragment. For this exercise we (ab)use the TWiki Enterprise Collaboration Platform, but it could as well be a shell script, PHP, Perl or another language. TWiki is suitable for this exercise because pages can be dynamically driven by URL parameters. Let's create a TWiki page that returns three bullets. To add some dynamic behavior, we return the value of a URL parameter in the first bullet.

   * URL parameter demo: %URLPARAM{ "demo" default="(empty)" }%
   * You are: %WIKIUSERNAME%
   * Your IP address: %REMOTE_ADDR%
<!--
   * Set SKIN = text
-->

The first bullet returns the value of the URL parameter called demo. If the parameter is empty or missing, we show the string (empty). The second bullet shows the name of the user, and the third bullet shows the IP address of the user's computer. There is one more bullet, hidden in HTML comments. It tells TWiki to treat the page as plain text, e.g. it does not add the usual HTML header and body tags.

Step 3: Create JavaScript code to do an Ajax call when the button is pressed

Although it is possible to hand-code Ajax, it is usually the easiest to use an Ajax framework, which is a JavaScript library. For this exercise we use the popular jQuery library.

<script src="http://code.jquery.com/jquery-1.4.4.js"></script>
<form name="form3">
 Demo:
 <input name="demo" type="text" />
 <input value="Go" type="button"
  onclick="JavaScript:$( '#result2' ).load(
   '%SCRIPTURLPATH{view}%/%WEB%/AjaxExampleScript?demo=' +
   escape( this.form.demo.value ) );" />
</form>
<div id="result3"></div>

First we define a place where the result of the Ajax call should be put. We use a div with ID result3. jQuery has at least three API calls for Ajax. We use the very basic .load() method. It loads data from the server and places the returned HTML into the matched element. In our case, $( '#result3' ) identifies the div with ID result3. The .load() method expects a parameter containing the URL of the server script. We supply the URL of our AjaxExampleScript page in a portable way using the %SCRIPTURLPATH% TWiki variable. We also append a URL parameter named demo with the URL-escaped value of the input field.

That's it! Now you understand the basics of Ajax.

Alternative step 3: Use handcrafted JavaScript for Ajax call

For the adventurous folks, let's look how we can code an Ajax call from scratch, without using an external Ajax framework, and in a browser agnostic way. Some more JavaScript is involved:

<script language="Javascript">
function ajaxCall( urlStr, queryStr, divID ) {
  var request = false;
  var self = this;
  if (window.XMLHttpRequest) {
    self.request = new XMLHttpRequest();  // Mozilla and Safari
  } else if (window.ActiveXObject) {
    self.request = new ActiveXObject("Microsoft.XMLHTTP"); // IE
  }
  self.request.open( 'POST', urlStr, true );
  self.request.setRequestHeader( 'Content-Type',
    'application/x-www-form-urlencoded' );
  self.request.onreadystatechange = function() {
    if (self.request.readyState == 4) {
      document.getElementById( divID ).innerHTML =
        self.request.responseText;
    }
  }
  document.getElementById( divID ).innerHTML =
    '<ul><li>%ICON{processing-bar}%</li></ul>';
  self.request.send( queryStr );
}
</script>

<form name="form4">
 Demo:
 <input name="demo" type="text" />
 <input value="Go" type="button"
  onclick="JavaScript:ajaxCall(
    '%SCRIPTURLPATH{view}%/%WEB%/AjaxExampleScript',
    'demo=' + escape( this.form.demo.value ), 'result4' )" />
</form>
<div id="result4"></div>

Let us dissect the JavaScript code. On the oncall event, the function ajaxCall() is called with three parameters: The URL of the script, the query string containing the value of the form field, and the ID of the div where we want to put the result of the Ajax call.

The function ajaxCall() first initializes an XML-HTTP request object that does the communication to the server. Unfortunately there is not one standard, so we need to use some conditionals to make it work on Mozilla, IE and Safari. request.open() opens the connection to the server. We set the proper header using request.setRequestHeader(). Then we define the callback function, to be used when the server sends a response. We set a processing bar to let the user know that the request is under way. As a last step, we send the query string, which triggers the call to the server. Once we get the callback, we check for proper state, and we set the div with the response from the server using the innerHTML method.

This is a simple working Ajax example. We could make the code more robust, for example with proper handling in case there is no response from the server.

TWiki uses Ajax in several places, for example to convert from TML (TWiki Markup Language) to HTML when you edit a page with the WYSIWYG editor. TWiki has also a REST API that can be used to communicate with the TWiki server.

Let us know if this was helpful in understanding how Ajax works. And let us know what projects inspire you to try to add some Ajax.

TWiki References:

• WhatIsTWiki - introduction to TWiki
• TWikiReferenceManual - reference manual
• TWikiVariables - big list of TWiki variables
• TWikiScripts - TWiki scripts
• GettingInvolved - getting involved with the TWiki community

External References:

• Wikipedia:Ajax_%28programming%29 - Ajax article on Wikipedia
• Wikipedia:List_of_Ajax_frameworks - list of Ajax frameworks
• Ajax: A New Approach to Web Applications - article that coined the term and Q&A
• Ajax Tutorial - with GET, POST, text and XML examples
• Simple Ajax example
• http://www.w3.org/TR/XMLHttpRequest/ - XMLHttpRequest recommendation by W3C
• Wikipedia:Representational_State_Transfer - REST article on Wikipedia

The Ajax diagram is courtesy of Jesse James Garrett

Comments

A word of caution if you use this on a TWiki site together with the BlackListPlugin: The plugins bumps you on the blacklist if you save a page that contains a escape() JavaScript function, as is the case in these examples. You are OK of your IP address is on the whitelist.