Ajax : Manual

AJAX - Javascript Function Library

AJAX : Overview | Reference | Quick Start | Examples | Download

Arrays : Overview | Reference | Download

The function library presents a basic function which you call with a pointer to a callback. In the simplest model your callback would take the text returned from the server and probably use InnerHtml to insert it into the HTML DOM.

Creating a callback

The first thing you need is a callback function, this will be automatically called from the library when your response comes back from the server, every callback function should expect the same input variables:

function myCallBack( responseString , statusCode , requestObject )
{
	//...
}

Making the request

Now that you have your callback function you can make a request:

myRequestObj = ajax_RequestString( myCallBack , "myAjax.php" , "ID=123" , "" );

The function will return the new request object or null depending on if it succesfully created the request. If you are only concerned with the text your callback receives you don't even need to assign myRequestObject.

Basic Example

Here is an example of a simple request and response utilising the userObject.

<script>
function go()
{
	//make a GET request to myscript.php
	ajax_RequestString( myCallBack , "myscript.php" , "" , "The request failed" )
}

function myCallBack( responseString , statusCode , requestObject )
{
	if( statusCode == ajax_status_ok )
	{
		alert( responseString );
	}
	else
	{
		//our userObject is an error message
		alert( requestObject.userObject );
	}
}

</script>
<input type="button" onclick="go()" value="Make Request">

In this example the userObject is the error message but it could be anything, e.g. the ID of a DIV to insert the contents into. Also note the statusCode enumerator, explained next...

Status Codes

The status codes are enumerated to make things simpler and reflect somewhat the HTTP codes. This library uses them to identify the nature of your server script's response as the server's HTTP response code will always return 200 if any data is served.

When returning data from the server the first line should be your status code (actually the first three ascii chars followed by any other char, though usually a newline) so a response could look like this.

200
Hot and sunny.

When a string request sees an "ok" status code it strips it and returns the rest of the string ("Hot and sunny.") it will also do so for any status code from 600 to 999, which you can use in your own scripts to mean whatever you like. A status code of 500 is set by the library if any other response is found, so

Hot and sunny.

Will return a NULL string and a statusCode of 500, as will

500
Error

This means that if an HTTP or network error occurs preventing a proper response your script will not get garbled results, the library will look for a status code and probably see the first three chars of "<html>" being the beginning of a 501 or 404 error page. When debugging your scripts you can still delve into the native HTTPRequest object to get to the actual HTTP code if you desire.

Custom Error Codes can be used to signal to your script differing outcomes when you don't want it to be hardcoded into your script:

601
Weather service currently offline.

your callback could then look like this.