XFBML

From Facebook Developer Wiki

Jump to: navigation, search

Facebook uses XFBML as a way for you to incorporate FBML (Facebook Markup Language, an extension to HTML) into an HTML page on a Facebook Connect site or an iframe application. At this time, we support the following XFBML tags, many of which are very similar to existing FBML tags.

  • fb:comments, for rendering a Comments Box social widget.
  • fb:connect-form, for rendering a form inviting a user's friends to connect their Facebook accounts to a Facebook Connect site.
  • fb:container, for providing a conditional attribute around regular HTML markup.
  • fb:eventlink, which is just like the FBML tag of the same name.
  • fb:grouplink, which is just like the FBML tag of the same name.
  • fb:login-button, for rendering the login button, as described above.
  • fb:name, which is just like the FBML tag of the same name.
  • fb:photo, which is just like the FBML tag of the same name.
  • fb:profile-pic, which is just like the FBML tag of the same name. This tag now takes a facebook-logo attribute, that when set to true, returns the Facebook favicon image, which gets overlaid on top of the user's profile picture on your site.
  • fb:prompt-permission, which is just like the FBML tag of the same name.
  • fb:pronoun, which is just like the FBML tag of the same name.
  • fb:serverfbml, for rendering FBML on a Facebook server and displaying the content inside an iframe. You must use this tag to render elements on Facebook like fb:request-form (for friend selectors). See the note below.
  • fb:share-button, which is just like the FBML tag of the same name.
  • fb:unconnected-friends-count, which returns the number of friends on the site who have not connected their accounts.
  • fb:user-status, which is just like the FBML tag of the same name.

You can see examples of XFBML in the demo applications. See the intermediate demo at Trying Out Facebook Connect.

In addition, you can call standard Facebook Platform API methods like users.getInfo in order to retrieve a user's Facebook information and display it on your site.

Contents

[edit] About fb:serverfbml

The fb:serverfbml tag is a very powerful tag for Facebook Connect sites and iframe applications. You use this tag to render FBML tags that otherwise cannot be rendered as XFBML tags (that is, any tags other than the ones that appear in the list above). Typical FBML tags you would wrap within fb:serverfbml are those that require user input, like fb:request-form. The contents of fb:serverfbml are rendered in a Facebook iframe.

[edit] Providing Social Context Using XFBML

There are a number of ways you can use Facebook Connect to provide more social context on your site, and reflect (on Facebook) the social actions your users take on your site. Some examples include:

  • Discover which of a user's connected friends on your site are also her Facebook friends.
  • Allowing the user to see what her connected friends are doing on your site.
  • Incorporate Facebook social context like a user's status with her user experience on your site.
  • Incorporate content from your site on Facebook – have the user add an application tab or box to her profile listing her recent activity.
  • Publish social actions taken on your site to Facebook – when a user writes a review on your site (or buys something, or uploads a video), create a News Feed story about it on Facebook.

[edit] Rendering XFBML

  1. For the user's browser to correctly recognize XFBML tags, you need to specify that the page is in XHTML. Thus, your page should begin with:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">

    Note: The xmlns:fb attribute (xmlns:fb="http://www.facebook.com/2008/fbml") is required for proper rendering on IE.

  2. Include the following script to initialize the JavaScript Client Library. This script tells Facebook that you want to render XFBML on your site, so Facebook should load all necessary resources in order to do so.

    Note: For the best performance, put this code right after the <body> tag in the file.

    <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>

  3. Then, include the following script in the BODY of your HTML file, after the reference to the Feature Loader script (above) and after any XFBML tags you may reference. Replace "YOUR_API_KEY_HERE" with your application's API key and specify the path to the cross-domain communication channel file (xd_receiver.htm) you created.

    <script type="text/javascript"> FB_RequireFeatures(["XFBML"], function(){ FB.Facebook.init("YOUR_API_KEY_HERE", "<relative path from root>/xd_receiver.htm"); }); </script>

    For more details on the second parameter to the FB.Facebook.init call, see Cross Domain Communication Channel#Location_of_Channel_File.

Note: Be sure and specify a Connect URL for your application in the Facebook Developer application.

[edit] DOM Requirements

Unlike certain FBML tags in standard Facebook applications, XFBML tags always need opening and closing tags.

For example, if you're rendering a Facebook photo, you'd normally use fb:photo, which doesn't require a closing tag (as in <fb:photo pid="54321" uid="6789" />). However, to render the XFBML version of the tag on your site, you'll need to format the tag as <fb:photo pid="54321" uid="6789"></fb:photo>.

[edit] Testing Your XFBML

You can test your XFBML code in our XFBML test console on the Run Around site, which is our demo site for Facebook Connect.

[edit] Using HTML to Imitate XFBML

Alternately, if you do not want to use XFBML tags, you can still get the same result by using HTML markup and the Facebook JavaScript Client Library.

[edit] Showing XFBML Only When It Is Rendered

Sometimes, a website would want to only expose XFBML once it is rendered. Use the areElementsReady property of FB.XFBML.Host like this:
window.onload = function() { FB_RequireFeatures(["XFBML"], function() { FB.Facebook.init("<your app id>", "xd_receiver.html"); FB.XFBML.Host.get_areElementsReady().waitUntilReady(function() { document.getElementById("container").style.visibility = "visible"; }); }); };
Retrieved from "http://wiki.developers.facebook.com/index.php/XFBML"
reference