Following on from the WordPress plugin I decided to take another look at the mess of javascript I wrote for that and make it a bit nicer. Also, it’s been a while since I did anything with jQuery plugins, so I decided to kill two birds with one stone and write a helper plugin for facebook. I’d never done anything with jQuery queues (required to ensure asynchronous methods work as expected) or plugins that work ‘correctly’ and include chaining capabilities, so this was a nice little project.
This plugin uses the javascript SDK (obviously!) and requires a facebook app_id, but that’s easy enough to get (see the wordpress plugin writeup for details of this process). It also requires the jQuery-cookie plugin by Klaus Hartl. Your page will need a ‘#fb-root’ div defined (required by the facebook API) and I suggest calling the methods on this div.
I’ve included an html page to demonstrate using the plugin to determine the current user’s name, and check whether they like a specific page (using the page id) but here’s a run down of some of the advanced features of this plugin:
Initialisation
You can choose to initialise the plugin directly or, if you call one of the other methods in the plugin it will auto-initialise if it hasn’t already. So you can do this (for example):
$('#fb-root').facebook('user',
{
success: userFunction,
app_id: '#########',
auto_auth: true,
scope: 'publish_stream'
}
);
and the helper will initialise, login to facebook (redirecting the user to the authorisation page if required, more about this later) and get the user object. A callback will be done to ‘userFunction(response)’ passing in the returned user object as a parameter. So you can get the user name using ‘response.name’.
Auto authorisation
Facebook requires a user to authorise an app before it can do anything. Usually this means some tedious code to detect the current status of your app, redirect to facebook for authorisation if required, then catch that process back at your app. If you set ‘auto_auth’ to true on a plugin call, this process is handled for you. The user will be redirected to facebook and then back to your app (or you can override the destination by passing in a url as the ‘unauthorised’ option) without you having to do anything. If you want to override this behaviour, pass a function in as the ‘unauthorised’ option, and leave ‘auto_auth’ as its default (false) option. No redirection will be done and you get a call back to your unauthorised function.
First authorised
Sometimes we want to do something when an app is authorised for the first time. For example in my wordpress plugin I want to post a promotional message on the user’s wall when the app is installed. the ‘firstauthorised’ callback allows you to do this. This does require cookie support to work, so if your user is blocking cookies unfortunately you won’t get this function firing.
Chaining
All the methods in theis plugin are chainable, so you can request lots of info from facebook in a single line of code (although behind the scenes, multiple api calls will be taking place)
Methods
Currently the plugin only supports 4 methods, but I plan to add more in future (hit me up in the comments if you’d like to see something added!)
init (default method):
Initialises the facebook API. takes the following parameters, only app_id is required.
- app_id (your facebook app id)
- status (a fb.init parameter, defaults to true)
- cookie (a fb.init parameter, defaults to true)
- xbfml (a fb.init parameter, defaults to true)
- scope (comma seperated list of permissions to ask for, see the fb api documentation for more details)
- authorised (callback function if the app is currently authorised, defaults to nothing, no parameters)
- unauthorised (callback function if the app is not currently authorised OR a url to redirect to if doing auto_auth, defaults to nothing, no parameters)
- firstauthorised (callback fucntion the first time the app is authorised, needs cookie support to work, defaults to nothing, no parameters)
- loggedout (callback if the user is currently logged out of facebook, defaults to nothing, no parameters)
- auto_auth (if ‘true’, the user will be automatically redirected to facebook to authenticate your app if they haven’t already done so)
user:
Returns the user object for the current user. As well as taking any of the ‘init’ parameters (for on the fly initialisation) this method has the following parameters (none is required, except the app_id if you haven’t previously initialised the plugin.
- success (a callback function called if the api call succeeds. passes the user object as a parameter)
- failure (a callback function called if the api call fails, passes the returned object as a parameter)
likespage:
Used to determine if a user likes a specific page. As well as taking any of the init parameters, this method has the following parameters of its own. Only pageid is required:
- success (callback on success, takes a boolean as a parameter, ‘true’ if the user likes the page, ‘false if not)
- failure (callback on failure, passes the returned object as a parameter)
- pageid (the id of the page to check if the user likes, no default)
postToWall
Posts a message on the user’s wall. As well as taking any of the init parameters, this can also take any of the options for the underlying api call, which you can find here:
None of these options have any defaults, so as a minimum you must pass in ‘message’, but you also have access to any and all of those options so you can post whatever you like.
This method also has the following callback options:
- success (called on a successful post, response object passed in as parameter)
- failure (called if the API call fails, response object passed as parameter)
You can download the plugin here: [wpdm_file id=6]