Although one can easily find voluminous tomes on the intricacies of the AJAX protocol, the primary task addressed by AJAX is laughably simple:
Send a message to a web server and deal with the server's response.
This blog post identifies compatible client and server routines,
rsInitAjax, whose simplicity of use approximates that of the task at hand.
A total of four parameters are required on the client side:
data – the message to the server,
url – address of the server script that interprets the message,
response – the server's response to the message,
There are a few unavoidable details on how these are structured:
- Without sacrificing anything important, we may assume that the data and response parameters are JSON objects that will be flattened to character strings during transmission to and from the server.
- Execution of the rsAjax routine is suspended while awaiting a response from the server. An optional Boolean async parameter allows execution to continue while the AJAX request is being processed.
- If a protocol error occurs, a detailed error message is displayed via an alert. An optional error parameter for a second callback function can be used to override this default.
- If an error is generated while executing the script, an error message is returned. In a PHP script, the message content is controlled via the PHP set_error_handler function.
- If the server script itself detects an error, it is not willy-nilly mixed in with normal return data for the client to sort through, but instead is returned in a response object, which, in this case, may contain the following fields:
data – data generated by the server script,
error – true, if an error was generated,
errorMessage – an optional error message indicating what went wrong.
Due to an implementation decision explained below, the components of the client-side
data object will arrive at the server script as components of the PHP $_POST variable.
The server-side response is stored in a global PHP variable,
$_RESPONSE. As is customary in PHP implementations of JSON, we use associative arrays to implement JSON objects, not PHP objects. On the server,
$_RESPONSE has the following form:
$_RESPONSE = array(
'data' => HTML or other response data output by the script,
'error' => error flag,
'errorMessage' => error message if needed,
additional user defined fields if needed
The client-side code for
rsAjax is essentially found already in jQuery, it's just a matter of sifting through the available 49 parameters and methods for jQuery.ajax. (I tried implementing rsAjax from first principles as spelled out in Thomas Powell's voluminous Ajax: The Complete Reference but got an implementation that worked only on toy test examples.)
The implementation relies exclusively on AJAX post requests, as these are uniformly superior to AJAX get requests from the standpoint of simplicity. Unlike get requests, post requests avoid issues of URL encodings, and they aren't limited in size. People sometimes claim that get requests are good because they rely on URLs which are bookmarkable, but no, URLs are only bookmarkable if placed in the browser's address bar, which is not where AJAX puts them!
On the server, we have a problem. PHP scripts normally mix PHP statements with HTML code, with the result being implicitly delivered to the client after the PHP statements have been executed, and without being explicitly saved first in a variable such as
$_RESPONSE. If we are to directly accommodate such PHP-HTML mixtures, we will be returning HTML rather than JSON to the client, and error data will be mixed with normal message data. Happily, PHP offers a way of collecting accumulated script output via its
ob_start function. This function even offers a callback mechanism by which we may specify the processing that will happen after the script is run, allowing us to collect all AJAX related code into one place at the beginning of the script.
The rsAjax implementation and related demo files may be downloaded as rsAjax.zip.
A Simple Demo
Here is a demo of rsAjax that uses the rsAjax interface to send a message to the server and get a return message back. After trying the demo, take a look at the code that makes it happen. On the client side, the rsAjax interface is called with three of the necessary parameters, and the fourth parameter comes along when the callback function, showResponse, is invoked. This callback looks to see if there was an error and updates the webpage accordingly.
On the server side, the code is simpler. The message arrives as $_POST['msg'] and is inspected for error. If all is well, a return message is sent back via template instantiation.