Requirements

jQuery 1.6.2 or above
Facebook Javascript SDK integration

How to use

Note: The following statements don't include Facebook integration. As the basics of the application depend on Facebook API, we assume that you do the Facebook integration.

We seperate the Facebook stage not to interfere with the Facebook applications you own that are already online. If you haven't already done the Facebook integration, you can see Facebook Javascript SDK page or go check this example's source.

1. Include Necessary Files

Add these lines into your web site's <head> part or depending on the difference of usage, up on the </body> tag.

Loading jQuery from CDN (Content Delivery Network) is recommended

<!-- Add Facebook Friend Selector CSS -->
<link type="text/css" href="/friend-selector/jquery.friend.selector-1.2.1.css" rel="stylesheet" />

<!-- Add jQuery library -->
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>

<!-- Add Facebook Friend Selector JS -->
<script type="text/javascript" src="/friend-selector/jquery.friend.selector-1.2.1.js"></script>

2. Insert the following code into <body> tag

This is the code block where you define the action for friend selector box. You can replace "bt-fs-dialog" name with anything you want. You have to change the class name in Step 3 with the same name.

See the Options and Events tabs for more options

<script type="text/javascript">
  jQuery(document).ready(function($) {
    $(".bt-fs-dialog").fSelector({
      onSubmit: function(response){
        // example response usage
        alert(response);
      }
    });
  });
</script>

3. Add the following code to your page's <body>

This code can be a button, image or a link. It would be adequate to add "bt-fs-dialog" to the class property definition.

<a href="javascript:{}" class="bt-fs-dialog">Click here</a>

If all of your definitions are correct, you can see the friend selector box when clicked on the example links.

Click here for basic example

Options

Option Description Possible values Default value
max Maximum number of friends that can be choosen. Any integer null
excludeIds Facebook IDs of the people who are excluded from the list. These IDs must be seperated by commas. [987945454741, 321321654654, 98987654654] []
getStoredFriends Facebook IDs of the people who are predefined. These IDs must be seperated by commas. [987945454741, 321321654654, 98987654654] []
closeOverlayClick Specifies if the box will close or not when overlay is clicked. Boolean true
enableEscapeButton Specifies if the box will close or not when Esc button is pressed. Boolean true
overlayColor Specifies the overlay color. Hexadecimal value or color name #000
overlayOpacity Specifies the transparancy value of the box. 0 to 1 0.3
closeOnSubmit Specifies if the box will be closed or not on submit. Boolean false
showSelectedCount Specifies if the selected people number will be shown in the box or not. Max value must be more than zero for this property to work. Boolean false
showButtonSelectAll Specifies if the select all button will be shown or not. Boolean true
addUserGroups Adds user groups to the list. If Facebook invitation is true this option will automatically false due to invitation restriction. Boolean false
color Defines the color of the box. default, dark, light-blue, blue, green, red, pink default
lang.title Defines the title of the box. - Friend Selector
lang.buttonSubmit Defines the name of submit button. - Send
lang.buttonCancel Defines the name of cancel button. - Cancel
lang.buttonSelectAll Defines the name of select all button. - Select All
lang.buttonDeselectAll Defines the name of deselect all button. - Deselect All
lang.buttonShowSelected Defines the name of show selected button. - Show Selected
lang.buttonShowAll Defines the name of show all button. - Show All
lang.summaryBoxResult Summary text for the search result. - {1} best results for {0}
lang.summaryBoxNoResult Text when the search result is empty. - No results for {0}
lang.searchText First message text shown on the search box. - Enter a friend's name
lang.fbConnectError Text when there is a problem about Facebook connection. - You must connect to Facebook to see this.
lang.selectedCountResult Text to show checked people count. - You have choosen {0} people.
lang.selectedLimitResult Text when choice limit is reached. - Limit is {0} people.
lang.facebookInviteMessage Facebook invite message. - Invite message
maxFriendsCount Maximum number of friends on list. Any integer null
showRandom Shows friends in random order. Boolean false
facebookInvite Facebook invite onsubmit. Boolean false

Events

Event Description Possible values Default value
onStart Runs when the box is opened. function(response){} null
onClose Runs when the box is closed. function(response){} null
onSubmit Runs when submit button clicked. function(response){} null

Examples

First you must connect to Facebook.

Connect

Features

  • Ability to set a maximum number for friend selection
  • Exclude as many people as you want from the list
  • Ability to show random friends list
  • Ability to set maximum friends on list
  • Search
  • Facebook invite option (sends apprequest)
  • Ability to select/deselect all friends
  • Ability to show selected friends
  • Ability to predefine selected friends
  • Ability to add user groups
  • Overlay color selection
  • Overlay opacity selection
  • Ability to hide the overlay with a mouse click outside the box or a ESC key press
  • Centers the box on window resize
  • Ability to close the box onsubmit
  • Ability to enable or disable to display the number of selected people in the box
  • Seven color options (easily customizable)
  • Adaptability of texts to any desired language
  • Ability to decide what to do onstart
  • Ability to decide what to do onclose
  • Easy integration

Frequently Asked Questions

Q: What is Facebook Friend Selector and what can it do for you?
A: It’s a friend selection assistant for your Facebook application or your website that is equipped with Facebook Connect.

Q: It seems to be a Facebook tool, is it so?
A: It has its Facebook user interface, but is not a Facebook tool.

Q: There are already two different friend selectors on Facebook.
A: Yes, there are. But Facebook’s present tools, after selecting friends, send invitations or similar notifications to the selected people even if we do not wish to. For example, AppRequests, a Facebook method, sends an application request to the people you select. But this tool returns you your friends ID’s only and you use them as you please.

Q: Is its integration easy? Do I need any documentation?
A: There are documents among the files provided. If you follow the steps given in this document, you will not have any problem.

Q: Do I need any server-side script?
A: You do not need any server-side script. You’ll only work with JavaScript as client-side.

Q: Do I have to build a Facebook application?
A: Yes, you have to have an application on Facebook.

Q: Will it mess up my website or application design?
A: Because this tool opens as a modal box, it does not alter your design.

Changelog

2013/07/23 - v.1.2.1

  • Adding user groups to the list is added related to issue #1. But it has a condition. If Facebook invitation is true this option will automatically false due to invitation restriction.
  • Bugfix #3. Thanks to @poliver

2012/08/13 - v.1.2

  • Added - Predefine selected friends
  • Added - Select/deselect all friends
  • Added - Show selected friends
  • Added - Enable/disable option for close with ESC press
  • Performance improvements
  • Facebook invite message redefined under lang property

2012/01/17 - v.1.1

  • Added - Facebook invite onsubmit
  • Added - Maximum friend count on friend list
  • Added - Random friends list

2011/12/11 - v.1.0

  • First release