Really Simple AJAX
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
This blog post identifies compatible client and server routines,
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
url - address of the server script that
interprets the message,
response - the server's response
to the message,
interprets the server response, if AJAX succeeds.
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
- 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.
- The response field is implemented
as a parameter to a success callback
- 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
errorMessage - an optional error message indicating what went wrong.
Due to an implementation decision explained below, the components of the client-side
object will arrive at the server script
as components of the PHP $_POST variable.
The server-side response is stored in a global PHP
$_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
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