Facebook Cookbook - Jay Goldman [107]
requireLogin
A boolean attribute you can set on your Ajax object to indicate that the user has to log into Facebook before the Ajax call can be made. This is particularly useful if you’re using a public Canvas page but need access to the user’s Facebook account information in order to calculate the return value of your Ajax method.
abort
Some quick testing shows that the Facebook Platform Ajax object has a default timeout of about 10 seconds, which you can’t adjust. If you think you might need to bail out sooner (or need to kill an in-progress request for any number of other reasons), call the myAjax.abort() method.
responseType
This is covered in the earlier example (we’re using Ajax.JSON), but you have the choice of three values:
Ajax.JSON
Your server will return a response encoded using JavaScript Object Notation (JSON), which will automatically be decoded for you. Any attributes you encode on the server side will become attributes of the data object, which you can then access using dot-notation (e.g., if you send back an attribute called available, you can access it using data.available). Generally speaking, this is the preferred approach because it keeps a proper separation between your data and display layers, meaning that the return from the server contains no formatting codes, and therefore isn’t tied to Facebook Platform (for example, you could call the same server-side function from a mobile version of your app and then parse and display the result using something like XHTML Mobile Profile). For more information on JSON, see http://json.org.
Ajax.FBML
Your server’s going to do all the calculations and formatting of the result and return it in FBML, all ready to display. You can pass this directly into the setInnerFBML() function. This approach means less client-side processing (since you can just dump the result straight to screen), but it also means that you’re tying your data and display layers very tightly together, and you might not be able to use the same server-side function in non-Facebook environments.
Ajax.RAW
Your server will return raw data that you’ll deal with client-side on your own. You might use this if you have an existing server-side function that returns something like XML and have an XML parser implemented in FBJS separately.
post
There’s no real magic in the post method, but it is worth noting that the earlier example uses the simpler form and passes the variables as a GET request. Since we were passing only one variable, we just used the JavaScript escape() function to handle the URL encoding, in case someone enters a username with funny characters in it. Sometimes you’ll need to pass a whole whack of variables to the server, which is happily accommodated by passing an array of variables instead:
var queryParams = {'username': username, 'firstName': firstName};
myAjax.post('http://www.yourserver.com/process.php', queryParams);
The FBJS parser will automatically encode all of the values so that you don’t have to worry about them. It’s important to note that this will change your request from a GET to a POST, so if you’re looking for these variables on the server side and you’re writing PHP, make sure to look in $_POST instead of in $_GET.
In keeping with the Facebook design methodology evident in apps such as Photos, this framework isn’t intended to provide the kind of overwhelmingly complete feature set you’d find in libraries such as jQuery, Prototype, or Dojo (to name a few). You’re not likely to need a whole lot more than is listed here for the simple interactions that most Facebook apps exhibit, and you might even find this overkill, in which case take a look at Dialogs with Ajax.
Displaying Pop-Up Dialogs
Problem
I want to display a pop-up dialog in the style seen throughout Facebook (well, I really want to display an alert but I’m not allowed to in FBJS, so I’ll settle for this).
Solution
Facebook Platform provides a very simple implementation