webtweakers - homepage of bas van gaalen

About XConn — AJaX: Asynchronous Javascript and XML

XConn is a small Javascript library that uses the XMLHttpRequest object (for Mozilla or other standard-based browsers) or an ActiveXObject (for IE) to make a connection with a server in order to send and/or retreive data, without the need of reloading the page. It's based on the buzz of 'AJaX' and used in the quotes in the example.

This is an update from the May 2005 version and is loosely based on the Prototype JavaScript library.

"Yet another AJaX implementation?", you might ask, correctly. Yes, there are a already a lot of other libraries based on the XMLHttpRequest object out there — see the references at the end of this page. They all have their strengths, features, usages and even weaknesses in some cases. I decided to go for a simple yet standards based and hopefully secure approach.

Usage

Xconn has a single method to send a request to the server. Its syntax is as follows:

new Ajax.Request((string) url, (object) options);

Where url is the url to send the request to and options can be any of these:

Option	Default	Description
method	'post'	The HTTP method to use for the request. The other possibility is 'get'.
contentType	application/x-www-form-urlencoded	The Content-Type header for your request. When sending XML (in combination with option `postBody` you would have to change this.
parameters	''	The parameters for the request, which will be encoded into the URL for a 'get' method, or into the request body for the other methods. This can be provided either as a URL-encoded string or as a hash object, with properties representing parameters.
postBody	none	Specific contents for the request body on a 'post' method. If it is not provided, the contents of the parameters option will be used instead.
onSuccess		Invoked when a request completes and its status code is undefined or belongs in the 2xy family.
onFailure		Invoked when a request completes and its status code exists but is not in the 2xy family.

A typical request goes like this:

new Ajax.Request('/quotes/json', {
   method: 'GET',
   onSuccess: function(xhr) {
      // in case of json:
      var response = eval('(' + xhr.responseText + ')');
      // handle response...
   }
});

Example

The source code of the quote example below can be downloaded here:
quote.js — 517 bytes — Sep 2009

(change quote)

Retreiving...

Compatibility

XConn is compatible with the following browsers:

Mozilla 1+ (and derivatives)
Microsoft Internet Explorer 5.0+ (Windows)
Apple Safari 1.2+
Opera 8.0+

Download XConn

The JavaScript source code can be found here:
xconn-1.1.js — 3055 bytes — v1.1, Sep 2009

References

A few tech docs — besides the obvious google search:

Dynamic HTML and XML: The XMLHttpRequest Object (Apple Developer Connection)
Very Dynamic Web Interfaces (xml.com)
Ajax: A New Approach to Web Applications (adaptive path; this is the article that coined the name 'AJaX')
Using the XML HTTP Request object (Jibbering.com)
AJaX on Wikipedia

A few simular libraries (a search showed up numerous more):

libXmlRequest
SAJaX — Simple AJaX Toolkit
XHConn — A Simple XMLHTTP Interface Library

Discussions about AJaX:

Ajax, promise or hype? (ppk)
Ajaxian.com (a blog about AJaX)
Ajax Blog (another blog about AJaX)
AJaX Considered Harmful
XMLHttpRequest & Ajax Working Examples (fiftyfoureleven.com)

webtweakers.com