AJAX JavaScript Control (2012 Update)

AJAX Control lets you quickly embed AJAX controls using text, XML and XSLT in a variety of ways to your web pages.

Downloads for the latest version of AJAXControl and source code for all the examples can be found here.

Introduction

Recently AJAX has become quite trendy among web developers, it was first brought to my attention when we used Frappr on our radio station to show a world map of listeners during a New Year’s special broadcast.

Although basic AJAX is fairly simple to implement, a robust client that is also user-friendly with good error fallback is not. AJAX can also work in many different ways from the user’s point of view, and interact with many regions of a page differently. Recently I have wanted to add a display of the current song on the radio to Deviant Audio’s web site; I could’ve done this equally well with a server-side PHP script, but decided it would be a good opportunity to sharpen up my JavaScript and write an AJAX control library that I could later incorporate into the new XSL templating system, reducing the task of making generic AJAX controls into a few simple XML elements (and the server-side code).

Compatibility

This version has been tested with Internet Explorer 7+, Firefox 1.5+ and Chrome. It is known to work on the latest versions of Internet Explorer, Firefox and Chrome at the time of writing.

Examples

The source code for both the control itself, the helper functions and the examples is fully documented and not all features are shown below. I recommend you check the source code for further details.

Using text-based responses:

• Form-based requests
  (adds two numbers together; uses text-based requests)
• Timer-based requests with pre-defined parameters
  (also shows the standard loader, passing user arguments to AJAX request callback)
• Event-triggered requests
  (sends a request when a drop-down box is changed; also shows how to programmatically make a request based on the form contents when the page first loads, and manual user-click requests)
• Use standard loader to disable form input elements
  (also shows other standard loader features, passing user arguments to AJAX request callback, form-based submission)
• Multiple independent AJAX controls on one page
  (also shows timer-based request triggering)
• Real-time AJAX Shoutbox
  (uses timers and form-based triggers, also shows how to redirect errors to a page element and handle textual AJAX requests)

Using XML-based responses:

• Using an XSL stylesheet
  (the same as the Form-based requests example except the response is returned as XML and an XSL stylesheet is used in the browser to transform it to output HTML)
• Cached XSL stylesheet with user-defined input parameters
  (shows how to set input parameters to a stylesheet and stop it from being re-loaded on every AJAX call; also shows how to use POST instead of GET as all the previous examples have)
• Multiple XSL transforms on a single result
  (shows how to run multiple XSL transforms against the result of a single AJAX call and place the outputs on different parts of the page)
• Using a form to configure the input parameters to an XSL stylesheet
  (shows how to let the user choose the input parameters; note you can also use hidden form fields if you want to used fix settings or settings that can be modified on the fly with JavaScript)
• Using multiple response functions
  (shows how to attach more than one function to execute when an AJAX call completes)

ChangeLog

Feature list 2006-06-03:

• object-oriented JavaScript (foo = new AJAXControl(…))
• GET and POST methods
• handles plain text and XML response types
• arbitrary user-defined arguments can be supplied to AJAX response callback function
• multiple independent AJAX controls on a single page
• requests can be triggered by any user event (such as a mouse click, form alteration or submission)
• requests can be triggered on a timer
• form fields can be automatically aggregated and passed to the server-side script when using a form to trigger a request
• DOM helper functions to make parsing response XML and modifying the page to display the results simpler
• optional loader/unloader callbacks called before a request starts and after it ends (designed to provide activity indicators to the user)
• default loader/unloader provided which allows any combination of page elements to be toggled on/off in the request phase (this is the most common activity indicator scenario, saves code repitition)
• default error handler (alerts an error) for when AJAX support isn’t available in the browser, overridable with a custom error handler to allow your application to degrade gracefully
• does not interfere with existing JavaScript event handlers on a page (notably ‘onload’)
• tested in IE 6 and Firefox 1.5
• TODO: user handlers for return status other than 200 OK

New features added 2006-06-05 (v1.00):

• Default parameters to the server-side script can be overridden when making a request
• Discard/queue (stall) behaviour when making an AJAX request can now be specified (lets overlapping requests triggered on a timer to be discarded while queueing user AJAX form submissions so their input isn’t lost)
• Default loader/unloader can disable/enable user-specified form controls to prevent multiple submissions
• Default error handler added for failed AJAX requests (either displays the status code and error text in an alert box, or redirects the error text to a user-specified element on the web page)
• Default error handler can be replaced with a custom error handler
• Numerous improvements to DOMHelper functions, nodes/IDs can be used interchangeably, elements are created in xhtml namespace when serving as XHTML, text handling functions added (notably replacing linebreaks with nodes in an XHTML-compliant manner), recursive child copying added
• JavaDoc-style documentation added to source code
• Six example pages created
• Tested in Firefox served as application/xml+xhtml (in standards compliance mode)

Changes made 2006-07-16 (v1.01):

• Feature: timeout for requests added to AJAXControl constructor – default 5 seconds. In Firefox, double-clicking an AJAX trigger (causing two requests) could cause a deadlock. The timeout is applied only when the 2nd request is triggered; it waits the specified number of seconds from the moment the 2nd request is triggered, for the 1st request to complete. If the 1st request completes within the timeout, the 2nd request is executed immediately afterwards, otherwise it is discarded

Changes made 2007-01-22 (v1.02):

• AJAXHelper class was added with textResult() and xslResult() helper methods to help yo quickly insert the result of an AJAX call returning text or XML into a web page
• AJAXHelper.xslCachedResult() was added to allow the same XSL stylesheet to be used client-side repeatedly without re-loading it for each new AJAX call. The helper also allows you to set input parameters for XSL stylesheets

Changes made 2007-01-23 (v1.03):

• The syntax for creating AJAX controls has been simplified
• AJAXHelper.xslCachedResult() now allows you to use multiple transforms and write to multiple places on the page for a single AJAX call

Changes made 2007-03-28 (v1.03 – general library v1.03):

• Bug fix in the handling of include() with whole file paths

Changes made 2009-03-07 (v1.04):

• AJAXControl.setResponseMethod can now take multiple response methosd so that more than one function can be executed when the AJAX request completes
• XSL transforms now work in Google Chrome

Changes made 2012-05-18:

• Five new examples were added showing how to use the XML and XSL features
• The existing examples were brought up to date to work with the current version of AJAX Control

Please send feedback to me via the contact page or leave a comment below.