In this document:
The Facebook SDK for iOS provides prebuilt UI components, including the FBFriendPickerViewController
class that can be used to pick friends.
You can add the friend picker programmatically or graphically.
You can create a friend picker with the following code in your view controller class:
// Initialize the friend picker
FBFriendPickerViewController *friendPickerController =
[[FBFriendPickerViewController alloc] init];
// Set the friend picker title
friendPickerController.title = @"Pick Friends";
// TODO: Set up the delegate to handle picker callbacks, ex: Done/Cancel button
// Load the friend data
[friendPickerController loadData];
// Show the picker modally
[friendPickerController presentModallyFromViewController:self animated:YES handler:nil];
This code initializes the friend picker with a title, triggers the data fetch and then presents the friend picker modally. You can also display the friend picker by pushing it onto a UINavigationController
:
...
[self.navigationController pushViewController:friendPickerController
animated:YES];
You can add the friend picker graphically using the iOS Interface Builder. Do this by using a nib or a storyboard.
Nib setup
To add the friend picker through a nib file, create a new class that is a subclass of FBFriendPickerViewController
. When creating the class, select the ''With XIB for user interface'' option:
Next, open your new implementation class and add code to load the friend picker when the view is loaded:
- (void)viewDidLoad
{
[super viewDidLoad];
// Load the friend data
[self loadData];
}
You can then display your friend picker from another view controller by presenting it modally or pushing it onto a UINavigationController
.
Modally:
FPViewController *friendPickerController =
[[FPViewController alloc] initWithNibName:@"FPViewController"
bundle:nil];
[friendPickerController presentModallyFromViewController:self
animated:YES
handler:nil];
}
Pushing onto a UINavigationController
:
FPViewController *friendPickerController =
[[FPViewController alloc] initWithNibName:@"FPViewController"
bundle:nil];
[self.navigationController pushViewController:friendPickerController
animated:YES];
Creating the friend picker through a nib file lets you play with the layout of the picker. For example, let's say you don't want the friend list display to take over the whole screen, like this:
You accomplish this by making the following changes to your nib:
Table View
object to the layout.tableView
outlet and connect it to your newly created table view.Label
object to the layout and set the text to ''My Friends''After your changes, your layout should look like this:
Storyboard setup
You can make changes to a view controller you've set up inside a storyboard scene. To add the friend picker UI control:
View Controller
object in your layout.FBFriendPickerViewController
After your changes, your layout should look like this:
After setting up your layout, add code to configure the friend picker. The following code shows how you can do this assuming you've defined a segue named ''SegueToFriendPicker'' for the transition to the friend picker:
- (void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
if ([segue.identifier isEqualToString:@"SegueToFriendPicker"]) {
// For storyboard, get the destination view controller which
// is the friend picker view controller
FBFriendPickerViewController *friendPickerController =
(FBFriendPickerViewController *) segue.destinationViewController;
// Set the friend picker title
friendPickerController.title = @"Pick Friends";
// TODO: Set up the delegate to handle picker callbacks, ex: Done/Cancel button
// Load the friend data
[friendPickerController loadData];
}
}
You should then make the following change to the code that's invoked when your app launches. The changes make sure that the FBFriendPickerViewController
class is loaded before the view is shown:
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
// Override point for customization after application launch.
[FBFriendPickerViewController class];
...
return YES;
}
Note: If you've added the -ObjC
flag to your linker options, then you don't have to add this code. Adding that flag causes the linker to load all objects in the Facebook SDK including the FBFriendPickerViewController
class.
There are various events your app may need to handle when you use the friend picker.
During data fetch:
When the picker is displayed:
All these events can be handled by defining a class that conforms to the FBFriendPickerDelegate
protocol and implementing the methods you're interested in.
First, add the protocol to the class you wish to handle the delegate callbacks:
@interface ViewController() <FBFriendPickerDelegate>
...
@end
Next, set up the delegate when configuring the friend picker.
If you set up your friend picker using a nib, you can set the delegate in the view controller's initialization method:
- (id)initWithNibName:(NSString *)nibNameOrNil
bundle:(NSBundle *)nibBundleOrNil
{
self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
if (self) {
// Set up the delegate
self.delegate = self;
...
}
return self;
}
If you set up your friend picker using a storyboard or programmatically, set the delegate before loading the picker data:
...
// Set up the delegate
friendPickerController.delegate = self;
// Load the friend data
[friendPickerController loadData];
...
Once the delegate is set up, implement the desired delegate methods. Example implementations are shown below:
/*
* Event: Error during data fetch
*/
- (void)friendPickerViewController:(FBFriendPickerViewController *)friendPicker
handleError:(NSError *)error
{
NSLog(@"Error during data fetch.");
}
/*
* Event: Data loaded
*/
- (void)friendPickerViewControllerDataDidChange:(FBFriendPickerViewController *)friendPicker
{
NSLog(@"Friend data loaded.");
}
/*
* Event: Decide if a given user should be displayed
*/
- (BOOL)friendPickerViewController:(FBFriendPickerViewController *)friendPicker
shouldIncludeUser:(id <FBGraphUser>)user
{
// Filtering example: only show users who have
// "ch" in their names
NSRange result = [user.name rangeOfString:@"ch"
options:NSCaseInsensitiveSearch];
if (result.location != NSNotFound) {
return YES;
} else {
return NO;
}
}
/*
* Event: Selection changed
*/
- (void)friendPickerViewControllerSelectionDidChange:
(FBFriendPickerViewController *)friendPicker
{
NSLog(@"Current friend selections: %@", friendPicker.selection);
}
/*
* Event: Done button clicked
*/
- (void)facebookViewControllerDoneWasPressed:(id)sender {
FBFriendPickerViewController *friendPickerController =
(FBFriendPickerViewController*)sender;
NSLog(@"Selected friends: %@", friendPickerController.selection);
// Dismiss the friend picker
[[sender presentingViewController] dismissModalViewControllerAnimated:YES];
}
/*
* Event: Cancel button clicked
*/
- (void)facebookViewControllerCancelWasPressed:(id)sender {
NSLog(@"Canceled");
// Dismiss the friend picker
[[sender presentingViewController] dismissModalViewControllerAnimated:YES];
}
The button click events can also be handled if you display the friend picker using the following method:
presentModallyFromViewController:animated:handler:
The block you provide to the handler
parameter is called when a person taps the done or cancel buttons, letting you to respond to those events. The code below shows an example of using the block:
[friendPickerController presentModallyFromViewController:self
animated:YES
handler:
^(FBViewController *sender, BOOL donePressed) {
if(donePressed) {
NSLog(@"Selected friends: %@", friendPickerController.selection);
}
}];
The default friend picker is displayed in the following way:
You can customize these default display features by configuring the relevant properties of FBFriendPickerViewController
:
// Initialize the friend picker
FBFriendPickerViewController *friendPickerController =
[[FBFriendPickerViewController alloc] init];
// Allow the selection of only one friend
friendPickerController.allowsMultipleSelection = NO;
// Hide the friend profile pictures
friendPickerController.itemPicturesEnabled = NO;
// Configure how friends are sorted in the display.
// Sort friends by their last names.
friendPickerController.sortOrdering = FBFriendSortByLastName;
// Configure how each friend's name is displayed.
// Display the last name first.
friendPickerController.displayOrdering = FBFriendDisplayByLastName;
// Hide the done button
friendPickerController.doneButton = nil;
...
// Hide the cancel button
friendPickerController.cancelButton = nil;
You can also show the friend list for a friend of the person who's logged in:
// Initialize the friend picker
FBFriendPickerViewController *friendPickerController =
[[FBFriendPickerViewController alloc] init];
// Get friend's list from one of user's friends.
// Hard-coded for now.
friendPickerController.userID = @"100003086810435";
...
Note: The friend list for the friend may not show up if that friend has turned all Facebook apps off.
If you need further customizations, such as changing the friend picker colors or adding more friend info to the display, consider building your own picker.
By default, friend data is fetched from the server when the loadData
method is called on an FBFriendPickerViewController
instance. While data is being fetched, any previously cached data is used is initially displayed in the picker. The fresh copy is then displayed once it is available.
You can pre-fetch and cache friend data before you need to display it. You do this by making use of a FBCacheDescriptor
object that represents the friend data you wish to fetch. Once you've created the cache descriptor object you can call the prefetchAndCacheForSession:
method on the object to fetch and cache the friend data. The example below shows how to do this when the view loads:
- (void)viewDidLoad {
[super viewDidLoad];
// Create a cache descriptor based on the default friend picker data fetch settings
FBCacheDescriptor *cacheDescriptor = [FBFriendPickerViewController cacheDescriptor];
// Pre-fetch and cache friend data
[cacheDescriptor prefetchAndCacheForSession:FBSession.activeSession];
}
The example above caches data based on the default friend picker data fetch settings. By default, the following friend data is returned in the results: id
, name
, first_name
, middle_name
, last_name
and picture
. You can pre-fetch additional info by calling the cacheDescriptorWithUserID:fieldsForRequest:
class method instead of cacheDescriptor
and passing in the additional info you wish to get. The example below sets up a fetch for birthday
and location
data as well:
// Set up the additional fields needed
NSSet *extraFieldsForFriendRequest = [NSSet setWithObjects:@"birthday", @"location", nil];
// Create a cache descriptor for the additional fields needed
FBCacheDescriptor *cacheDescriptor = [FBFriendPickerViewController
cacheDescriptorWithUserID:nil
fieldsForRequest:extraFieldsForFriendRequest];
// Pre-fetch and cache friend data
[cacheDescriptor prefetchAndCacheForSession:FBSession.activeSession];
For more information about adding friend picker to your iOS apps, see the following.
Find these in the download folder for the Facebook SDK for iOS.
FBFriendPickerViewController
.FBFriendPickerViewController
.FBFriendPickerViewController
. FBFriendPickerViewController
.