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.

Contents

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:

  • Discovering which of a user's connected friends on your site are also her Facebook friends. Example: fb:connect-form
  • Allowing the user to see what her connected friends are doing on your site.
  • Incorporating Facebook social context like a user's status with her user experience on your site. Examples: fb:user-status, fb:live-stream
  • Incorporating content from your site on Facebook – have the user add an application tab or box to her profile listing her recent activity.
  • Publishing 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. Example: fb:share-button (XFBML)

For a more in-depth look, read Providing Social Context on Your Site.

XFBML Tags

At this time, we support the following XFBML tags, many of which are very similar to existing FBML tags.

  • fb:bookmark displays an Add Bookmark button.
  • fb:comments displays a Comments Box social widget.
  • fb:connect-form displays a form inviting a user's friends to connect their Facebook accounts to a Facebook Connect site.
  • fb:container provides a conditional attribute around regular HTML markup.
  • fb:eventlink, like the FBML tag of the same name, displays the specified event name as a link to the event's page.
  • fb:fan displays a Fan Box social widget on your website.
  • fb:grouplink, like the FBML tag of the same name, displays the specified group name as a link to the group's page.
  • fb:live-stream displays a Live Stream Box on a Facebook Connect site.
  • fb:login-button displays the login button, as described above.
  • fb:name, like the FBML tag of the same name, displays the name of the user optionally linked to his or her profile.
  • fb:photo, like the FBML tag of the same name, displays a Facebook photo.
  • fb:profile-pic, like the FBML tag of the same name, displays the user's profile picture. 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, like the FBML tag of the same name, initiates a dialog requesting specified extended permissions from the user.
  • fb:pronoun, like the FBML tag of the same name, displays the appropriate pronoun for the specified user.
  • fb:serverFbml renders FBML on a Facebook server and displays 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 (XFBML), like the FBML tag of the same name, displays a standard Facebook Share button.
  • fb:unconnected-friends-count returns the number of friends on the site who have not connected their accounts.
  • fb:user-status, like the FBML tag of the same name, displays the status of the specified user.

You can see examples of XFBML in the demo applications. See the intermediate demo at Connect/Demos.

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.

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.

Getting Started with XFBML

To render XFBML on your Facebook Connect site or in your IFrame applications, read Connect/Setting Up Your Site.

DOM Requirements

Unlike certain FBML tags in standard Facebook applications, XFBML tags always need opening and closing tags. This is to ensure compatibility across all browsers.

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>.

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.

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.

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"