FBMLspec
From Facebook Developers Wiki
Contents |
Facebook FBML High-Level Technical Specification
This technical specification provides an overview of the structure of and theory behind Facebook’s markup language (FBML). It illustrates how Facebook’s extension to HTML allows developers to create applications that provide their users with a richer, reliable user experience within an ecosystem like Facebook. FBML integrates developers' applications deeply into Facebook, letting applications interact with their users and the users' friends.
Understanding the Types of FBML Tags
FBML serves many roles within Facebook. It is used in secure conditions on the user profiles, in small snippets on the news feed, and in full page batches on canvas pages. The goal of FBML is to support a versatile tag set in order to help developers target these different settings.
There are dozens of FBML tags. With the exception of several special tags, they can be organized into the following types:
- Social data tags
- Sanitization tags
- Design tags
- Component tags
- Control tags
This specification highlights one FBML tag of each type.
Social Data Tags
Social data is the core of FBML and the primary attraction to developers. The main feature of FBML is the ability to easily place social tags within HTML. Social data tags retrieve and format data to the application or user making the request. This data can take many forms, such as user information, group information, or photos.
The most common and most readily used social data tag is fb:name. The fb:name tag identifies and renders the user's name in a variety of ways and can provide a link to that user’s profile.
A system to identify users is vitally important for any network. Developers need to know how to process user IDs. Consider your data and how to express it according to the Facebook style in a way that is consistent with Facebook and with the style of your application.
In order to ensure that this tag is used safely, Facebook checks for privacy restrictions each time the fb:name tag is invoked. A crucial feature of FBML is awareness of who is viewing the page. If someone logged in to Facebook is viewing the user, that user’s name is rendered fully; when viewed outside Facebook, only the user's first name appears. If the logged in user is blocked from viewing the particular user, nothing renders at all.
This tag has several other rendering properties. Facebook assumes the existence of a user page associated with the user ID. This would be the user’s profile page. Therefore, this tag can be rendered as a link to that profile. There are also English-specific grammar tags associated with the name. These tags indicate possessiveness, reflexiveness and whether the viewer is viewing his or her own profile. The developer needs to determine the context with which these tags are used.
For syntax and usage for fb:name, see Fb:name.
Sanitization Tags
All Web sites set their own standards. Web sites that allow for third party development need to make those developers aware of what those standards are, and how they are enforced. FBML uses sanitization tags to enforce site standards both internally and on developers’ applications created for the site. Even within a site, different areas may have different standards. In this section, we describe how FBML handles Flash content with the fb:swf tag.
In order to maintain the basic look, feel, and privacy expectations of a site, FBML needs to sanitize or remove certain HTML tags. Tags like img and a can easily be sanitized, but more powerful tags like object and embed need to be removed completely. FBML replaces these tags with more specific handlers aimed at the specific use cases allowed by the site, in this case displaying SWFs.
On Facebook, SWFs cannot automatically begin playing on profile pages, so the fb:swf tag displays a developer-specified place-holder image until the user interacts with the object. On an application's canvas page (the page where an application lives on Facebook), the application has more control of the feel of the page, so fb:swf renders as a normal embedded Flash object.
When sanitizing your site, think about your site's permissions. What are you comfortable having a Flash player do? What sort of links does you allow? How should your site handle Web forms?
For example, Facebook handles HTML form tags in a special way. Developers can use standard HTML forms, but Facebook adds more parameters in the form of hidden inputs. This allows Facebook to confirm that the logged in user submitted the form and also to send the form information back to the correct application. Unlike with Flash objects, this addition is invisible to developers. They have no control over these handling rules, but they are necessary for correct behavior.
For syntax and usage for fb:swf, see Fb:swf and UsageNotes/Forms.
Design Tags
Design tags help define the look of a page. While FBML allows developers to design their pages using standard HTML and CSS, we have found that FBML allows us to help developers by providing predefined design tags that help them blend their application into the style of the host site. On Facebook, these tags render into elements that we use on the rest of our site. However, the tags are general enough that they have design implementations on most other sites.
For example, many developers use fb:tabs to manage the flow of their application. Tabs provide a simple way to direct users to different sections of the application. Developers can include the tag and have an immediately recognizable UI element.
The actual implementation of fb:tabs is a straightforward transformation of an FBML tag to HTML. Unlike fb:name or fb:swf, it is not dependent on the viewer or location on the site. However, close attention must be paid because fb:tabs must be aware of its child fb:tab-item elements, which specify the content of the tabs.
If you're designing your application to run on a site like Facebook, the front-end specification is the same as it would be for your own site, so generate the HTML for the way you want it to look on your site. Bear in mind that design tags don’t rely on data about the logged in user or the environment.
For syntax and usage for this FBML tag, see Fb:tab-item.
Component Tags
In addition to design tags, FBML features some tags that provide richer features of the site. Component tags create widget-like components that allow for user interaction with an application on Facebook. Often these tags provide full ready made items that can be placed into the application.
One example of this form is the fb:comments tag. This is a customizable FBML component that displays a comment board in an application. The comment board is similar to the Facebook Wall, but a developer can integrate it into an application. To the user, the comment board operates just like a Wall, and the developer does not need to provide any additional back end code to support the component.
In order to support these components, the host needs to provide a way for developers to specify a unique ID for each comment board in their application. FBML refers to these as XIDs. The combination of the XID and the application specifies a unique component.
Components also require the ability to pass information back from an application. This refetch uses FBML as a way for an application to pass data back into Facebook. The refetch process is described in more detail on the Wiki page.
For syntax and usage for fb:comments, see Fb:comments.
Control Tags
FBML is not meant to be a full programming language, and therefore purposefully omits constructs like loops and only allows branching in limited contexts. This allows the renderer to easily do batch operations to fetch data. There are certain cases that are not known to the developer before hand that must be expressed in FBML. FBML supports a limited set of control tags for this purpose.
The most useful of these are the visible-to tags, such as fb:visible-to-owner. This tag allows an developer to show content only to the owner of application profile box. For example, you could display a link asking the user to customize their box. Control tags are not used as privacy tags, rather they control how FBML renders information on a page. Content that is hidden to the user is not removed from the page, but is obscured. You can see the information if you view the page source.
When employing control tags, consider what information you want to display, how you want to display it and under what circumstances. How do you want your application to hide information for one user and display it to another?
For syntax and usage for fb:visible-to-owner, see Fb:visible-to-owner.
Primary FBML Parameter Types
FBML uses the following types of parameters to further define its tags.
Array: An array of values for a given element, typically user IDs. For example, fb:multi-friend-selector uses an array to let a user select multiple friends.
Boolean: You can specify yes/no, true/false, and any number not equal to 0/0. For example, <fb:name useyou="true" />.
Color: You can use the color parameter type to define the background color for the associated content. The color can be specified as an English word that is recognizable by HTML (for a list of color names, see http://www.html-reference.com/colornames.htm) or as a hexadecimal color (a 6 character string). For example, red, or #FF0000. Tags that let you specify color include fb:swf and the various fb:visible-* tags.
Float: A floating point number. A float is used to specify the weight for an item in the fb:random-option tag and the version number in fb:fbml.
Int: These numbers are arbitrary precision keys, and are also known as bigints. They are used typically for various IDs, like user IDs, photo IDs, albums IDs, and so forth. For example, the uid parameter for fb:user is an int, as in: <fb:user uid="12345" />.
String: A string of text. The string can be a label for a user interface element, a URL, or message text, for example.
UID: The user ID. You can use the string loggedinuser or profileowner to substitute the IDs of those users. Facebook uses 64-bit integers for user IDs.
URL: The type of URL. Facebook permits different kinds of URLs in different parts of the site. The URL can be an absolute URL, a hash identifier, or a relative URL.
FBML Errors
FBML checks for and handles the following types of errors.
Parsing errors: Facebook checks to see if FBML is not well-formed. Certain tags can't be used in certain contexts. For example, a parsing error results if you try to place in image within fb:subtitle, or try to wrap fb:swf within fb:title. Parsing errors also result if you include tags that import information, like meta or embed anywhere in the FBML. Lastly, a parsing error occurs if you try to use a tag that isn't an actual FBML tag.
CSS errors: Facebook sanitizes and sandboxes the FBML style sheets so that a developer can change only the style of his or her application within Facebook, and not that of Facebook overall. Facebook also removes any JavaScript that might be in a developer’s CSS.
Rendering errors: Facebook checks for errors that result in any sort of incompatible FBML structure, which affects the rendering of information. For example, Facebook flags an application that gives a bad user ID for fb:name, or tries to use the fb:tab-item tag when it’s not within fb:tab. In this case, the FBML may be structurally correct, but the data is wrong.
For More Information
For information about all FBML tags, read the FBML page on the Facebook Developers Wiki.
