FbFriends is a jQuery plugin for picking Facebook friends from a dialog.
IOW:
<script type='text/javascript' src='http://code.jquery.com/jquery-1.8.0.min.js'></script>
<script type='text/javascript' src='http://connect.facebook.net/en_US/all.js'></script>
<script type='text/javascript' src='files/fbfriends.js'></script>
<link rel='stylesheet' type='text/css' href='files/fbFriends.css'/>
<!-- or similar -->
<script type='text/javascript' src='js/bootstrap.min.js'></script>
<link rel='stylesheet' type='text/css' href='css/bootstrap.min.css'/>
Put a div into a section of the DOM that we can create a dialog out of. In this example I'm using Bootstrap's Modal, though anything will do (see the BYOD section below).
<div class="modal hide" role="dialog">
<div class="modal-header">
<button class="close" data-dismiss="modal" type="button" aria-hidden="true">×</button>
<h3>Select a Friend</h3>
</div>
<div class="modal-body">
<!-- This is the important bit -->
<div id="basic"></div>
</div>
</div>
Then we call our plugin, passing functions to control the dialog and handle the user's section:
$("#basic").fbFriends({
whenDone: function(friends){ doSomethingWithArray(friends);},
shower: function(element){ element.parents(".modal").modal("show");},
hider: function(element){ element.parents(".modal").modal("hide");},
});
And here it is in action, with the JS above bound to a button, and with
the whenDone
callback set to show cool toaster things:
That's it! (Although I have styled the modal a bit.)
The whenDone callback takes an array of friend objects, which are passed directly back from the FB API. They might looks something like this:
[
{
first_name: "Bob",
last_name: "Dole",
id: "11111",
name: "Bob Dole",
picture: {
data: {
is_silhouette: false,
url: "http://someImageUrl"
}
}
}
]
Those are the fields that come back by default. If you want more info
about the friend(s), you can specify a list of fields in the
additionalFields
option, like so:
$("#something").fbFriends({
additionalFields: ["gender"],
afterDone: function(friends){ console.log(friends[0].gender);}
});
You should first try the fields out in the FB API Graph Explorer to see how if how it works (e.g. do you need to configure your app to ask for more permissions?).
FbFriends doesn't contain any functionality for creating a dialog. You just put the FbFriends root inside of your favorite Javascript-controlled dialog and pass FbFriends functions to open and close it. That way, you can use anything you want: Bootstrap's modal, JQueryUI dialog, even nothing at all. This allows FbFriends to be very flexible; you can control all the parameters of your dialog, theme it, etc.
For example, you could also easy jQuery UI with a default theme like this:
<div title="Select a friend">
<div id="jqueryui"></div>
</div>
$("#jqueryui").fbFriends({
whenDone: toast,
shower: function(element){ element.parent().dialog({ height: 400, width: 400 });},
hider: function(element){ element.parent().dialog("close");}
});
And here it is in action:
By default, FbFriends lets the user pick a single friend with a click
and then closes the dialog. But you can also allow them to check
multiple friends by passing the multiple: true
parameter. A few
options matter here:
$("#multi").fbFriends({
multiple: true,
whenDone: function(friends){//do something with the whole array of selected freinds},
friendChecked: function(friend){//optional, do something on check},
friendUnchecked: function(friend){//optional, do something on uncheck},
//normal dialog stuff
shower: function(element){ element.parents(".modal").modal("show");},
hider: function(element){ element.parents(".modal").modal("hide");},
});
We add a couple of buttons to our modal so that the user can tell us when they're done:
<div class="modal-footer">
<button class="btn" data-dismiss="modal" aria-hidden="true">Cancel</div>
<button id="multi-submit" class="btn btn-primary">Done</button>
</div>
We also need to provide bind the "Done" button so that it informs FbFriends that the user is done selecting people:
$("#multi-submit").done(function(){
$("#multi").fbFriends("submit");
});
Do it:
By default, FbFriends will open the dialog as soon as it's called. You
can override that by passing immediate: false
in the options. You can
later open the dialog with:
$(yourSelector).fbFriends("show");
You can also programmatically close it:
$(yourSelector).fbFriends("hide");
By default, FbDialog assumes you've already initialized the FB Javascript SDK and logged in the user. But if you don't need to use the FB SDK outside of showing FbFriends, you can have FbFriends do all the work for you. You'll need to pass it at least an FB appID:
$("#yourDiv").fbDialog({
//other options here
initialize: true,
login: true,
fb: {
appId: "your FB app ID",
//other optional settings
}
});
The entire fb
value gets passed to FB.init so use it however you need.
You can also decide whether you want FbFriends to try to log in the
user. By default, it will. Redundant logins are harmless but take some
extra time. You can make FbFriends assume the user is logged in by
specifying login: false
.
You can specify afterLogin
to get FB's successful response to
authentication by specifying the afterLogin
function. That's useful if
you need to capture the name and FB ID of the user.
initialize: true
implies login: true
but not vice-versa.
Here's the full set of options with defaults:
$("#yourDiv").fbDialog({
{
multiple: false, //select mutliple friends
whenDone: function(friends) { //callback when selection is done
return console.log(friends);
},
friendChecked: null, //in multiple mode, callback for when a friend is checked
friendUnchecked: null, //in multiple mode, callback for when a friend is unchecked
shower: function(element) {}, //how to show the dialog
hider: function(element) {}, //how to hide the dialog
immediate: true, //show the dialog imediately
initialize: false, //whether to handle the FB SDK initialization internally
login: true, //whether to log the user into FB if required
fb: { //options past to FB.init if initialize is true
appId: null,
channelUrl: null,
status: true,
cookie: true,
xfbml: false
},
afterLogin: null, //callback with the users info if login: true
additionalFields: [],
includeMe: false //add the current user to the list
});