Coding Standards AJAX
This coding standards document is very incomplete!
At the present I intend it to cover mostly interface standards.
The JavaScript to PHP interface will be the first thing that I standardize here.
AJAX call Coding Standards
AJAX calls are generally made via one of two Jquery functions. The Jquery $.post() function is the preferred method and should be used whenever possible.
The $.post() Function
the following code uses the $.post() function to perform an AJAX call.
var dataString = 'email=' + email;
$.post("php/emailPlayerID.php", dataString, emailPlayerResult);
return false;
The AJAX call will be made to the emailPlayerID.php program and dataString will be passed to it. Note that dataString is a string variable formatted as a URL query string. The response from emailPlayerID.php will be processed by the callback function specified third parameter of the $.post function (emailPlayerResult() in the example above).
The $.getJSON() Function
If an AJAX called PHP program returns a JSON file then it may be called by
the Jquery $.getJSON() function as an alternative to the $.post() function.
Special error hadling capabilities are provided by this function. These may
modify the callback function processing that is described below.
Note that further documentation of these differences should eventually be included here.
Callback Function Coding Standards
Each time an AJAX call is made by a JavaScript program to a PHP program a callback function is required to process the return from the PHP program .
The first three lines of every callback function, except those in board18index.js, handle login timeout situations. These lines are always:
if (response.indexOf("<!doctype html>") !== -1) { // User has timed out.
window.location = "access-denied.html";
}
If the PHP program's auth.php code detects a timeout it will transfer control to the access-denied.html page. This has the result of sending the code for this page to the callback function. The first line of this code is <!doctype html>. The above three lines handle this situation.
Echo Status Return Type
Most AJAX called PHP programs use the echo command to return short text strings indicating the status of the return. Sometimes an extra short text field is concatenated to a particular such string. For example, the 'email' status return below has a player id concatenated to it.
Two status returns which should always be provided for are "success" and "fail". Most other status returns will be editing exceptions which should be reported back to the player so that he can try again.
This is an example of a valid callback function which handles this type of status return scheme. It was taken from board18index.js.
/*
* Function regResult is the callback function
* for the ajax newUser call.
*/
function regResult(response) {
if (response.indexOf("<!doctype html>") !== -1) { // User has timed out.
window.location = "access-denied.html";
}
if(response === 'success') {
$('#login #password').val('');
$('#login :text').val('');
$('#register form').slideUp(300);
$('#login form').slideDown(300);
var loginNote ='You have successfully registered. ';
$('#lognote').text(loginNote);
}
else if(response === 'duplicate') {
$("#newuser_error").text('Username is already in use.').show();
$("#newuser").focus();
}
else if(response === 'bademail') {
$("#email_error").text('Invalid email format, please correct.').show();
$("#email").focus();
}
else if(response.substring(0,5) === 'email') {
var logmessage = 'Player ' + response.substring(5);
logmessage += ' is already using this email address.';
$("#email_error").text(logmessage).show();
$("#email").focus();
}
else if(response === 'fail') {
var errmsg1 ='Program error in newUser.php.\n';
errmsg1 += response + 'Please contact the BOARD18 webmaster.';
alert(errmsg1);
}
else { // Something is definitly wrong in the code.
var errmsg2 ='Invalid return code from newUser.php.\n';
errmsg2 += response + 'Please contact the BOARD18 webmaster.';
alert(errmsg2);
}
}
JSON File Return Type
Some AJAX called PHP programs use the echo command to return a JSON string. These strings should be decoded using the jQuery.parseJSON() function. This function returns a javascript object. The PHP program will always include a status return in the object with a name like "stat". Thus, for example, the decoded object, resp, should have a sub object named "resp.stat" which can be treated exactly like the status return described in the above section. If resp.stat equals "success" then the rest of the JSON object can be processed by the callback function.