Retrieving Data via Ajax

Problem

I want to do a call and/or response to my server without causing the current page to refresh. For example, I might want to dynamically populate some content, or update a section of my page, or maybe check to see whether some text entered into a field is valid.

Solution

Ajax can be used for such a wide variety of uses that it would require a whole other book to run down all the various permutations and combinations (conveniently, you can pick up any number of O’Reilly books on the topic, including Understanding AJAX: Using JavaScript to Create Rich Internet Applications and Ajax for Web Developers). As a simple example, we’re going to use a text field in which users would enter the username they’d like to use, and then we’ll check on the fly to see whether it’s available. You’ll need a text input on your Canvas page:

The JavaScript for checkUsername() is surprisingly simple because of the Ajax object provided by Facebook Platform, which really makes your life easy:

function checkUsername(usernameField){

if(usernameField.getValue() == ''){

document.getElementById('usernameAvailable').setTextValue('');

return;

}

var encodedUsername = escape(usernameField.getValue());

var checkUsername = new Ajax();

checkUsername.responseType = Ajax.JSON;

checkUsername.ondone = function(data){

var message = '';

console.log(data);

if(data.available){

message = 'Great! That username is available!';

}else{

message = 'Ooops! That username is taken. Sorry!';

}

document.getElementById('usernameAvailable').setTextValue(message);

}

checkUsername.post('http://www.yourserver.com/checkUsername.php?

username=' + encodedUsername);

}

Finally, you’re going to need to create a page on your server (or a servlet, depending on your server-side language of choice) that the Ajax script in your Canvas page can call to send data to and/or receive data from. Since this is just a simple example, the checkUsername.php file on our server contains:

if($_GET['username'] == 'jay'){

echo '{"available": true}';

}else{

echo '{"available": false}';

} ?>

WARNING

Your Ajax call will fail if you try to use a Facebook URL as the callback. It’s very important that the script call a URL that is not on Facebook, but it could still sit on the same server that your app is served from.

That should really be it! If you’re following along at home and have recreated the code just shown, you can now try entering a username in the field. As soon as the field loses focus, the onchange event will fire and cause the checkUsername() JavaScript function to execute, which will prepare and fire off an Ajax request to your server and then parse the JSON-formatted response and update the contents of the usernameAvailable .

Discussion

Even though the solution presented here is one of the simplest cases, it provides a pretty flexible foundation for building more complicated Ajax calls. You would use an almost identical function if you just wanted to update data on your server (e.g., moving the pieces in a chess game might call a chessMove.php page and pass it player and move, and then parse a result value and update the displayed board on the Canvas page). You could also use a similar function and a call to setTimeout() to create a rotating banner ad system that doesn’t need to refresh the page when changing ads.

The Ajax implementation in Facebook Platform provides a good deal more functionality than we’ve covered, including:

onerror

An error handler function that