Fan Box
From Facebook Developer Wiki
The Fan Box is a social widget that allows Facebook Page owners to attract and gain Facebook fans from their own website.
The Fan Box lets users:
- See how many users are already fans, and see some of their friends who are
- Read recent posts from the Page
- Become a fan with 1-click without needing to visit the Page
Contents |
What Do I Need to Know?
Before you add a Fan Box to your website, you need the following:
- A website, and the ability to modify files on your website
- A Facebook Page that promotes your website (you must be an admin of the Page)
- A basic understanding of HTML, so you can edit the pages on your website where you want to place the Fan Box
Adding a Fan Box to Your Site
The Fan Box is based on the fb:fan tag.
The easiest way to add the Fan Box to your site is to use the Add a Connect Widget wizard, which you reach in one of three ways:
- Under your Page's profile picture, click the Add Fan Box to your site link.
- Under your Page's profile picture, click the Edit Page link, then click the Add Fan Box to your site link under Promote Your Page.
- Following this URL to the wizard: http://www.facebook.com/facebook-widgets/fanbox.php then selecting the Page from the Make a Fan Box for this page list at the top of the wizard.
The Fan Box wizard appears.
Use the check boxes on the wizard to specify which elements of the Fan Box you want to show.
- Checking the Include stream check box displays your Page's stream on your site. The stream updates each time the Page loads.
- Checking the Include fans check box displays a certain number of your Page's fans. You can change this setting, as described below.
Next, choose where you want to put the Fan Box. If you have a Blogger or TypePad blog, click the appropriate button to add the Fan Box to your blog. Follow the steps on the Blogger or TypePad page.
If you're adding the Fan Box to any other kind of website, click the Other button. The wizard automatically generates the JavaScript code you need to easily add the Fan Box to your site. The wizard creates a Facebook application and corresponding API key. If you already have an API key from your Facebook Connect site or another Facebook social widget like the Comments Box or the Live Stream Box), you must replace the auto-generated key with that API key.
The JavaScript code the wizard generates looks similar to this:
Copy this code to any page on your site where you want to display a Fan Box.
Important: If you want to place a Fan Box on a page on your site that already references Facebook Connect (that is, the page contains one script that calls FeatureLoader.js.php and another that calls FB.init), then you must not reference these scripts again. You simply can just put in the fb:fan tag where you want the Fan Box to appear. As in:
Using the Fan Box with SSL
If you need to render the Fan Box on a secure page over SSL, simply change how you reference the FeatureLoader script. Reference the script this way:
Customizing the Fan Box
The Fan Box gets rendered by the fb:fan XFBML tag. You can customize the Fan Box by changing the defaults for the following attributes in the fb:fan tag:
- profile_id: The ID of the Page associated with the Fan Box. Specify either the profile_id or the name, but not both.
- name: The Page's name (the name after the final backslash) or username (if one was specified). Specify either the profile_id or the name, but not both.
- stream: Set to 1 to display stream stories in the Fan Box or 0 to hide stream stories. (Default value is 1.)
- connections: The number of fans to display in the Fan Box. Specifying 0 hides the list of fans in the Fan Box. You cannot display more than 100 fans. (Default value is 10 connections.)
- width: The width of the Fan Box in pixels. The Fan Box must be at least 200 pixels wide at minimum. (Default value is 300 pixels.)
- height: The height of the Fan Box in pixels. The height defaults based on the elements you include in the Fan Box. For a Fan Box that contains only the Become a Fan button, but no stream or friends, the height is 64 pixels. If you include all the features, the Fan Box is 554 pixels high. If you change the number of connections shown, you may need to edit the height to ensure they are all visible.
- css: The URL to your own style sheet. See fb:fan for policies on using your own CSS.
Using an IFrame instead of JavaScript
We highly recommend Using JavaScript to add a Fan Box, as it allows your site to add more social widgets (other Fan Boxes or Live Stream Boxes) easily in the future.
If you are unable to use this method for some reason, you can use add a Fan Box using an HTML iframe tag, like this:
You need to specify your Page ID in the iframe src attribute You also must specify the URL to your Page in the anchor tag in the div.
You can choose to hide the stream from the Fan Box by changing 1 to 0 in the stream URL parameter.
You can modify the number of fans to display by changing the setting for the connections URL parameter. Setting connections to 0 hides your fans. You cannot specify more than 100 fans.
You can reference a style sheet by passing css, a URL-encoded GET parameter, to the iframe src. Your style sheet can modify the Fan Box's colors and fonts, but it cannot delete, obscure or modify:
- Your Page title and icon
- The Become a Fan button
- The order of the elements (button, stream, fans)
Known Issues
- Browser Issues: We've seen long load times in certain browsers (Internet Explorer, Chrome, and Safari) when the Web page containing the Fan Box references many other JavaScript libraries, especially with delayed execution. To work around this issue, do one of the following:
- Move the FeatureLoader script line (
<script src="http://www.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>) to the top of your Web page, right after the opening <body> tag. - Render the Fan Box in an IFrame, as described above.
- Using on MySpace: Because MySpace doesn't support IFrames on profiles, you cannot add a Fan Box directly to a MySpace profile. To add a Fan Box on MySpace, you need to create a MySpace application and use the IFrame method to render the Fan Box within the application. Then you can add the application to a MySpace profile. See the MySpace developer documentation for details.
- iWeb Height Issue: If you're adding a Fan Box to your site through iWeb, the Fan Box may render very tall. You can specify a height in the Inspector. A Fan Box with all the default features (10 connections, stream, Become a Fan button) is 554 pixels tall.
