Http: A Caching XmlHttpRequest Wrapper

A wrapper for XmlHttpRequest that supports forced caching on FireFox and forced non-caching on IE.

XmlHttpRequest is a class available in client-side JavaScript for making new HTTP requests from within a page. It is implemented as a built-in object in Safari and FireFox, and as an ActiveX object on Internet Explorer.

An excellent reference for this object is available at Apple.

The Http class presented here provides a (hopefully) simpler interface to initiating a request with XmlHttpRequest.

API Reference

Functions

Http.get(params, callback_args)

Initiate an HTTP request with the given options.

params should be an object with the following key-values:

url

The URL to request. Required. Note that due to security restrictions, the URL must point to the same server as the current page. You cannot use XmlHttpRequest to retrieve results from external servers directly.

cache

The caching mode to use for this request. Defaults to Cache.Get.

method

The HTTP method to use for this request. Defaults to Method.Get. Note that some XmlHttpRequest implementations do not support the full range of HTTP verbs, usually only supporting GET and POST.

callback

A function to call when the request is complete. Optional. Currently, the callback is only called when the readystate reaches ReadyState.Complete; this wrapper does not support progressive notification. The callback will be called whether or not the completed request was sucessful.

The callback should have the form function(response, [arg1, arg2, ...]). response is XmlHttpRequest object that completed the request object. Subsequent arguments are taken from the callback_args passed to Http.get.

callback_args is an array of arguments which will be passed to the callback function.

Http.from_cache(params, callback_args)

Do a request, but only pull results if they have already been cached locally.

Http.is_cached(url)

Returns true if the given url has already been requested and cached.

Http.clear_cache()

Clears the cache.

json_response(response)

Parse the response text as JavaScript (using eval()), and return the resulting object.

getResponseProps(response[, header])

Parse a response header as JavaScript (using eval()), and return the resulting object. If omitted, the header defaults to "X-Ajax-Props". This allows the server to return arbitrary text in the response, and a coded response in a header.

Caching Options

Http.Cache.Get

Perform a normal request, and do not add the result to the local cache. Note: on IE, requesting the same URL via GET multiple times will cause IE to cache the result internally.

Http.Cache.GetCache

Perform a request and cache the result if sucessful. If the requested URL's response is already cached locally, do not perform the server request.

Http.Cache.GetNoCache

Perform a request and add a time-based variable to the querystring to force IE not to cache the result. The result is not placed in the local cache.

Http.Cache.FromCache

If the requested URL's response has already been cached, call the supplied callback on the locally cached version. Http.get will return true or false based on whether or not the response is in the cache.

Request Methods

Possible request methods are the HTTP verbs, or possibly any arbitrary verb if your underlying XmlHttpRequest implementation allows it.

Demo

A page which shows Cache.Get vs. Cache.GetNoCache: time.html.

Firefox and Safari should retreive new times with either button. IE 6 will only retreive new times with the no-cache button.

Versions

• 1.2.2: Added is_cached and clear_cache. Updated time demo.
• 1.2.1: Fixed errors when using Http.Cache.GetCache. Results should now be cached, and callbacks should be called correctly for cached results. (Thanks to Daniel Rinehart.)
• 1.2: Now instrumented for flangelib logging. No-cache parameter now uses time in milliseconds instead of full human-readable date. Moved constants into the Http namespace.
• 1.0: New API; incompatible with previous versions.
• 0.9.2.2: Tweaked the no-cache parameter.
• 0.9.2.1: GetNoCache now uses unique URL parameter instead of request headers (which didn't work.)
• 0.9.2: Added "GetNoCache" function.
• 0.9.1: Added named constants for some HTTP response codes.

Sightings

• dev.aol.com: Log4Ajax
• webmonkey: Nitty Gritty Ajax
• A previous version of this code (0.9.2.2) was used in "AJAX for ASP.NET" by Steven A Bristol.

Contact Information

• Email: