1|Page

Collect by Babon Mandal

FBML
Facebook Markup Language (FBML) enables you to build full Facebook Platform applications that deeply integrate into a user's Facebook experience. You
can hook into several Facebook integration points, including the profile, profile actions, Facebook canvas, News Feed and Mini-Feed.
FBML is an evolved subset of HTML with some elements removed, and others which have been added that are specific to Facebook. You set the FBML for a
profile box by calling profile.setFBML through the API. The FBML is cached on Facebook's server until profile.setFBML is called again through a canvas page.
For a high-level technical spec for FBML, please see FBMLspec.
To see which HTML and FBML tags you can use in various parts of your application, such as canvas pages, email, or Feed stories, see Allowed FBML and
HTML Tags.
You can define new FBML tags using Custom Tags. You can also use in your application custom tags that other developers created. To see the list of public tags
from other developers, visit the Custom Tags Directory.
Note: For Facebook Connect applications that run outside the Facebook frame, you can use XFBML, which is a separate language from the one described here.

Contents
[hide]

1 FBML Tags
o 1.1 User/Groups
o 1.2 Profile-specific
o 1.3 Visibility on Profile
o 1.4 Embedded Media

2|Page

o
o
o
o
o
o
o
o

1.5 Social Widgets

1.6 Platform Internationalization
1.7 Tools
1.8 Misc
1.9 Forms
1.10 Message Attachments
1.11 Additional Permissions
1.12 Notifications and Requests

1.13 Status Messages

1.14 Editor Display
1.15 Page Navigation
1.16 Dialog
1.17 Wall
2 Deprecated Tags
o
o
o
o
o

FBML Tags
Note: For an alphabetical listing, see FBML tags.

User/Groups

fb:name
fb:user
fb:pronoun
fb:profile-pic
fb:eventlink
fb:grouplink
fb:is-in-network
fb:if-can-see
fb:if-can-see-photo
fb:if-is-app-user
fb:if-is-friends-with-viewer
fb:if-is-group-member
fb:if-is-user
fb:if-is-verified (BETA)
fb:user-status

Profile-specific

fb:add-section-button
fb:if-section-not-added

3|Page

3 Dynamic FBML attributes

4 Usage Notes
5 Invalid CSS Attributes
6 See Also

7 External Links

fb:narrow
fb:wide
fb:user-table
o fb:user-item
fb:subtitle
o fb:action
fb:publisher-link

Visibility on Profile

fb:visible-to-owner
fb:visible-to-friends
fb:visible-to-app-users
fb:visible-to-connection
fb:restricted-to
fb:18-plus
fb:21-plus

Embedded Media

fb:iframe
fb:photo
fb:mp3
fb:swf
fb:flv
fb:silverlight

Social Widgets

fb:comments (XFBML)
fb:live-stream

fb:switch
o fb:default
fb:user-agent
fb:typeahead-input
o fb:typeahead-option

Misc
Platform Internationalization

fb:date
fb:fbml-attribute
fb:intl
fb:intl-token
fb:tag
fb:tag-attribute
fb:tag-body

fb:js-string
fb:fbml
fb:fbmlversion
fb:redirect
fb:ref
fb:share-button
fb:time
fb:title
fb:page-admin-edit-header

Forms

Tools

fb:board
fb:chat-invite (BETA)
fb:comments
fb:feed
fb:friend-selector
fb:google-analytics
fb:if
o fb:else
fb:if-multiple-actors
fb:mobile
fb:multi-friend-input
fb:quantcast
fb:random
o fb:random-option
fb:rock-the-vote

4|Page

fb:submit
fb:captcha

Message Attachments

fb:attachment-preview

Additional Permissions

fb:prompt-permission

Notifications and Requests

fb:req-choice
fb:request-form
o fb:multi-friend-selector

fb:multi-friend-selector (condensed)
fb:request-form-submit
fb:application-name
o
o

Status Messages

fb:error
fb:explanation
fb:success
o fb:message

Editor Display

fb:editor
o fb:editor-button
o fb:editor-buttonset
o fb:editor-cancel
o fb:editor-custom
o fb:editor-date
o fb:editor-divider
o fb:editor-month
o fb:editor-text
o fb:editor-textarea
o fb:editor-time

Page Navigation

fb:dashboard
o fb:action
o fb:create-button
o fb:help
fb:header
fb:mediaheader
o fb:header-title
o fb:owner-action
fb:tabs

5|Page

fb:tab-item

Dialog

fb:dialog
o fb:dialog-title
o fb:dialog-content
o fb:dialog-button

Wall

fb:wall
o

fb:wallpost
fb:wallpost-action

Deprecated Tags

fb:if-is-own-profile
fb:if-user-has-added-app
fb:networklink
fb:notif-subject
fb:notif-page
fb:notif-email
fb:profile-action
fb:userlink
fb:visible-to-added-app-users
fb:visible-to-user

Dynamic FBML attributes

Visibility (clicktoshow, clicktohide,clicktotoggle)

Mock AJAX (clickrewriteid,

clickrewriteurl,clickrewriteform)
Forms (clicktoenable, clicktodisable,clickthrough)
requirelogin
FBJS

Usage Notes

Forms
Images
CSS, Design, and the DOM
Javascript
Flavors
Facebook User IDs
Default FBML
Public Canvas Pages

Invalid CSS Attributes

Certain CSS properties are stripped by Facebook Platform for security purposes. This section needs updating. We'll get to it soon.
As of Dec 7, 2007, "position: absolute" maybe cause compatibility problems as mentioned here: http://developers.facebook.com/news.php?blog=1&story=56

A. Users / Groups
1. Fb:name
Description
Renders the name of the user specified, optionally linked to his or her profile.
6|Page

This also works for Facebook Pages with the ID of the Page passed as the uid parameter.
You can use this tag for both the subject and the object of a sentence describing an action. For example, if a user with the user ID $tagger tags a photo of a user
with the user ID $tagee, you could say:
<fb:name uid="$tagger" capitalize="true" /> tagged a photo of <fb:name subjectid="$tagger" uid="$tagee" />
User names and profile links follow standard Facebook privacy rules for other viewing users.

Attributes
Required Name

Type

Description

required uid

uid

The ID of the user or Page whose name you want to show. You can also use "profileowner" on a user's profile or an
application canvas page; you can use "loggedinuser" only on canvas pages.

optional firstnameonly bool

linked

bool

lastnameonly bool

Link to the user's profile. (Default value is true.)

Show only the user's last name. (Default value is false.)

possessive

bool

Make the user's name possessive (e.g. Joe's instead of Joe). (Default value is false.)

reflexive

bool

Use "yourself" if useyou is true. (Default value is false.)

shownetwork bool

7|Page

Show only the user's first name. (Default value is false.)

Displays the primary network for the uid. (Default value is false.)

useyou

bool

Use "you" if uid matches the logged in user. (Default value is true.)

ifcantsee

string

Alternate text to display if the logged in user cannot access the user specified. To specify an empty string instead of the
default, use ifcantsee="". (Default value is Facebook User.)

capitalize

bool

Capitalize the text if useyou==true and loggedinuser==uid. (Default value is false.)

subjectid

uid

The Facebook ID of the subject of the sentence where this name is the object of the verb of the sentence. Will use the
reflexive when appropriate. When subjectid is used, uid is considered to be the object and uid's name is produced.

Examples
If you're formatting the tag as FBML, you don't need to use a closing tag.
<fb:name uid="12345" />
If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.
<fb:name uid="12345"></fb:name>
FBML markup to use when logged in as user 1160:
<fb:name
<fb:name
<fb:name
<fb:name
<fb:name

subjectid="219770" uid="219770" /> = himself

subjectid="219770" uid="1160" /> = you
subjectid="1160" uid="219770" /> = Josh Gibson
subjectid="1160" uid="1160" /> = yourself
uid="profileowner" useyou="true" possessive="true" reflexive="true" /> = your own

<fb:name uid="1160" capitalize="true" /> tagged a photo of <fb:name subjectid="1160" uid="219770" />

2. Fb:user
Description
Hides the content enclosed in this tag from any user who is blocked by the user whose uid is referenced in fb:user.
For example, Alice and Bob are friends. Carol and Bob are friends. Alice and Carol are not friends. Alice cannot see Carol's profile, but Carol has not blocked her
and vice versa. Carol writes on Bob's Wall. Alice can see Carol's Wall post and her name, though she still can't see Carol's profile.
However, if Carol blocks Alice (or vice versa), then Carol's Wall post won't show up at all.
8|Page

If you want to hide user content based on a privacy check, use Fb:if-can-see.

Attributes
Required
required

Name

Type

Description

uid

int

The user ID of the user whose information will be contained in the tag.

Examples
<fb:user uid="12345" >
This is user 12345's information.
12345.
</fb:user>

It should only be shown to people who have not been blocked by user

3. Fb:pronoun
Description
Renders a pronoun for a specific user. If you include no additional parameters, then you is displayed if the user with uid is viewing the page. If another user is
the viewer, then he or she is displayed if the gender is known; otherwise, they is displayed.

Attributes
Required Name

Type Description

required uid

int

The user ID for whom to generate the pronoun. You can specify user IDs for multiple users by separating them with a comma, as
in: uid="1234, 5678". You can substitute actor for the user ID so you can more easily aggregate Feed stories.

optional useyou

bool

Use the word "you" if uid is viewing the page. (Default value is true.)

9|Page

possessive bool Use the possessive form (his/her/your/their). (Default value is false.)
reflexive

bool

Use the reflexive form (himself/herself/yourself/themself). (Default value is false.)

objective

bool

Use the objective form (him/her/you/them). (Default value is false.)

usethey

bool

Use "they" if gender is not specified. (Default value is true.)

capitalize bool Force a capital letter for the pronoun. (Default value is false.)

Examples
If you're formatting the tag as FBML, you don't need to use a closing tag.
<fb:pronoun uid="12345" />
If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.
<fb:pronoun uid="12345"></fb:pronoun>
Another FBML example.
<fb:pronoun uid="actor" possessive="true" useyou="false"/>

4. Fb:profile-pic
Description
Turns into an img tag for the specified user's or Facebook Page's profile picture.
The tag itself is treated like a standard img tag, so attributes valid for img are valid with fb:profile-pic as well. So you could specify width and height
settings instead of using the size attribute, for example.
10 | P a g e

Attributes
Required Name

Type

Description

required uid

int

The user ID of the profile or Facebook Page for the picture you want to display. On a canvas page, you can also use
"loggedinuser".

optional size

string

The size of the image to display. (Default value is thumb.). Other valid values are thumb (t) (50px wide), small (s) (100px
wide), normal (n) (200px wide), and square (q) (50px by 50px). Or, you can specify width and height settings instead, just
like an img tag.

linked

bool

Make the image a link to the user's profile. (Default value is true.)

facebooklogo

bool

(For use with Facebook Connect only.) When set to true, it returns the Facebook favicon image, which gets overlaid on top
of the user's profile picture on a site.

Examples
If you're formatting the tag as FBML, you don't need to use a closing tag.
<fb:profile-pic uid="12345" linked="true" />
If you're formatting the tag as XFBML for Facebook Connect or an iframe application, you must use a closing tag.
<fb:profile-pic uid="12345" facebook-logo="true" linked="false" width="300" height="400"></fb:profile-pic>
Note: If you're specifying a custom image size (using the height and width attributes), you no longer need to include px for each dimension.
Another FBML example.
<fb:profile-pic uid="12345" width="32" height="32" linked="true" />

11 | P a g e

It seems that a size of "normal" currently provides the best quality available through this tag. If you need an image larger than 200px wide and need this done
within FBML, you can use size "normal" in combination with width. This example creates an image twice the width of size "normal" in the best quality
possible with this tag.
<fb:profile-pic uid="12345" size="normal" width="400" />

Notes
If you need a larger version of the photo, don't want to stretch out the 200px wide photo, and can deal with having to use an API call rather than being able to use
an FBML tag, the URL for the gallery-view image (up to 604px in width or height) can be obtained using FQL via the src_big column of the photo table
(example included).

5. Fb:eventlink
Description
Prints the specified event name and formats it as a link to the event's page.

Attributes
Required
required

Name

Type

Description

eid

int

Event ID for the event whose name and link you want to retrieve.

Examples
If you're formatting the tag as FBML, you don't need to use a closing tag.
12 | P a g e

<fb:eventlink eid="21150032416" />

If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.
<fb:eventlink eid="21150032416"></fb:eventlink>

6. Fb:grouplink
Description
Prints the specified group name and formats it as a link to the group's page.

Attributes
Required
required

Name

Type

Description

gid

int

Group ID for the group whose name and link you want to retrieve.

Examples
If you're formatting the tag as FBML, you don't need to use a closing tag.
<fb:grouplink gid="2541896821" />

If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.
13 | P a g e

<fb:grouplink gid="2541896821"></fb:grouplink>

7. Fb:is-in-network
Description
Displays content inside the tag only if the user is in a given network.
Note: You can use fb:else with fb:is-in-network, even though the tag does not start with fb:if-.

Attributes
Required

Name

Type

Description

required

network

int

The network ID to check. You can check one network at a time.

optional

uid

int

The user ID to check. (Default value is loggedinuser.)

Examples
<fb:is-in-network
network="16777229" uid="1230541">User 1230541, you are in the
<fb:networklink nid="16777229" />
network!</fb:is-in-network>

Notes

This tag renders content on canvas pages and for notifications and feed stories. It doesn't work with profiles, email and notifications.
You can use the fb:networklink FBML to display only the name of the network.

14 | P a g e

* 8. Fb:if-can-see
Description
Displays the enclosed content if the logged in user can see the specified what attribute of the specified user.
You can use these settings to provide content or links with relevance to Facebook privacy or to implement your own privacy using Facebook's current controls.
You can use this tag in conjunction with fb:else.

Attributes
Required Name Type

Description

required uid

int

The user ID to check.

optional what

string

The privacy setting to check. (Default value is search.). Other valid values are profile, friends, not_limited, online,

statusupdates, wall, groups, photosofme, notes, feed, contact, email, aim, cell, phone, mailbox, address,
basic, education, professional, personal, seasonal.

Examples
<fb:if-can-see uid="12345" what="profile">
Check out how cool <fb:name uid="12345" /> is.
<fb:else>Sorry, no dice.</fb:else>
</fb:if-can-see>

See Also
15 | P a g e

You can see a real world example of this tag in the Footprints demo application. Go to Demos for more details and to download and install the demo apps.

* 9. Fb:if-can-see-photo
Description
Displays the enclosed content only if the logged in user can see the photo specified.
You should use this tag[who says?] when specifying content that should only be shown when using fb:photo.
You can use this tag in conjunction with fb:else.

Attributes
Required Name Type

Description

required pid

string

An API-supplied pid of the photo, or any pid found in the query string of a photo URL on Facebook. The pid cannot be longer than
50 characters.

optional uid

int

If pid is not an API-supplied pid, this should be the id parameter in the query string used to find the pid.

Examples
<fb:if-can-see-photo pid="12345">
<fb:photo pid="12345" />
Check out this cool photo!
</fb:if-can-see-photo>

<fb:if-can-see-photo pid="54321" uid="6789">

<fb:photo pid="54321" uid="6789" />
16 | P a g e

This one is cool too!

</fb:if-can-see-photo>

* 10. Fb:if-is-app-user
Descriptions
Displays the enclosed content only if the specified user has accepted the terms of service of the application (that is, authorized your application).

Attributes
Required
optional

Name

Type

Description

uid

int

The user ID to check. (Default value is loggedinuser.)

Examples
<fb:if-is-app-user uid="12345">
Here's the user's score: 55555!
<fb:else>That user hasn't signed up for the app!</fb:else>
</fb:if-is-app-user>

<fb:if-is-app-user>
Your score: 55555!
<fb:else>You should sign up and play!</fb:else>
</fb:if-is-app-user>

17 | P a g e

* 11. Fb:if-is-friends-with-viewer
Description
Displays the enclosed content only if the specified user is friends with the logged in user.

Attributes
Required
optional

Name

Type

Description

uid

int

The user ID to check. (Default value is profile owner[verify].)

includeself

bool

Return true if viewer and uid specified are the same. (Default value is true.)

Examples
<fb:if-is-friends-with-viewer uid="12345">
Hey you guys are friends!
<fb:else>Did you know that you have something in common?</fb:else>
</fb:if-is-friends-with-viewer>

* 12. Fb:if-is-group-member
Description
Displays the enclosed content only if the specified user is a member of the specified group.
18 | P a g e

Attributes
Required

Name

Type

Description

required

gid

int

The group ID.

optional

uid

int

The user ID to check. (Default value is loggedinuser.)

role

string

The role to check. (Default value is member.). Other valid values are officer, admin.

Examples
<fb:if-is-group-member gid="54321" uid="12345" role="admin">
Hey, you're an admin of that group!
<fb:else>Sorry, admins only!</fb:else>
</fb:if-is-group-member>

* 13. Fb:if-is-user
Description
Only renders the content inside the tag if the viewer is one of the specified user(s).

Attributes
Required Name Type Description
required uid

Examples
19 | P a g e

int

The user ID of the user that is allowed to see the content. To match multiple users, pass in a comma-delimited list of uids.

<fb:if-is-user uid="uid1,uid2">This is secret 4 u 2!</fb:if-is-user>

[*] Notes
As of FBML v1.1 you can use this tag only on a canvas page.

14. Fb:if-is-verified
Description
Displays the enclosed content only if Facebook has verified the current user. You should use this tag with fb:else to provide alternate content in case Facebook
has not verified the user.
Important: You may never disclose a user's verified state anywhere in your application or on Facebook, whether to that user or the user's friends.

Examples
<fb:if-is-verified>
Here's some content.
<fb:else>Let's show you this instead.</fb:else>
</fb:if-is-verified>

See Also

users.isVerified
fb:else

20 | P a g e

15. Fb:user-status
Description
Returns the status of the user specified by uid. If there is a URL in the status that starts with either http or https, it can be formatted as a hyperlink.
If the viewing user doesn't have permission to see the user's status, an empty string is returned.
Note: This tag only returns the status, not the user's name, so it might be more useful to display the user's name along with the status.

Attributes
Required

Name

Type

Description

required

uid

int

The user ID of the user whose status you want to retrieve.

optional

linked

bool

Indicates whether URLs in the status should be formatted as hyperlinks. (Default value is true.)

Examples
If you're formatting the tag as FBML, you don't need to use a closing tag.
<fb:user-status uid="12345" linked="true"/>
If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.
<fb:user-status uid="12345" linked="true"></fb:user-status>

21 | P a g e

B. Profile-Specific
1. Fb:add-section-button
Description
Renders an Add to Profile or Add to Info button (depending upon which section attribute you specify) on an application's canvas page. This button allows a
user to add either a new condensed profile box to the main profile or a new application info section to the Info tab.
Important: The button appears only if the application has already called profile.setInfo or profile.setFBML and set info for that user. We recommend you call
profile.setInfo after the user has entered enough data for your application to be able to make a compelling info section.
If the user already has a condensed profile box or an info section from the application, the button does not appear on that application's canvas page.
The Platform Guidelines state that you cannot incentivize users to add integration points, so you cannot know whether the user has added a profile box. However,
you can use the fb:if-section-not-added tag to have Facebook render contents -- such as the fb:add-section-button tag with an explanation for the user -- only if
the user hasn't added the profile box or info section.

Attributes
Required Name Type
required section Specifies whether to add a condensed profile box to the main profile (profile) or an application info section to the Info tab
(info).

Examples
<fb:add-section-button section="profile" />

22 | P a g e

Description

2. Fb:if-section-not-added
Description
Renders the content wrapped within this tag on an application canvas page if the user hasn't added a condensed profile box or info section to her profile. Use this
to encourage your users to add a box or info section to their profiles.
If the user already has a condensed profile box or an info section from the application, then nothing appears on that application's canvas page for this tag.
The content cannot be more than 100 pixels in height.

Attributes
Required Name Type

Description

required section string Specifies which section to check (profile to check for a condensed profile box in the narrow column on the Wall and Info tabs or a
box in either column on the Boxes tab, or info to check for an application info section to the Info tab).

Examples
<fb:if-section-not-added section="profile">
Display our box on your profile!<br />
<fb:add-section-button section="profile" />
</fb:if-section-not-added>
23 | P a g e

Notes

You cannot use fb:else with this tag. This is to prevent the gating of application functionality if a user hasn't added an application info section.
Contents of this tag are limited to a maximum height of 100 pixels. Facebook enforces this by wrapping the tag in a div with a style of "maxheight:100px; overflow:hidden"

3. Fb:narrow
Description
Renders the content contained by the tag only if the profile box is in the narrow column of the profile.

Examples
<fb:narrow>
This text appears only in the narrow column.
</fb:narrow>

Notes
If no fb:narrow or fb:wide tag is specified, all content is displayed in either column.
24 | P a g e

The narrow profile box is 200 pixels wide, including margins. There are 8 pixels of padding on each side, so the actual amount of column width you can use is
184 pixels.
If you want your fb:narrow information to appear when installed, set the Default Profile Box Column value to Narrow in Installation section of your
application's settings in the Developer application.

4. Fb:wide
Description
The enclosed content appears only when profile box is in the wide column of the profile. See fb:narrow for the opposite.

Examples
<fb:wide>
This will only appear in the wide column.

</fb:wide>

Notes
If no fb:narrow or fb:wide tag is specified, all content appears in either column.
The wide profile box is 388 pixels wide, not including margins. The left margin is 8 pixels, but there is no right margin. For balanced margins, make your content
380 pixels wide.

25 | P a g e

5. Fb:user-table
Description
Renders a table, each cell of which contains a thumbnail and name for a particular user, similar to the Mutual Friends table on profile pages. Inside this tag, use
fb:user-item tags to specify the set of users. This tag only works on profile pages. Applications cannot use this on their canvas pages.

Attributes
Required
optional

Name

Type

Description

cols

int

The number of columns in the table. (Default value is 6 for fb:wide, 3 for fb:narrow.)

Examples
<fb:user-table cols="3">
<fb:user-item uid="12345" />
<fb:user-item uid="123456" />
<fb:user-item uid="123457" />
<fb:user-item uid="123458" />
<fb:user-item uid="123459" />
<fb:user-item uid="123450" />
</fb:user-table>

5. Fb:user-item
Description
26 | P a g e

Renders a single cell of a table, which contains a thumbnail and name for a particular user, similar to the Mutual Friends table on profile pages. Must be used
inside a fb:user-table tag. This tag only works on profile pages. Applications cannot use this on their canvas pages.

Attributes
Required
required

Name

Type

Description

uid

uid

The ID of the user whose name and photo you want to show.

Examples
<fb:user-table cols="3">
<fb:user-item uid="12345" />
<fb:user-item uid="123456" />
<fb:user-item uid="123457" />
<fb:user-item uid="123458" />
<fb:user-item uid="123459" />
<fb:user-item uid="123450" />
</fb:user-table>

6. Fb:subtitle
Description
Defines the subtitle for the profile box. The enclosed content is interpreted purely as plain text.
This tag may contain fb:action, an optional tag that renders an action link on the right-hand side of the subtitle.

Attributes
27 | P a g e

Required
optional

Name

Type

Description

seeallurl

string

The URL for a "See all" link. This URL must be a facebook canvas page.

Examples
<fb:subtitle seeallurl="http://apps.facebook.com/myapp/seeall" >
<fb:action href="http://apps.facebook.com/fun_graphics_app/new.php">Post a new fun graphic</fb:action>
Displaying 10 images
</fb:subtitle>

Notes

This tag always renders the HTML title attribute with Learn More About This Application for seeallurl.[possible bug?] At present there doesn't seem to be
any way to prevent this.
This tag does not function within fb:visible-to- tags.

See Also

fb:title

7. Fb:action
Description
Renders a link, usually for navigational purposes. Its appearance depends on its container.
The tag must be a child of either fb:dashboard or fb:subtitle.
28 | P a g e

Attributes
Required Name Type
required href

string

Description
The URL for the link. The URL must be a canvas page. For example,
href="http://apps.facebook.com/<appname>/<filename>.php".

optional onclick string Call a FBJS function

Examples
<fb:dashboard>
<fb:action href="new.php">Create a new photo album</fb:action>
</fb:dashboard>

<fb:dashboard>
<fb:action href="new.php">Create a new photo album</fb:action>
<fb:action href="you.php">Photos of You</fb:action>
</fb:dashboard>

29 | P a g e

This article or section needs expansion

Notes

The link appears in the top left of the fb:dashboard element and the top right of the fb:subtitle element.
You cannot use FBJS onclick, since you cannot have the href attribute set to # or javascript:. You can use the onclick attribute: use any absolute
URL in the href and make sure onclick returns false to prevent the link from being followed.

Fb:publisher-link
Description
Renders an anchor tag around the internal content pointing to a profile with the application's Publisher preselected.

Attributes
Required
optional

Name

Type

Description

uid

int

The user's profile to link to the Publisher.

Examples
<fb:publisher-link uid="4842" >Send a gift to <fb:name uid="4842" linked="false" /></fb:publisher-link>
30 | P a g e

C. Visibility on Profile
Fb:visible-to-owner
Description
Displays content inside only if the viewer of the profile matches the profile owner.
This also works for Facebook Pages with the content only displayed to an admin of the Page.

Attributes
Required
optional
31 | P a g e

Name

Type

Description

bgcolor

color

The color of the blank box shown to users who are not the owner.

Examples
<fb:visible-to-owner>
Welcome back to your profile!
</fb:visible-to-owner>

Notes

This is new to FBML v1.1, make sure you wrap your code in <fb:fbml version="1.1"> and </fb:fbml>! Even inside the default FBML tag, or when using
setFBML.
Do not use this tag to display private or sensitive information. Content inside this tag is rendered to all users' browsers, including those who are not the
profile owner. For those who are not the owner, the content is shown as white space on the page but it is still visible by viewing the page source.
This tag cannot be used to for controlled display elements like fb:subtitle
This tag only sets the css style to "visibility:hidden" instead of the ideal "display:none"... This will leave massive white space to the non-owner.

Fb:visible-to-friends
Description
Use this tag to display the content inside the tag on a user's profile only if the viewer is a friend of that user.
While this tag is still valid, you may find it more versatile to use fb:visible-to-connection, since it applies equally to user profiles and Facebook Pages.

Attributes
Required
optional
32 | P a g e

Name

Type

Description

bgcolor

color

The color of the blank box shown to viewers who are not friends of the user.

Examples
<fb:visible-to-friends>Hello my friend!</fb:visible-to-friends>

Notes

This is new to FBML v1.1.

Do not use this tag to display private or sensitive information. Content inside this tag is rendered to all users' browsers, including those who are not
one of the specified users. For those who are not one of those users, the content is shown as white space on the page but it is still visible by viewing the
page source.
Content in this tag is also visible to the owner.

Fb:visible-to-app-users
Description
Displays the enclosed content only if the viewer has granted full permissions to the application.[verify]

Attributes
Required
optional

Name

Type

Description

bgcolor

color

The color of the blank box shown to users who have not granted full permissions to the app.

Examples
<fb:visible-to-app-users>
33 | P a g e

Welcome users!
</fb:visible-to-app-users>

Notes

This is new to FBML v1.1.

Do not use this tag to display private or sensitive information. Content inside this tag is rendered to all users' browsers, including those who have not
granted full permissions to the application. For those who have not done so, the content is shown as white space on the page but it is still visible by
viewing the page source.
fb:else doesn't work here either.

Fb:visible-to-connection
Description
Use this tag to display the content inside the tag on a user's or a Facebook Page's profile only if the viewer is a friend of that user or is a fan of that Facebook
Page.

Attributes
Required
optional

Name

Type

Description

bgcolor

color

The color of the blank box shown to viewers who are not friends of the user or fans of the Page.

Examples
<fb:visible-to-connection>Welcome, fans!</fb:visible-to-connection>

Notes
34 | P a g e

This is new to FBML v1.1, make sure you wrap your code in <fb:fbml version="1.1"> and </fb:fbml>! Even inside the default FBML tag, or when using
setFBML.
Do not use this tag to display private or sensitive information. Content inside this tag is rendered to all users' browsers, including those who are not
one of the specified users. For those who are not one of those users, the content is shown as white space on the page but it is still visible by viewing the
page source.
Content in this tag is also visible to the owner.

Fb:restricted-to
Description
Lets you tailor the enclosed content to display to specific ages, locations, or content types.
You should use this tag with fb:else so you can provide alternate content in case the viewing user doesn't meet the demographic requirements. Also, if the user
hides their age for privacy reasons, Facebook cannot determine whether or not the content is visible to the user, and thus it cannot be displayed. In this case, your
fb:else clause should contain content that any user who doesn't necessarily meet these restrictions could see.
Note: You cannot use the fb:restricted-to tag to send invitations and requests to a demographically-restricted set of users, as with fb:multi-friend-selector. Instead,
use the admin.getRestrictionInfo and admin.setRestrictionInfo API calls to target those users for your application overall.
Note: If you want to restrict your entire application to a given set of demographic restrictions, use admin.setRestrictionInfo.

Attributes
Required Name

Type

Description

optional age

string

The valid age or age range that can see the content. To specify multiple age ranges, separate each entry with a comma.
Every specified age must be an integer. You can use plus (+) and minus (-) to restrict content to that age or older/younger
(like 21+ for 21 and older or 18- for younger than 19). You can also specify a range of ages, like 18-35 so anyone between
the ages of 18 and 35 (inclusive) can see the content. You can also specify multiple age ranges (like 19-,30+ -- if you want
to exclude people in their 20s, for example). Every specified age must be an integer, and only the integer part of a user's

35 | P a g e

age is taken into account. So for example, a user who is 17.9 years old will be treated as 17, and "18-35" includes anyone
18 or older but under 36.
location

string

age_distribution array
type

string

The country or countries that can see the content. To specify multiple countries, separate each entry with a comma. When
specifying the location, specify the country or countries (using a comma-separated list) from the ISO 3166 alpha 2 code
list. This list is not necessarily the same as the IANA ccTLD (country code top level domain) list. For example, the ISO
3166 entry for England is .gb, while the IANA entry is .uk.
An array containing age and location restrictions for multiple areas.
The type of content being filtered. You can specify alcohol at this time. Before rendering your FBML, we run a check
against the type on Facebook, and if the user meets the age and location requirements, we'll render the content.

Examples
Restricting content to users 17 and younger only.
<fb:restricted-to age="17-">Let's talk boy bands.
<fb:else>Cool, the kids are gone!</fb:else>
</fb:restricted-to>
Restricting content to users 18 and older in Great Britain only.
<fb:restricted-to age="18+" location="gb">Remember to drive on the <i>correct</i> side of the road.
<fb:else>You're either not from Great Britain or you're from Great Britain but not 18 yet.</fb:else>
</fb:restricted-to>

Specifying alcohol content to users in the United States only.

<fb:restricted-to location="us" type="alcohol">Enjoy a fine malt beverage.
<fb:else>Enjoy a nice soft drink.</fb:else>
</fb:restricted-to>

36 | P a g e

Fb:18-plus
Description
Restricts content to users who are age 18 or older.
You should use this tag with fb:else so you can provide alternate content in case the viewing user doesn't meet the age restriction.
Keep in mind that the content you provide to people 18 and older must still conform to the Facebook Platform Guidelines and Statement of Rights and
Responsibilities.

Examples
<fb:18-plus>Oooh la la<fb:else>Barney?</fb:else></fb:18-plus>

Fb:21-plus
Description
Restricts content to users who are age 21 or older.
You should use this tag with fb:else so you can provide alternate content in case the viewing user doesn't meet the age restriction.
Keep in mind that the content you provide to people 21 and older must still conform to the Facebook Platform Guidelines and Statement of Rights and
Responsibilities.

Examples
<fb:21-plus>Ooooh la la<fb:else>Barney?</fb:else></fb:21-plus>
37 | P a g e

D. Embedded Media

Fb:iframe
Description
Inserts an <iframe> tag into an application canvas page; you cannot use the <fb:iframe> tag on the profile page (that is, application tabs and profile boxes). You
cannot use FBML inside an iframe; use XFBML tags instead.
The conventional <iframe> tag has been re-created in FBML and became <fb:iframe>. You edit the attributes for <fb:iframe> the same way you would for
HTML tags.
If you aren't requiring a session secret to be passed, you must use your server's URL as the src for your iframe. Otherwise, apps.facebook.com wraps your page
with the Facebook layout.

Attributes
Required Name

Type

Description

required src

string

The URL of the iframe. Signed GET parameters are appended to the URL to prove that the frame was loaded through
Facebook, as described in the forms section. These parameters also include one named fb_sig_in_iframe to indicate this
context.

optional smartsize

bool

This parameter smartly sizes the iframe to fit the remaining space on the page and disables the outer scrollbars. If you
include more than one smartsizing iframe, they automatically distribute the size appropriately. (Default value is false.)

frameborder

int

Indicates whether to show (1) or hide (0) an iframe border. (Default value is 1.)

scrolling

string

Indicates whether to show scrollbars. (Default value is yes.) - use "yes", "no", or "auto" (not "true" or "false")

style

string

Indicates a custom inline style for the iframe.

width

int

Indicates the width of the iframe.

height

int

Indicates the height of the iframe.

38 | P a g e

resizable

bool

Gives the ability to set the iframe's size using the JavaScript API. See Resizable IFrame for details. You must specify a name
for this iframe. This option cannot be used when smartsize is enabled.

name

string

The name of the iframe. You must name the iframe when resizable is enabled.

ext_send_ss

bool

Setting this to true requires that the session secret (fb_sig_ss) be passed, in addition to the usual fb_sig parameters, when
available. You might want to require this when the iframe source is outside of the application callback URL. By default this
attribute is false to prevent unintentionally sending application and user data to a third party, which can use the session
secret to make API calls on behalf of the application or user. You should use this attribute only to send the session secret to
an application-owned URL that needs to make API calls, as the iframe source may not necessarily fall under its callback
URL. (Default value is false.)

include_fb_sig bool

Setting this to false indicates that credential information is not sent to the site in the iframe. This prevents external sites from
stealing private information.(Default value is true.)

Fb:photo
Description
Renders a Facebook photo.

Attributes
Required Name Type

Description

required pid

string

An API-supplied pid of the photo. The pid cannot be longer than 50 characters. (The use of a pid found in the query string of a
photo URL on Facebook is deprecated.)

optional uid

int

(Deprecated) If the pid is not an API-supplied pid, this should be the ID parameter in the query string used to find the pid. This
property is not supported in the XFBML variant of this tag and is deprecated for the FBML variant.

size

string

The size of the photo to display. (Default value is normal.). Other valid values are thumb (t) (75px width), small (s) (max of 130px
width or height), and normal (n) (max of 604px width or height).

align

string

The image's alignment. (Default value is left.) and the only other valid value is right.

39 | P a g e

Examples
If you're formatting the tag as FBML, you don't need to use a closing tag.
<fb:photo pid="12345" />
If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.
<fb:photo pid="12345"></fb:photo>

Notes

The pid returned after making an FQL call is not the same pid found in the string of a photo URL. Please only use the pid found via the API.

If the user is not able to see the photo, then the photo will not be rendered. To provide an alternate user interface for those users, you can use the fb:if-cansee-photo tag.
There are 2 undocumented parameters width and height. By setting these you can scale an image to the preferred size. Keep in mind that this will use inbrowser scaling and results may vary depending on the browser

Fb:mp3
Description
Renders a Flash-based audio player.

Attributes
Required

Name

Type

Description

Required

src

string

The URL of the audio file. The URL must be absolute.

Optional

title

string

The name of the song.

40 | P a g e

artist

string

The name of the artist performing the song.

album

string

The title of the album.

width

int

The width of the player in pixels. (Default value is 300.)

height

int

Does nothing. (Default value is 29.)

Examples
<fb:mp3 src="http://host.com/file.mp3" title="Song Name" artist="Song Artist" album="Album Name"/>

Notes

Currently, Facebook requires a minimum Flash Player version of either 9.0.159.0 or 10.0.22.87 for all <fb:swf> tags. When Adobe discontinues security
updates for Flash 9 (Flash 10 is unsupported on Windows 98 and ME), it will no longer be supported anywhere on Facebook.
If you want to call the Facebook Platform API from a Flash application (using the ActionScript 3.0 Library for Facebook Platform), you need to render
your Flash object with fb:swf or fb:fbjs-bridge.
The src attribute must point directly to the mp3 file,[possible bug?][who says?] and cannot be played by a query string (for example, "songs.php?songid=35911").
Supported formats include .mp3.
.wav files are not supported[possible bug?].
File's bitrate must me in increments of 11KHz (11KHz, 22KHz, 44.1 KHz all work).
File must end in .mp3 (for example, /location/1385097 will not work).
The title, artist, and album attributes must be in ASCII characters or the file does not display correctly. For example, titles with Chinese characters do not
display in Chinese but in gibberish or not at all[possible bug?].
Even though the artist attribute is optional, providing an empty string value (as in, artist="") will result in "Unknown Artist" being displayed, rather than
nothing as specified[possible bug?].
The height attribute doesn't actually do anything[possible bug?].
If there are multiple fb:mp3 controls on the same page, it is possible for the user to play all of them simultaneously[possible bug?]

Requested Enhancements
41 | P a g e

Prevent the simultaneous playback of multiple fb:mp3 controls on the same page by stopping any currently playing fb:mp3 if another one is played.
Enable the "height" attribute
Implement volume control
Add XSPF support
Make artist attribute truly optional. IE: When it is not specified, no artist is displayed and it does not scroll away from the song title

See Also

fb:flv
fb:swf

Fb:swf
Description
Renders a Shockwave Flash (SWF) object. On profile pages, an image appears first. When the user clicks the image, it turns into the Flash object. On canvas
pages, the image is ignored, and the Flash object is directly included.
You can also make API calls to Facebook directly from Flash. Check out the official ActionScript 3.0 Library for Facebook Platform for more details.

Attributes
Required Name

Type

Description

required swfsrc

string

The URL of the Flash object. The URL must be absolute.

optional imgsrc

string

The URL of the image (.gif and .jpg formats only). (Default value is http://static.ak.facebook.com/images/spacer.gif; Note that
this renders the Flash object unusable and invisible on profile pages, if no height/width parameters are set..)

height

int

The height of the image and the Flash object.

width

int

The width of the image and the Flash object.

42 | P a g e

imgstyle

string

The style attribute for the image.

imgclass

string

The class attribute for the image.

flashvars

string

The URL-encoded Flash variables. Also passes the fb_sig_ values as described in the section on Forms.

swfbgcolor string The hex-encoded background color for the Flash object. By default, a Flash object's background defaults to transparent, so if
you want a background color, specify one for this attribute.
waitforclick bool

Indicates whether to autoplay the Flash object (false) when allowed. false does not work in profiles for security and
aesthetic reasons, except after an AJAX call. (Default value is true.)

salign

string

The salign attribute from normal Flash <embed>. Specify t (top), b (bottom) l (left), r (right) or a combination (tl, tr, bl,
br)

loop

bool

Indicates whether to play the Flash object continuously. Specify true or false

quality

string

Indicates the quality of the object. Specify best, high, medium or low.

scale

string

The scaling to apply to the object. Specify showall, noborder, exactfit

align

string

Indicates how the browser aligns the obect. Specify left, center or right

wmode

string

Indicates the opacity setting for the object. Specify transparent, opaque or window. (Default value is transparent.)

Flash Variables
Facebook passes the following parameters to the SWF when it is loaded:
Required Name

Type

Description

allowScriptAccess string This string is always set to "never."

fb_sig_profile

int

The uid of the user into whose profile the Flash object is being loaded; this is blank when loaded in the canvas.

fb_sig_time

int

The time when the signature was generated.

fb_sig_user

int

The uid of the currently logged in user.

fb_sig_session_key string The Facebook session key.

fb_sig_expires
43 | P a g e

int

The session expiration time.

fb_sig_api_key

string

Your application's API key.

fb_sig_added

bool

Indicates whether the user has added your application.

fb_sig_ss

string

The session secret, used in place of your application's secret key for secure API calls. This is sent only to a SWF that
resides within the domain or subdomain of your application's callback URL. The session secret also gets passed to a
SWF object inside your Publisher.

fb_sig

string

An MD5 hash of all the parameters with names that start with fb_sig_ plus your application secret. This way, the Flash
object can confirm that it is being loaded into a Facebook page. (But be careful embedding your secret in your Flash
application; hackers can get at it if you do.) See notes below.

Examples
<fb:swf
swfbgcolor="000000"
imgstyle="border-width:3px; border-color:white;"
swfsrc='http://www.youtube.com/v/xxxxxxxxxx'
imgsrc='http://img.youtube.com/vi/xxxxxxxxxx/2.jpg'
width='340' height='270' />

Notes

Currently, Facebook requires a minimum Flash Player version of either 9.0.159.0 or 10.0.22.87 for all <fb:swf> tags. When Adobe discontinues security
updates for Flash 9 (Flash 10 is unsupported on Windows 98 and ME), it will no longer be supported anywhere on Facebook.

Make sure that the flashvars parameter is all lowercase. Some sources of embedded links capitalize the V, which does not work on Facebook.
Currently, Facebook wraps the resultant Flash object in a <div> tag, so despite the fact that the embed/object tag is not block-level, consecutive <fb:swf>
tags will appear one above the other instead of side-by-side.
Facebook prevents direct script access from Flash with allowScriptAccess=none. To link or call JavaScript from your Flash object, you can use Flash
localconnection and the fb:fbjs-bridge tag.

44 | P a g e

To verify that your Flash object was loaded from a Facebook page, do the following. For security, this technique does not embed your secret key in your
Flash app:

1. Get all the parameters whose names start with fb_sig. (Do not include the fb_sig parameter itself.) In Flex use Application.application.parameters to do
this.
2. Strip the fb_sig_ prefix from all parameters, and make sure the keys are lowercase.
3. Create a string of the form param1=value1param2=value2param3=value3, etc., sorted by the names (not the values) of the parameters. Note: Do not use
ampersands between the parameters.
4. Separately pass this string and the fb_sig parameter itself to your server, where your secret key is stored.
5. On your server, append your application secret key to the string that was passed in. The following is returned:
param1=value1param2=value2param3=value3myappsecret
6. On your server, create an MD5 hash of this string.
7. On your server, compare the generated hash with the fb_sig parameter that was passed in. If they are equal, then your Flash object was loaded by
Facebook. (Or by someone who stole your secret key.) In this case respond to the flash object with VALID or a similar code. If the signature is not valid,
respond with INVALID.

See Also

fb:flv
fb:mp3
fb:fbjs-bridge

Fb:flv
Description
Renders a Flash-based FLV player that can stream arbitrary FLV (video/audio) files on the page.

Attributes
45 | P a g e

Required Name Type

required src

string

Description
The URL of the FLV file. The URL must be absolute.

optional height int

The height of the video container in pixels or percentage.

width int

The width of the video container in pixels or percentage.

title

string

The name of the video. The title appears on the movie's control bar.

scale

string

A Flash attribute. How to scale the movie within the container. Specify one of showall (displays the whole movie, overriding
container dimensions while maintaining the original aspect ratio of the container), noborder (movie fills the container, without
distortion but possibly with some cropping, while maintaining the original aspect ratio of the container), or exactfit (movie
dimensions match container dimensions, which may result in distortion). (Default value is showall.)

img

string

The URL of the image displayed behind the play button before the movie starts playing. The URL must be absolute.

align

string

A Flash attribute. Determines where the FLV file is aligned within the container. Specify l (left), r (right), t (top), b (bottom).

salign string A Flash attribute. Specifies where the scaled FLV file appears within the container based on its width and height settings. Specify l
(left), r (right), t (top), b (bottom).
color string The hex value for background color while the movie plays. (Default value is #000000.)

Examples
<fb:flv
src='http://www.mediacollege.com/video-gallery/testclips/barsandtone.flv'
width='400' height='300' title='my movie' color='#FFBB00' salign='r'
img='http://www.example.com/test.jpg' scale='showall'/>

Notes

Currently, Facebook requires a minimum Flash Player version of either 9.0.159.0 or 10.0.22.87 for all <fb:flv> tags. When Adobe discontinues security
updates for Flash 9 (Flash 10 is unsupported on Windows 98 and ME), it will no longer be supported anywhere on Facebook.
If you want to call the Facebook Platform API from a Flash application (using the ActionScript 3.0 Library for Facebook Platform), you need to render
your Flash object with fb:swf or fb:fbjs-bridge.
The file supplied must already be encoded as FLV you cannot pass an .avi file into the player, for example.

46 | P a g e

When using fb:flv and Internet Explorer, width and height may need to be specified. Otherwise the Flash object renders as a single grey pixel.

See Also

fb:mp3
fb:swf

Fb:silverlight
Description
Renders a Microsoft Silverlight control. On profile pages, an image appears first. When the user clicks the image, it turns into the control. On canvas pages, the
image does not appear, and the Silverlight control is directly included.

Attributes
Required Name

Type

Description

required silverlightsrc string The URL of the Silverlight control.

string

The URL of the image (.gif and .jpg formats only). (Default value is http://static.ak.facebook.com/images/spacer.gif. Note
that this renders the Silverlight control unusable and invisible on profile pages.)

height

int

The height of the image and Silverlight control.

width

int

The width of the image and Silverlight control.

imgstyle

string

The style attribute for the image.

imgclass

string

The class attribute for the image.

swfbgcolor

string

The hex-encoded background color for the Silverlight control.

optional imgsrc

47 | P a g e

Examples
<fb:silverlight silverlightsrc="http://www.somesite.com/silverlight" />
For now this feature has no functionality.

E. Social Widgets

Fb:comments (XFBML)
Description
Displays a Comments Box on a Facebook Connect site or in an IFrame application. The Comments Box is the XFBML version of the fb:comments tag. It lets
developers add a comment box to a website or in an iframe application easily.
The Comments Box has a default appearance with a rounded box around each post, or you can use the simple attribute to remove the box. If you want, you can
choose to specify your own stylesheet (by including the css attribute and reference the URL to your stylesheet).
You can modify the Comments Box's colors and fonts, but you cannot delete, obscure or modify:

The Facebook favicon

The links to the logged in user and logout
The user's profile picture
The checkbox to let the user agree to publish the comment on their profile
The Post button

Attributes
48 | P a g e

Required Name

Type

Description

optional xid

string

The unique identifier for this set of comments. Comments can contain alphanumeric characters (Aa-Zz, 0-9), hyphens (-), percent
(%), period (.), and underscores (_) (in effect, the result of any urlencode can be a valid XID). Facebook recommends you specify
an xid; otherwise any extra GET params that are added after the URL, before the hash, will be made into the XID and the
Comments Box will "swap" whenever parameters are appended/changed. (Default value is URL-encoded URL of the page
without the hash.)

numposts int

The maximum number of posts to display (must be positive). (Default value is 10.)

width

string

The width of the Comments Box in pixels. (Default value is 550px.)

css

string

The URL to your own stylesheet.

title

string

This is the title of the Feed story that gets published when a comment is made. (Default value is the title of the Web page
containing the Comments Box.)

url

string

The URL to the page where the comment was made. (Default value is window.document.location.href.)

simple

bool

When true, a rounded box does not appear around each post on your site. (Default value is false.)

reverse

bool

When true, reverses order of comments so the most recent one appears at the bottom of the list and the composer appears at the
bottom of the page. (Default value is false.)

quiet

bool

When true, ensures that posts to this board don't send any notifications. By default, they are automatically sent to the last n
commenters. (Default value is false.)

Examples
<fb:comments
numposts="4" title="My Blog Comments"
css="http://www.yourwebsite.com/css/comments.css?1234"
simple="1"></fb:comments>

See Also

fb:comments
Comment FQL Table

49 | P a g e

Comments Box - Social Widget that shares xids with fb:comments.

Comments Box Sample Site
Developer blog post with video introduction to the Comments Box
Comments API

Fb:live-stream
Description
Use this tag to render a Live Stream Box social widget on your FBML canvas pages or Facebook Connect sites.
Note: If you have an IFrame application, you can render the Live Stream Box in an <iframe> tag. See Live Stream Box for details.

Attributes
Required Name

Type

Description

required event_app_id string This is the application ID from the application you just created above. You must specify either the application ID or the API
key.
string

The API key from the application you just created above. You must specify either the application ID or the API key.

optional width

int

The width of the box in pixels. (Default value is 450 pixels.)

height

int

The height of the box in pixels. (Default value is 400 pixels.)

xid

string

If you want to have multiple Live Stream Boxes on your canvas pages, specify a unique XID for each box. Specify
xid=EVENT_NAME, where EVENT_NAME represents the event. EVENT_NAME can include only numbers, letters, and
underscores. (Default value is default.)

apikey

50 | P a g e

Examples
For an FBML canvas page:
<fb:live-stream event_app_id="YOUR_APPLICATION_ID" width="400" height="500"/>

For
a Facebook Connect site:
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:fb="http://www.facebook.com/2008/fbml">
<head></head> <body> <div> YOUR PAGE CONTENT
</div> <fb:live-stream width="400"
height="500"></fb:live-stream> <script
src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php"
type="text/javascript"></script> <script
type="text/javascript"> FB.init("YOUR_API_KEY_HERE",
"xd_receiver.htm"); </script>
</body>
</html>

Notes
Important: If you want to place a Live Stream 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:live-stream tag where
you want the Live Stream Box to appear. As in:
<fb:live-stream width="400" height="500"></fb:live-stream>

See Also
51 | P a g e

Live Stream Box

F. Platform Internationalization

Fb:date
Description
Renders a date. This will adjust the date format correctly depending on the locale settings of the viewing user.
Format Name

English Example

Spanish Example

long_numeric

07/15/2008

15/07/2008

short_numeric

7/15

15/07

verbose

Tuesday, July 15, 2008

martes, 15 de julio de 2008

monthname_year

July 15, 2008

15 de julio de 2008

monthname

July 15

15 de julio

long_numeric_time

07/15/2008 6:14pm

15/07/2008 18:14

short_numeric_time

7/15, 6:14pm

15/07 18:14

verbose_time

Tuesday, July 15, 2008 at 6:14pm

martes, 15 de julio de 2008 a las 18:14

monthname_year_time

July 15, 2008 at 6:14pm

15 de julio de 2008 a las 18:14

monthname_time

July 15 at 6:14pm

15 de julio a las 18:14

Attributes
Required
required

52 | P a g e

Name

Type

Description

int

The time to render, in POSIX time_t format (that is, seconds since midnight on January 1, 1970 GMT)

optional

format

string

Which format to use. The available formats are listed in the table in the Description above. (Default value is verbose_time.)

tz

string

The time zone to use when rendering the date/time. Default is the logged-in user's time zone.

Examples
<fb:date t="1216170865" format="long_numeric" />
Displays "07/15/2008" for users viewing Facebook in American English, "15/07/2008" for most European language users, "2008 7 5 " for Chinese and
Japanese users, etc.

<fb:date t="0" format="monthname_time" tz="GMT" />

Displays "January 1 at 12:00am" for users viewing in American English, "1 January at 00:00" for users in British English, etc.

<fb:date t="0" format="monthname_time" tz="PST" />

Displays "December 31 at 4:00pm" for users viewing in American English, "31 December at 16:00" for users in British English, etc.

Notes
Be aware of the fact that date formats can vary substantially in length between locales. Don't assume that if you leave just enough space in your layout for an
English date, you will have enough room for dates in all languages; you probably won't.

See Also
fb:time

53 | P a g e

Fb:fbml-attribute
Description
Contains the value of an attribute of an FBML tag.
This is an alternate way to specify attributes for FBML tags. Use this tag in cases where you want to mark some user-visible text as translatable. Since it is not
permitted to nest fb:intl tags inside attributes, the values need to be moved to the body of an fb:fbml-attribute tag directly beneath the tag being modified.

Attributes
Required
required

Name

Type

Description

name

string

The name of the attribute.

Examples
Non-translatable tab label:
<fb:tab-item href="..." title="Education" />

Translatable equivalent:
<fb:tab-item href="...">
<fb:fbml-attribute name="title">
<fb:intl desc="Name of tab with education details">Education</fb:intl>
</fb:fbml-attribute>
</fb:tab-item>

Non-translatable editor button:

54 | P a g e

<fb:editor-button value="Add" name="add" />

Translatable equivalent:
<fb:editor-button name="add">
<fb:fbml-attribute name="value">
<fb:intl desc="Button: Add an item to a list">Add</fb:intl>
</fb:fbml-attribute>
</fb:editor-button>

See Also

fb:intl

Translating Platform Applications

*** Fb:intl
Description
Marks a string of English text as translatable into other languages. The text will appear in the user's language if it has been translated, and will be recorded in
your application's list of translatable strings if not already present. For more information, see Translating Platform Applications.
To incorporate variables into the text, your text should contain tokens, which are delimited by curly braces (by default) and act as placeholders. The tokens are
replaced at display time with corresponding values from fb:intl-token tags enclosed by this tag. Use tokens and fb:intl-token instead of directly including your
dynamic values in the text itself; otherwise each dynamic value will have to be individually translated. See the examples below. Any tokens with numbers or
dates as their values will be automatically localized.

55 | P a g e

Your text can contain FBML and HTML tags. See the #Notes section below for more information.

Attributes
Required Name
optional desc

delimiters

Type

Description

string

Descriptive text to clarify the context in which the text is used, and the meaning if it is ambiguous. This is shown to translators in the bulk translation use
interface, among other places, and should describe the text well enough that someone can translate it without seeing it in the context of your application.
In general a piece of text should always have a description unless it is a complete sentence whose meaning would be clear to a user who has never seen
your application.

string

Text may contain tokens to represent variables (dynamically generated values). Tokens are normally delimited by open and close curly braces, e.g.,
{name}. This attribute allows you to use alternate characters. Its value must be two characters long; the first character marks the start of a token and the
second marks the end. These two characters must be distinct.

Examples
<fb:intl>Click the red button to continue.</fb:intl>
This text is self-explanatory and is a complete sentence including ending punctuation, so a translator will be able to correctly translate it even without a
description.

<fb:intl desc="Label for a form field for entering the name of a restaurant">Name:</fb:intl>
Here the description tells the translator both where the text appears (as a form label) and what it refers to (a restaurant, as opposed to a person.) Thanks to the
description, a translator can choose the correct word here even in languages that have a different word for "name" depending on whether the name is a
person's or a place's.

<fb:intl>You have {number} new messages.

<fb:intl-token name="number">5</fb:intl-token>
</fb:intl>

56 | P a g e

The token "{number}" is replaced by the contents of the <fb:intl-token> tag with the same name.

<fb:intl>Click {here} to continue.

<fb:intl-token name="here">
<a href="...">
<fb:intl desc="In 'Click here to continue'">here</fb:intl>
</a>
</fb:intl-token>
</fb:intl>
The link text is translatable, but the link target is not. See the Notes section for more on this technique.

Notes
Tokens and Dynamic Text
Since every unique piece of text inside an <fb:intl> tag is entered into the database of translatable phrases, you should be careful to use tokens for values that
change depending on context. For example, an application dealing with events might display a message like, "Your event starts at 6:15." A simple (and
incorrect) approach is to insert the time directly into your text and wrap the result in <fb:intl>, like so:
<fb:intl>Your event starts at 6:15.</fb:intl>
This will cause "Your event starts at 6:15." to appear in the Translations application. But then, when the next user sees the same message with a time of 8:30,
this approach will cause a separate translatable string ("Your event starts at 8:30.") to be added to the database. You will effectively be asking your volunteer
translators to translate hundreds of versions of that message for all the possible time values. The problem gets even worse when you're dealing with something
less constrained than time, such as people's names -- there will be a potentially infinite amount of work for translators to do, and your application will never be
fully translated.
The correct way to do this is to use a token for the part of the text that can change from request to request:
<fb:intl>
Your event starts at {time-of-day}.

57 | P a g e

<fb:intl-token name="time-of-day">6:15</fb:intl-token>
</fb:intl>
Only the text inside the <fb:intl> tag gets inserted into the translatable strings database, and the contents of the <fb:intl-token> are inserted at display time. Now
your translators only have to translate this sentence once.
It is perfectly legal to nest <fb:intl> tags inside <fb:intl-token> tags; this is used when making link text translatable, and will be described below.
HTML Tags, Including Links
Your translatable strings may contain HTML tags. HTML tags are included verbatim in the translatable text, and translators will be free to rearrange them or get
rid of them as they see fit. For that reason, you should only include tags that indicate emphasis -- <b>, <i>, and so on. Tags such as <div> or, worst of all, <a>,
should never be included in your translatable text. Instead, use a token to denote a link, like this:
<fb:intl>
Click {here} to update your settings.
<fb:intl-token name="here">
<a href="settings.jsp">
<fb:intl desc="In 'Click here to update your settings.'">here</fb:intl>
</a>
</fb:intl-token>
</fb:intl>

The enclosing translatable string ("Click {here} to update your settings.") does not contain any HTML tags; the "{here}" token represents the link. The value of
the token is the opening <a> tag (which is not translatable), followed by the translatable word "here" with a desc that describes the context in which it appears,
followed by the closing </a> tag (which is not translatable.) Translators will translate the enclosing sentence and put the token in the appropriate place in the
translated sentence, and will also translate the word "here", but will not ever see the <a> tag in the translation tool.
Use this technique for any HTML markup that is functional rather than grammatical in nature, as well as for things like images that you want to display inline:
<fb:intl>
You have won a {medal-picture} gold medal!
<fb:intl-token name="medal-picture>

58 | P a g e

<img src="medal.png" />

</fb:intl-token>
</fb:intl>

If a tag has an attribute (such as a caption or title) that needs to be translatable, render the tag with fb:tag, which allows you to embed <fb:intl> tags in the
attribute value. See fb:tag for more details.
You should almost always put structural elements outside <fb:intl> tags, since you won't want translators rearranging your page.
For example, do this:
<div class="section_header"><fb:intl>About This Application</fb:intl></div>
But don't do this:
<fb:intl><div class="section_header">About This Application</div></fb:intl>
FBML Tags
Your translatable strings may also contain FBML tags. These are treated differently than regular HTML tags, since they usually involve dynamic content. In
general, FBML tags are divided into two categories: Tags like fb:name that can output arbitrary text and markup, and enumerable tags like fb:pronoun that
always output one of a fixed set of values. The FBML interpreter handles these two types of tags very differently.
The FBML interpreter automatically turns tags such as fb:name into tokens in your translatable text, and uses the output of the tag as the token value.
For example:
<fb:intl>You are <fb:name uid="12345" />'s best friend.</fb:intl>
Results in the following text in the Translations application:
You are {name}'s best friend.
This is done so that translators can translate the sentences without knowing anything about FBML tags. You may freely change the attributes of the <fb:name>
tag here; for example, no matter which user ID you use, the same translation will be looked up.
Most FBML tags fall into this first category.

59 | P a g e

The second category, whose most common member is the <fb:pronoun> tag, is handled very differently. If you have the following text:
<fb:intl><fb:pronoun uid="12345" capitalize="true"/> sent you a message.</fb:intl>
This is actually turned into three separate entries in the translation database:
She sent you a message.
He sent you a message.
They sent you a message.
This allows the sentence to be translated correctly in languages where the verb "sent" needs to change depending on the gender of the subject.
The two styles of tags can, of course, be combined:
<fb:intl>
<fb:name id="12345" /> has sent <fb:pronoun id="12345" possessive="true" /> best wishes.
</fb:intl>
This causes three separate entries to be created in the translation database:
{name} has sent her best wishes.
{name} has sent his best wishes.
{name} has sent their best wishes.

See Also

Fb:fbml-attribute for text within HTML attributes

Fb:intl-token
60 | P a g e

Description
Contains an attribute that replaces a token (variable) in the text of an fb:intl tag. This tag must be a direct child of anfb:intl tag.
See fb:intl for more usage notes and examples.

Attributes
Required Name Type
required name

string

Description
The name of the token that should be replaced with the contents of this tag. Do not include the token delimiters (curly braces by default) in the name.

Examples
<fb:intl>You have {number} new messages.
<fb:intl-token name="number">5</fb:intl-token>
</fb:intl>
The token {number} is replaced by the contents of the fb:intl-token tag with the same name.

<fb:intl>Click {here} to continue.

<fb:intl-token name="here">
<a href="...">
<fb:intl description="In 'Click here to continue'">here</fb:intl>
</a>
</fb:intl-token>
</fb:intl>
The link text is translatable, but the link target is not.

61 | P a g e

Notes

Each instance of this tag should have a unique name. If the same name is used twice, the interpreter may select either value.

fb:name and fb:pronoun are specific exceptions, in that you may use them inline for fb:intl, and they do not need to be wrapped by fb:intl-token.

An fb:intl-token tag with a name that doesn't correspond to a token in the text of the parent fb:intl tag will be ignored.

See Also
fb:intl

Fb:tag
Description
Renders an HTML tag. This is most commonly used in conjunction with fb:intl to put translatable text in an attribute of an HTML tag.
You specify the attributes for the HTML tag in fb:tag-attribute tags directly under this tag. The fb:tag-body tag, if present, holds the contents of the tag.
Note this tag applies only to HTML. FBML-specific elements should use fb:fbml-attribute instead.

Attributes
Required
required

62 | P a g e

Name

Type

Description

name

string

The name of the HTML tag to render.

Examples
<fb:tag name="img">
<fb:tag-attribute name="src">http://myhost/image.png</fb:tag-attribute>
<fb:tag-attribute name="alt">
<fb:intl>FooCorp company logo</fb:intl>
</fb:tag-attribute>
</fb:tag>
This renders as <img src="http://myhost/image.png" alt="FooCorp company logo" /> in English. In other languages the value of the alt attribute will be replaced
with an appropriate translation, provided someone has translated the original string.

<fb:tag name="div">
<fb:tag-attribute name="class">user_info</fb:tag-attribute>
<fb:tag-attribute name="title">
<fb:intl>
<fb:name uid="12345"/> has {number} friends.
<fb:intl-token name="number">15</fb:intl-token>
</fb:intl>
</fb:tag-attribute>
<fb:tag-body>
<fb:intl>
<fb:name uid="12345"/> is in first place.
</fb:intl>
</fb:tag-body>
</fb:tag>
A more complex example, a div with a tooltip whose text has dynamic content. This renders as <div class="user_info" title="John Smith has 15 friends.">John
Smith is in first place.</div> in English.

63 | P a g e

See Also

fb:intl

fb:tag-attribute

fb:tag-body

fb:fbml-attribute (for translating the attributes of FBML tags)

Fb:tag-attribute
Description
Contains the value of an attribute of an HTML tag specified by fb:tag. This tag is always a child of fb:tag; see fb:tag for more usage examples.

Attributes
Required
required

Name

Type

Description

name

string

The name of the attribute.

Examples
<fb:tag name="img">
<fb:tag-attribute name="src">http://myhost/image.png</fb:tag-attribute>
<fb:tag-attribute name="alt">
<fb:intl>FooCorp company logo</fb:intl>
</fb:tag-attribute>

64 | P a g e

</fb:tag>
This renders as <img src="http://myhost/image.png" alt="FooCorp company logo" /> in English. In other languages the value of the alt attribute will be replaced
with an appropriate translation, provided someone has translated the original string.

See Also

fb:tag

fb:tag-body

Fb:tag-body
Description
Contains the body (contents) of an HTML tag specified by fb:tag. This tag is always a child of fb:tag.

Examples
<fb:tag name="div">
<fb:tag-attribute name="class">user_info</fb:tag-attribute>
<fb:tag-attribute name="title">
<fb:intl>
<fb:name uid="12345"/> has {number} friends.
<fb:intl-token name="number">15</fb:intl-token>
</fb:intl>
</fb:tag-attribute>
<fb:tag-body>

65 | P a g e

<fb:intl>
<fb:name uid="12345"/> is in first place.
</fb:intl>
</fb:tag-body>
</fb:tag>
A complex example of a div with a tooltip whose text has dynamic content. This renders as <div class="user_info" title="John Smith has 15 friends.">John Smith
is in first place.</div> in English.

See Also

fb:tag

fb:tag-attribute

G. Tools

Fb:board
Description
This tag is currently in beta. It is available for all applications. Please post any bugs in bugzilla.
Displays a discussion board with a unique identifier. Facebook handles pagination, topic display, posting and storage.
Fb:board is a Facebook discussion board for developers to drop onto canvas pages easily. It is not designed to be fully extensible or for the developer to get the
data in the posts. Using the tag implies a board exists that can be posted on identified by the passed xid. Please note the following:

66 | P a g e

Every pageload for posting, see all page, and so forth refetches the configuration from the callbackurl supplied. The callbackurl defaults to the page
where it was originally found, so the tag should work without any extra coding. However, you can point a callbackurl to a special page that can be more
efficient, if you so desire.

An fb_sig_xid parameter is passed to these pages. Facebook looks for this xid when using this board. You can use it to short-circuit your application logic
and only output the fb:board tag with the proper parameters.

When an action occurs, the page is also passed an fb_sig_xid_action parameter. If you return true for the action requested in the fb:board tag, you can
assume the action was performed. Possible values are: new_topic, new_post, edit_topic, edit_post, delete_topic, delete_post,mark_irrelevant, mark_relevant.
These actions correspond respectively to these parameters: cancreatetopic, canpost, cancreatetopic,canpost, candelete, candelete, canmark, canmark.

The refetch is in the form of a POST to the URL supplied in the callbackurl, mimicking a canvas page.

Note that some attributes may be ignored for the user acting on his or her own post.

Attributes
Required Name

Type

Description

required xid

string

The unique identifier for this board. The board name can contain alphanumeric characters (Aa-Zz, 0-9), hyphens (-) and underscores (_) only.

optional canpost

bool

Indicates whether the viewing user can post on this board. (Default value is true.)

candelete

bool

Indicates whether the viewing user can delete any post or topic on this board. (Default value is false.)

canmark

bool

Indicates whether the viewing user can mark a post as relevant or irrelevant. (Default value is false.)

cancreatetopic

bool

Indicates whether the viewing user can create a topic on this board. (Default value is true.)

numtopics

int

The maximum number of topics to show in the box. (Default value is 3.)

callbackurl

string

The URL to refetch this configuration. (Default value is the current page.)

returnurl

string

The URL where the user is returned after selecting a "back" link. (Default value is the current page.)

Examples
<fb:board xid="titans_board"
canpost="true"

67 | P a g e

candelete="false"
canmark="false"
cancreatetopic="true"
numtopics="5"
returnurl="http://apps.facebook.com/myapp/titans/">
<fb:title>Discuss the Titans</fb:title>
</fb:board>

Notes

This tag works on application canvas pages only and not in other integration points like profile boxes.

This tag may contain fb:title

Fb:chat-invite
Description
Enables your users to initiate Facebook Chat with their friends from within your applications.
This tag renders a list of the current user's friends on your canvas page. When the user selects a friend, a Facebook Chat window opens, and can display a prepopulated message in the text field. This way your users can interact in real time with each other, whether to play a game with each other or to collaborate with
a productivity tool.

68 | P a g e

It's best that you make the message concise, and if you include a URL, keep it as short as possible.

Detecting a User's Online Status

69 | P a g e

Detecting a user's online status can help you present a more concise and useful Chat invite. You can determine whether a user's friends are online by checking
for the online_presence setting in the user FQL table. If a friend is not online, you can put that friend's UID in the exclude_idsarray (see below) so that friend
doesn't appear in the Chat invite.

Rendering the Invite with FBJS (for Flash-based Applications)

You can use FBJS to render the Chat invite on your canvas page. This is useful for non-page-based applications (especially Flash applications and games).
To render a chat-invite from FBJS, use fb:js-string together with setInnerFBML(). See the Examples for sample code.

Positioning the Chat Invite Tool Over an IFrame

If you're rendering iframes in an FBML application with the fb:iframe tag, you can use CSS to overlay the Chat invite over the iframe rendered by fb:iframe. You
need to add some styling to the div tag. See theExamples for sample code.

Incorporating Live Message (Advanced)

Another way you can communicate with your users and their friends is to use the Chat invite tag with the Live Message feature. This way, you can update the
page of the user who initiated the chat with some sort of message.
For example, say your chat invitation text contains a URL that allows the recipient of the chat invite to join a game when clicked. When the recipient clicks the
link in the invite, the next page load would trigger a call to liveMessage.send, which sends a message to the sender's page. This message would invoke an
FBJS callback (for example, to a function called. 'onFriendJoin()') which would inform the sender the friend has joined the game; you could even change the
page to bring the sender into the game.
Note: The LiveMessage feature is currently in beta.

Attributes
70 | P a g e

Required Name

Type

Description

required msg

string

The default message that gets sent to the friend along with the chat invite. You can use plain text only here. However, if you include a URL, it gets
formatted properly as a hyperlink.

optional condensed

bool

Indicates whether to display the user's profile pic and name, or just the user's name. (Default value is false.)

array

A comma-separated list of user IDs to exclude from the chat invite (like you can do with fb:multi-friend-selector).

exclude_ids

Examples
<fb:chat-invite msg="let's play a game!" condensed="false" exclude_ids="1,2,3"/>

Rendering fb:chat-invite with FBJS

<fb:js-string var="chatInvite">
<fb:chat-invite msg="let's play a game!" condensed="false" exclude_ids="1,2,3"/>
</fb:js-string>
<div id="chat_invite_container"></div>
<script>
document.getElementById('chat_invite_container').setInnerFBML(chatInvite);
</script>

Positioning the Chat Invite Tool Over an IFrame

<fb:js-string var="chatInvite">
<fb:chat-invite msg="let's play a game!" condensed="false" exclude_ids="1,2,3"/>
</fb:js-string>
<div id="chat_invite_container" style="position: absolute; left: 200px; top: 300px"></div>
<script>
document.getElementById('chat_invite_container').setInnerFBML(chatInvite);

71 | P a g e

</script>
The style attribute of the chat_invite_container div tells the browser where exactly to place the friend list, even if it's over other elements, like an iframe.

Notes

At this time, you cannot render this tag with fb:serverfbml (for iframe applications and Facebook Connect sites). However, you can use this tag in the
context of an iframe rendered with fb:iframe in an FBML application only (not with an HTML <iframe> tag) -- see Positioning the Chat Invite Tool Over an
IFrame above. We'll support fb:chat-invite in iframe applications in the future and will let you know when it's available.

This tag does not work in Internet Explorer 6.

Fb:comments
Description
Displays a set of comments for a unique identifier. Facebook handles posting, drawing, and see all page.
The fb:comments tag is essentially a Wall for developers to drop on canvas pages and application tabs on profiles easily. Using the tag implies a Wall-like
comments set exists that can be posted or identified by the passed XID. Please note the following:

Every pageload for posting, see all page, and so forth refetches the configuration from the callbackurl supplied. Thecallbackurl defaults to the page
where it was originally found, so the tag should work without any extra coding. However, you can point a callbackurl to a special page that can be more
efficient.
Note: If you render the fb:comments tag from FBJS using setInnerFBML(), you must set a callbackurl.

72 | P a g e

An fb_sig_xid parameter is passed to these pages. Facebook looks for this xid. You can use it to short-circuit your application logic and only output the
fb:comments tag with the proper parameters.

When an action occurs, the page is also passed an fb_sig_xid_action parameter. Currently this can be "post" or "delete". If you return true for the action
requested in the fb:comments tag, you can assume the action was performed.
Note: Facebook redirects immediately to the same page again after passing the post to that page - but without the post information.

The refetch is in the form of a POST to the URL supplied in the callbackurl, mimicking a canvas page.

You can style fb:comments arbitrarily by using overriding styles and embedding CSS (or using link tags) as described in CSS Tips and Tricks. You can
turn off the rounded-corners chrome by specifying the simple attribute below.

Comments can be published to a user's Feed only if the user checks Post comment to my Facebook profile. Previously, all comments would be
published if developer set the 'publish_feed' parameter to true.

Consider setting quiet to true. This prevents notifications from being sent to the previous commenters, who may or may not be friends with the user
making the comment.

Attributes
Required Name

Type

Description

required xid

string

The unique identifier for this set of comments. Comments can contain alphanumeric characters (Aa-Zz, 0-9), hyphens (-), percent (%), period
(.), and underscores (_) (in effect, the result of any urlencode can be a valid XID).

canpost

bool

Indicates whether the viewing user can post on this comment set.

candelete

bool

Indicates whether the viewing user can delete any post on this comment set. Any user visiting that user's profile where the comment appears
can delete comments made to it (so, avoid using candelete unless this is the intended functionality).

numposts

int

The maximum number of posts to display (must be positive).

string

The URL to refetch this configuration. (Default value is the current page.)
Note: If you render the fb:comments tag from FBJS using setInnerFBML(), you must set acallbackurl.

returnurl

string

The URL where the user is returned after selecting a "back" link. (Default value is the current page.)

showform

bool

Boolean whether to show the form (canpost "true" only) for inline posting. Posts using this form will not go to a see-all page after posting, bu
rather refresh the page.

send_notification_ui

int

User ID to send a notification to upon someone posting a comment. (Only one uid allowed).

optional callbackurl

73 | P a g e

d
publish_feed

bool

Indicates whether to publish a Feed story when the comment gets posted. The comment must be at least 5 words in length in order to be
published to Feed.
Note: The comment can be published to a user's Feed only if the user checks Post comment to my Facebook profile.

simple

bool

Removes the rounded box around the text area to allow greater customization.

reverse

bool

Changes the order of comments and comment area to allow greater customization.

quiet

bool

When true, ensures that posts to this board don't send any notifications. By default, they are automatically sent to the last n commenters,
whether or not they are friends with the user currently posting the comment. (Default value is false.)

Examples
<fb:comments xid="titans_comments" canpost="true" candelete="false"
returnurl="http://apps.facebook.com/myapp/titans/">
<fb:title>Talk about the Titans</fb:title>
</fb:comments>

Code Snippet - Tracking the Comment Count

Notes

This tag works on application canvas pages and application tabs on profiles only, but not in other integration points like profile boxes. Theuid passed to
the tab link for FBML generation is the profile owner's user ID, not the viewer's user ID.

This tag may contain fb:title.

This tag works on its own; don't use it with fb:wall.

See Also
74 | P a g e

Comment FQL Table

Comments Box - Social Widget that shares XIDs with fb:comments.

fb:comments (XFBML) - XFBML tag used for rendering fb:comments in iframe applications and on external sites.

Comments API

Fb:feed
Description
Renders an application-specific News Feed, which displays recent application stories about the logged in user's friends. This tag is in beta, and is only available
on canvas pages.

Attributes
Required
optional

Name

Type

Description

title

string

The title that should be published at the top of an application's News Feed. (Default value is News Feed.)

max

int

The maximum number of stories that should be displayed in the News Feed.

Examples
<fb:feed/>

75 | P a g e

<fb:feed title="Events News Feed" max="5"/>

76 | P a g e

Fb:friend-selector
Description
Renders a predictive friend selector input for a given person. You can use this tag inside an fb:request-form to select users for whom a request can be sent.

Attributes
Required Name

Type

Description

int

The user whose friends you can select. (Default value is the uid of the currently logged-in user.)

name

string

The name of the form element. (Default value is friend_selector_name.)

idname

string

The name of the hidden form element that contains the user ID of the selected friend. If you are using this tag inside fb:request-form, do not override
the default. (Default value is friend_selector_id.)

include_me

bool

Indicates whether or not to include the logged in user in the suggested options. (Default value is false.)

exclude_ids

array

A list of user IDs to exclude from the selector. (comma-separated)

include_lists

bool

Indicates whether or not to include friend lists in the suggested options. (Default value is false.)

optional uid

77 | P a g e

Examples
<fb:friend-selector uid="123445" name="uid" idname="friend_sel" />

Notes
If the user enters a name that does not match any of his friends, idname gets set to an empty string (instead of a uid number) and name gets set to the

entered text.
If no value is entered then idname is not added as a hidden field in the POST.

Bugs
If a valid friend is entered and selected from the drop-down completion, the idname gets set to that person's uid and remains as that value unless another

valid friend is entered. This means, if I enter a valid friend and then delete the entry to make it blank (or a non-friend), it sends that previous
friend's uid in idname, but sends a blank string (or the non-friend's name) in name.
Just check if the name is empty. People don't usually submit a half-typed friend's name.

Even better. Put a parent element around the selector. On submit, use parent.getFirstChild().hasClassName('typeahead_found') to check

if the user really meant to submit that friend. You could then use your own hidden field to mark the selector output to be ignored.

See Also
You can see a real world example of this tag in the Footprints demo application. Go to Demos for more details and to download and install the demo apps.

78 | P a g e

Fb:google-analytics
Description
Inserts appropriate Google Analytics code into a canvas page.

Attributes
Required Name

Type

Description

required uacct

string

Your Urchin/Google Analytics account ID.

optional page

string

The argument given to the urchinTracker() function, either a page or a virtual page.

ufsc

bool

Sets client info flag, where 1=on and 0=off. This is a UTM user setting. (Default value is 1.)

udn

string

Sets the domain name for cookies. Specify auto, none or domain. This is a UTM user setting. (Default value is auto.)

uhash

string

Specify whether the unique domain hash for cookies is on or off. This is a UTM user setting. (Default value is on.)

utimeout

int

Sets the inactive session timeout in seconds. This is a UTM user setting. (Default value is 1800.)

ugifpath

string

Set the Web path to the __utm.gif file. This is a UTM user setting. (Default value is /__utm.gif.)

utsp

string

The transaction field separator. This is a UTM user setting. (Default value is | (a pipe character).)

uflash

bool

Sets the Flash version detection option, where 1=on and 0=off. This is a UTM user setting. (Default value is 1.)

utitle

bool

Sets the document title detection option, where 1=on and 0=off. This is a UTM user setting. (Default value is 1.)

ulink

bool

Enables linker functionality, where 1=on and 0=off. This is a UTM user setting. (Default value is 0.)

uanchor

bool

Indicates whether the use of anchors for campaigns is enabled, where 1=enabled and 0=disabled. This is a UTM user setting. (Default value is 0.)

utcp

string

Specifies the cookie path for tracking. This is a UTM user setting. (Default value is /.)

usample

int

Represents the sampling percentage of visitors to track, which is a whole number from 1 to 100. This is a UTM user setting. (Default value is 100.)

uctm

bool

Sets the campaign tracking module state, where 1=on and 0=off. This is a UTM campaign tracking setting.(Default value is 1.)

ucto

int

Sets the timeout in seconds. This is a UTM campaign tracking setting. (Default value is 15768000, or 6 months.)

uccn

string

The name of the campaign. This is a UTM campaign tracking setting. (Default value is utm_campaign.)

79 | P a g e

ucmd

string

Represents the campaign medium. Specify cpc, cpm, link, email or organic. This is a UTM campaign tracking setting. (Default value is utm_medium.)

ucsr

string

Represents the campaign source. This is a UTM campaign tracking setting. (Default value is utm_source.)

uctr

string

The campaign term or keyword. This is a UTM campaign tracking setting. (Default value is utm_term.)

ucct

string

Represents the campaign content. This is a UTM campaign tracking setting. (Default value is utm_content.)

ucid

int

Represents the campaign ID number. This is a UTM campaign tracking setting. (Default value is utm_id.)

ucno

string

Indicates whether or not to override the campaign. This is a UTM campaign tracking setting. (Default value is utm_nooverride.)

Examples
Inserting:
<fb:google-analytics uacct="UA-9999999-99" />

Yields:
<script src="https://ssl.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-9999999-99";
urchinTracker();
</script>

Notes

This tag can only be used on canvas pages.

The urchinTracker function provided by Google Analytics can be accessed in FBJS through Facebook.urchinTracker. To enable, include something
similar to the following:

80 | P a g e

<a href="http://www.example.com" onclick="Facebook.urchinTracker('/outgoing/example.com')">

You must include the <fb:google-analytics> tag on your page if you're going to call Facebook.urchinTracker in FBJS

See Also
Google Analytics Example

Fb:if
Description
Only renders the content inside the tag if value tag is set to true.

Attributes
Required
optional

Name

Type

Description

value

bool

Displays content if true. (Default value is false.)

Examples
<fb:if value="true">Show this content.</fb:if>

81 | P a g e

Fb:else (Sub menu @ Fb:if)

Description
Handles the else case inside any fb:if, fb:if-* or fb:is-in-network tag, and with age and location restricting tags.
Applicable tags include:

fb:if

fb:if-can-see

fb:if-can-see-photo

fb:if-is-app-user

fb:if-is-friends-with-viewer

fb:if-is-group-member

fb:if-is-own-profile

fb:if-is-user

fb:if-user-has-added-app

fb:is-in-network

fb:18-plus

fb:21-plus

fb:restricted-to

Examples
<fb:if-is-own-profile>
Welcome back to your profile!

82 | P a g e

<fb:else>This is not your profile.</fb:else>

</fb:if-is-own-profile>

Notes
You cannot use this tag inside an fb:if-section-not-added tag. This is to prevent the gating of application functionality if a user hasn't added an application info
section.

See Also
You can see a real world example of this tag in the Who's Showing Up demo application. Go to Demos for more details and to download and install the demo
apps.

Fb:if-multiple-actors
Description
Displays the enclosed content when more than one actor is involved in a Feed story. Use this tag in the templates you create with the Feed Template
Console or the feed.registerTemplateBundle method.
If two or more stories are aggregated, then the {actor} token is replaced with the names of all of the users whose actions are being aggregated.

Examples
{actor} <fb:if-multiple-actors>are<fb:else>is</fb:else></fb:if-multiple-actors> testing feed stories.

83 | P a g e

Fb:mobile
Description
Renders the contained content only when viewed on the mobile website (http://m.facebook.com). Any content outside these tags does notget rendered on the
mobile website.
For more information, read the Mobile article.

Examples
This text appears on the regular site, but not on m.facebook.com.
<fb:mobile>This text appears only on m.facebook.com.</fb:mobile>

Fb:multi-friend-input
Description
Renders a multi-friend form entry field like the one used in the message composer. You can use the field inside anfb:request-form to select users for whom a
request can be sent.
Output Adds the following hidden tag inside the form for each user with their user ID for the value.
<input type="hidden" value="123456789" name="ids[]"/>

84 | P a g e

Here is an example, in PHP, of how to access these IDs.

$friends

(isset($_REQUEST["ids"])

$_REQUEST["ids"] : null);

If users were entered into the multi-friend-input, $friends becomes an array of IDs; otherwise, $friends is null.

Attributes
Required Name

Type

Description

int

The width of entry field. (Default value is 350px.)

border_color

string

The color of entry field border. (Default value is #8496ba.)

include_me

bool

Indicates whether or not to include the logged-in user in the form. (Default value is false.)

max

int

The maximum number of people that can be selected. (Default value is 20.)

exclude_ids

array

A comma separated list of user IDs to exclude from the selector.

prefill_ids

array

A comma separated list of user IDs to pre-populate in the selector. Note that this cannot be used inside an <fb:request-form>.

prefill_locke
d

bool

Set to true to prevent editing of the pre-populated IDs.

name

bool

The name that should be given to the array of selected user IDs. This defaults to ids for the first <fb:multi-friend-input>, and
to fb_multi_friend_input_ids<n> for all by the first. In general, you should include name attributes if you include more than one <fb:multi-friendinput> in a single page.

optional width

Examples
<fb:multi-friend-input width="350px" border_color="#8496ba" exclude_ids="4,5,10,15" />

85 | P a g e

Notes

When used inside a mock AJAX form, the ID array contains only the last UID in the multi-friend-input.[possible bug?] - this actually seems to return all input ids
when using mock ajax as of 10/29-08

You can access all of the values of multi-friend-input using form serialize.

When used, it appears to disable the recipient input box on the popup for fb:share-button. [possible bug?]

When using with prefil_locked=true, the input appears to be read-only. [possible bug?]

Fb:quantcast
Description
Inserts appropriate Quantcast code into a canvas page.

Attributes
Required Name Type Description

86 | P a g e

required qacct

string Your Quantcast account ID.

optional media string Specifies a media type. Can be one of widget,video,audio,music, game,advertisement, or other. (Default value is "widget".)
labels string Specifies one or more hierarchical media labels. Multiple labels can be separated by commas and hierarchy is represented by periods. (Default value is "".)

Examples
This code:
<fb:quantcast qacct="p-123456" />

Renders as:
<script type="text/javascript" src="http://edge.quantserve.com/quant.js"
<script type="text/javascript">
_qoptions= {
"qacct":"p-123456",
"source":"fb-app"
};
quantserve();
</script>

></script>

This code:
<fb:quantcast qacct="p-123456" media="widget" labels="game.card.poker" />

Renders as:
<script type="text/javascript" src="http://edge.quantserve.com/quant.js"
<script type="text/javascript">
_qoptions= {
"qacct":"p-123456",
"media":"widget",

87 | P a g e

></script>

"labels":"game.card.poker",
"source":"fb-app"
};
quantserve();
</script>

Fb:random
Description
Randomly chooses an item inside the tags based on the weights provided.
fb:random allows the developer to input a series of tags, of which one or more are shown randomly. Each item can have a weight and the tag can be specified
to show more than one choice. Each option should be wrapped in an fb:random-option tag.

Attributes
Required
optional

Name

Type

Description

pick

int

The number of items to choose from the random subset. (Default value is 1.)

unique

bool

Indicates whether to force uniqueness if pick > 1. (Default value is true.)

Examples
<fb:random>
<fb:random-option weight="2">A: This will be shown 2 times as often as B.</fb:random-option>
<fb:random-option weight="1">B: This will be show half as often as A</fb:random-option>
</fb:random>

88 | P a g e

a screenshot is not applicable for this tag

Notes

Weights of options are relative to the number of options left, which shrinks if unique==true and pick>1.

Weights of options can be any float > 0. The weights are relative to each other, not necessarily to 1.

This tag may contain fb:random-option.

*Fb:random-option (sub = Fb:random)

Description
Contains code to be output when selected by the fb:random tag. You can control the frequency of this pick with theweight attribute.
The fb:random-option tag must be inside an fb:random tag.

Attributes
Required
optional

89 | P a g e

Name

Type

Description

weight

float

Allows for controlling the frequency of a choice. (Default value is 1.0.)

Examples
<fb:random>
<fb:random-option weight="2">A: This text appears twice as often as B.</fb:random-option>
<fb:random-option weight="1">B: This text appears half as often as A.</fb:random-option>
</fb:random>
a screenshot is not applicable for this tag

Notes

Weights of options are relative to the number of options left, which shrinks if unique==true and pick>1 in the parent fb:random tag.

Weights of options can be any float > 0. The weights are relative to each other, not necessarily to 1.

Fb:rock-the-vote
Description
Displays a Rock the Vote & CREDO Mobile registration widget inline in your application. The text inside the tags is formatted as a hyperlink. When the user
clicks the link, a US voter registration form appears. When the user is done, they are prompted to share it with their friends. Then they are returned to your
page.
This is particularly suitable for political apps or any app that wants to encourage voter registration. You can add this to a Page via the Static FBML App.

Attributes
90 | P a g e

Required Name
optional api_key

Type

Description

string

The api_key that you got from Rock the Vote to track your online voter registrations - get one athttp://www.rockthevote.com/partners. If you don't have an
api_key, one will be provided for you.

Examples
The basic widget link.
<fb:rock-the-vote>Register to vote!</fb:rock-the-vote>

Using your own api_key (replace "MY_API_KEY" with actual key).

<fb:rock-the-vote api_key="MY_API_KEY">Register to vote!</fb:rock-the-vote>

Using your own api_key and a custom image.

<fb:rock-the-vote api_key="MY_API_KEY"><img src="http://rtvmultimedia.s3.amazonaws.com/banners/468x60/rtv-468x60v1.jpg"></fb:rock-thevote>

Alternatively, you can embed the registration widget using an iframe tag so that it loads within the page automatically.
<fb:iframe src="http://www.registrationbyworkingassets.com/register/?api_key=MY_API_KEY" width="610" height="1000"
scrolling="no" />

Fb:switch
Description
91 | P a g e

Evaluates every fb: tag inside and returns the first one that evaluates to anything other than an empty string. You can use fb:default to specify a default that gets
rendered if nothing else does before it was executed.

Examples
<fb:switch>
<fb:photo pid="12345" />
<fb:profile-pic uid="54321" />
<fb:default>You can't see either the photo or the profile pic</fb:default>
</fb:switch>
Note: fb:default always returns its content. Thus, if it is the first tag within fb:switch, then no other tags get tested.

Fb:default
Description
This article or section needs expansion
For a group of fb: tags contained within an fb:switch tag, the fb:default tag renders any content inside itself if no other fb: tag inside the fb:switchtag renders
code before it.

Examples
<fb:switch>
<fb:photo pid="12345" />
<fb:profile-pic uid="54321" />

92 | P a g e

<fb:default>You can't see either the photo or the profile pic</fb:default>

</fb:switch>
a screenshot is not applicable for this tag

Fb:user-agent
Description
Displays the contents wrapped inside the tag to the specified user-agents. You can use fb:user-agent on the canvas page and the profile box. It serves as a tool
to deal with browser idiosyncrasies.
User-Agent Resources

http://www.user-agents.org/index.shtml - a list of common user agent strings

http://whatsmyuseragent.com/ - what is your user agent string?

Attributes
Required Name

Type

Description

required includes

string

A comma-delimited list of strings to test for inclusion against the HTTP request's user-agent string. If a given include string matches the user-agent string,
the content inside the include tag appears; otherwise it does not.

optional excludes

string

A comma-delimited list of strings to test for exclusion against the HTTP request's user-agent string. If a given include string matches the user-agent string,
the content inside the include tag does not appear; otherwise it does appear.

93 | P a g e

Examples
<fb:user-agent includes="ie 6,ie 7">
Hi IE 6/7 users.
</fb:user-agent>

<fb:user-agent excludes="firefox">
Hi people not using Firefox.
</fb:user-agent>

<fb:user-agent includes="mozilla" excludes="firefox/2.0">

Hi Mozilla (but not Firefox 2.0) users.
</fb:user-agent>

<fb:user-agent includes="ie" excludes="ie 6">

Hi IE (but not IE 6) users.
</fb:user-agent>

Notes
94 | P a g e

If both the includes and excludes attributes exist, the order of operation is to evaluate the includes then the excludes. For example, you can state includes="MSIE"
excludes "MSIE 6.0".

The matching is case-insensitive.

Should be used around style tags not within them.

Fb:typeahead-input
Description
This tag is currently in beta. Please post bugs in the Bug Tracker.
Creates a type-ahead tool (as suggested) that will give you the results that you specify. To add options in the input box, use fb:typeahead-option.

Attributes
Required

Name

Type

Description

required

name

string

The variable name that is sent in the POST request when the form is submitted.

optional

autocomplete

string

Set to off to prevent the browser's autocomplete feature from overriding this tag's ability to autocomplete.

size

int

The size of the input field.

value

string

The pre-selected option value.

Examples
<fb:fbml version="1.1">
<fb:typeahead-input name="your_input_name" autocomplete="off" value="default selection">
<fb:typeahead-option value="me"><fb:name uid=1160 capitalize=yes linked=no /></fb:typeahead-option>
<fb:typeahead-option value="ex">x</fb:typeahead-option>

95 | P a g e

<fb:typeahead-option>why</fb:typeahead-option>
</fb:typeahead-input>
</fb:fbml>

Notes

The tag must be wrapped in a fb:fbml tag with version 1.1.

You must name the input.

You must set autocomplete="off" to prevent the browser's autocomplete from overriding this tag's.

Known Issues

In profile boxes, the autocomplete options cannot extend beyond the edges of the box the application owns.

HTML and FBML that generates HTML inside of fb:typeahead-option is being interpreted as literal HTML

Bug Reports
A bug report was filed concerning the wrong values of the input posting.

http://bugs.developers.facebook.com/show_bug.cgi?id=1055

A bug report was filed regarding the number of inputs the typeahead can handle and the rendering of type-ahead suggestions.

http://bugs.developers.facebook.com/show_bug.cgi?id=1145

unable to use indexed name in fb:typeahead value

http://bugs.developers.facebook.com/show_bug.cgi?id=1371

needs ability to set the currently 'selected' item

96 | P a g e

http://bugs.developers.facebook.com/show_bug.cgi?id=1372

Fb:typeahead-option
Description
This tag is currently in beta. Please post bugs in the Bug Tracker.
This tag specifies the values for a typeahead form input. You must use it in conjunction with Fb:typeahead-input.

Attributes
Required
optional

Name

Type

Description

value

string

The value assigned to the fb:typeahead-input element, used in the POST request when the form is submitted.

Examples
<fb:fbml version="1.1">
<fb:typeahead-input name="your_input_name">
<fb:typeahead-option value="me"><fb:name uid=1160 capitalize=yes linked=no /></fb:typeahead-option>
<fb:typeahead-option value="ex">x</fb:typeahead-option>
<fb:typeahead-option>why</fb:typeahead-option>
</fb:typeahead-input>
</fb:fbml>

97 | P a g e

H. Misc

Fb:js-string
Description
This tag renders a block of FBML into an FBML block variable instead of rendering it on the page. You can use this variable in your JavaScript with
See FBJS for more information.

Attributes
Required
required

Name

Type

Description

var

string

A valid JavaScript identifier.

Examples
<fb:js-string var="example">Pre-rendered FBML content.</fb:js-string>
a screenshot is not applicable for this tag

<fb:js-string var="name.element1">This is the first element.</fb:js-string>

<fb:js-string var="name.element2">This is the second element.</fb:js-string>
This allows you to access name as if it were a JavaScript array.

98 | P a g e

setInnerFBML.

The array can only be one level deep, and associative names must be prefixed by at least 1 alpha character (name.5,
name.6, etc. will not work).
Real example (PHP):
<fb:js-string var="articles.id{$article['article_id']}">
Do you really want to delete article #{$article['article_id']}?<br /><br />
Associated contributors to this article will remain credited.
</fb:js-string>

<a href="#" onclick="removeArticle({$article['article_id']})">Delete Article</a><span

id="removeSpan{$article['article_id']}"></span>

<script>
function removeArticle(articleId) {
var dialog = new Dialog(Dialog.DIALOG_CONTEXTUAL);
dialog.setContext(document.getElementById("removeSpan"+articleId));
dialog.showChoice('Confirm Removal', articles["id"+articleId], 'Yes', 'Cancel');
dialog.onconfirm = function() {
document.setLocation('http://apps.facebook.com/facebookdocs/removearticle.php?article='+articleId);
};
}
</script>

99 | P a g e

Another Example - Reloading an IFrame

Let's say you have a div with an IFrame in it that you want to load different locations depending on links a user
clicks.
<a onClick="outside_location.setInnerFBML(location_two);" style="cursor: pointer;">Other IFrame Location</a>
<div id="outside_location">
<fb:iframe width="540" height="270" frameborder="0" src="http://your.default.location" />
</div>
// To reload the iFrame with a different location source you will need
// to declare the location inside of a fb:js-string object like so:
<fb:js-string var="location_two">
<fb:iframe width="540" height="270" frameborder='0' src='http://your.other.iframe.location' />
</fb:js-string>
<script type="text/javascript" charset="utf-8">
var outside_location = document.getElementById('outside_location');
</script>

***Fb:fbml***
Description
This tag serves two purposes. You can use this tag to:
1. Define a block of FBML to be rendered in a specific version of FBML.

100 | P a g e

2. Define a namespace to use with Custom Tags.

When using this tag with custom tags, the xmlns attribute defines a namespace for the custom tags registered by an application. Adding anxmlns attribute
effectively imports the custom tags from an application into a namespace of your choice within the scope of the fb:fbml tag.
The value of the xmlns attribute must be a URL of the form "http://external.facebook.com/apps/<app_name>". The <app_name> must match the name of the
registering application's name in the application's canvas URL (that is, "http://apps.facebook.com/<app_name>").
Inside fb:fbml, you can use any custom tags you registered for your application using fbml.registerCustomTags by prefixing those tags with the namespace you
selected (see Examples below).
An fb:fbml tag may have more than one xmlns property, each of which defines a different namespace.
Note: You cannot create a namespace that starts with fb or f8. This keeps the Facebook FBML namespace distinct from any custom namespace.

Attributes
Required Name
optional version
xmlns

Type

Description

float

The version of FBML with which to render the content. (Default value is [the current version].)

string

The name of the custom tag namespace. You cannot create a namespace that starts with fb or f8. You can include alphanumeric characters, underscores ("_"
and hyphens ("-"). Note: You can include multiple xmlnsattributes in one fb:fbml tag.

Examples
<fb:fbml version="1.0">
The tags that follow rely completely on FBML in version 1.0.
This is being rendered in version: <fb:fbmlversion />
</fb:fbml>

<fb:fbml version="1.2">

101 | P a g e

The tags here rely on FBML 1.2.

This is being rendered in version: <fb:fbmlversion />
</fb:fbml>

In this Custom Tags example, we (the tags consumer) imported custom tags defined by the tag creator "my_movie_app" into the namespace "movies".
<fb:fbml xmlns:movies="http://external.facebook.com/apps/my_movie_app">
<movies:gallery title="my movie gallery">
<movies:video id="7" />
</movies:gallery>
</fb:fbml>

See Also

fb:fbmlversion

Fb:fbmlversion
Description
Prints the version of FBML currently in scope. You should use this tag only for debugging purposes.

102 | P a g e

Examples
<fb:fbml version="1.0">
The tags that follow rely completely on FBML in version 1.0.
This is being rendered in version: <fb:fbmlversion />
</fb:fbml>

<fb:fbml version="1.2">
The tags here rely on FBML 1.2.
This is being rendered in version: <fb:fbmlversion />
</fb:fbml>

Notes
As you can in the above code example, the second code snippet does not work because there is no version 1.2 of FBML at this time.

See Also

fb:fbml

Fb:ref
103 | P a g e

Description
Fetches and renders FBML from a given ref source either a ref string "handle" you've created usingfbml.setRefHandle or a URL that serves FBML. You can
use this ref to publish identical FBML to a large number of user profiles and subsequently update those profiles, without having to republish FBML on behalf of
each user (that is, using profile.setFBML for each user). For a high level discussion of the benefits of fb:ref and how to use it, read this forum post

Attributes
Required Name Type
required url
handle

Description

string

The URL from which to fetch the FBML. Facebook caches the content retrieved from that URL until you callfbml.refreshRefUrl. You must specify
either url or handle, but not both.

string

The string previously set by fbml.setRefHandle that identifies the FBML. You must specify either url or handle, but not both.

Examples
Using Key/Value Pairs
When using key/value pairs, Facebook stores developer-specified FBML on its servers in the form of a hashtable.
To set the FBML code of

YourHandle,

you must call

fbml.setRefHandle

at least once.

fbml.setRefHandle("YourHandle", "FBML_Content")

Next, include the FBML referenced by the handle. Insert the

<fb:ref handle="YourHandle" />

104 | P a g e

<fb:ref>

tag into the appropriate place in your markup:

Using the URL Attribute

When using

fb:ref

with the

url

attribute, Facebook downloads the specified URL, caches the result, and parses the FBML,

passing it to the user.

To include the specified FBML, insert the

<fb:ref>

tag into the appropriate place in your markup:

<fb:ref url="http://www.mysite.com/someurl.php" />

To clear the cache, call fbml.refreshRefUrl:

fbml.refreshRefUrl("http://www.mysite.com/someurl.php")

Notes
Performance
If you have to update a large number of refs, you want to be using handle refs, since you can do it with a single push, rather than URL refs, which will hammer
your server on the callback.[verify] You may also want to stream out your updates in parallel, which can be easily accomplished by using curl_multi instead of curl
in the PHP5 facebook rest client. There's a guide available for this.
Cache Expiration
As mentioned within a forum thread by a member of the Facebook team: "You only need to publish on update. We'll keep it otherwise."
So the cache never expires and you will not need to periodically update your application cache. Facebook will keep the cache indefinitely. However, developers
should not rely on the cache always keeping their data i.e. it is not safe to assume that once data has been cached (in the case of a URL ref), it can be
deleted from your server.
Nested Refs
The contents of a ref handle can contain FBML, including other <fb:ref> tags.

105 | P a g e

Warning: An infinite nesting can be created by creating two ref handles that refer to each other. Do not do this.
FBML Anomalies in Refs This writer has not been able to successfully create mock-Ajax forms inside of ref handles [possible bug?] (but that does not necessarily
mean they don't work).

See Also

Changing profile content

( Changing profile content

Introduction
Applications that a user has added may add content to the user's profile page. [insert note about profile item insertion checkbox during add app process]
Your widget can't make a request with every profile load: all markup inserted by your API call will be cached (a 'push' model). However, if the user interacts with
your widget (e.g. submits a form) you can trigger a content change, and may use mock ajax to do so.
Flash applications will not start automatically.
You can either:

Make a call that updates an individual user's profile content (direct)

Insert a 'reference handle' into the user's profile, for which you'll provide the markup in another call (indirect).

The indirect method is better when multiple users have the same content, because you can give them all the same handle.

Direct
106 | P a g e

profile.setFBML( markup: <markup>, uid: <uid> )

setFBML()

lets you directly insert FBML into the profile widget. You need an infinite session key to do this, but it doesn't have to be the session key of the user

whose page you wish to update. Your own key will do. Markup is restricted and will be cached. For more information, seesetFBML
PHP:
old - $facebook->api_client->profile_setFBML( $markup, $uid );
new - $facebook->api_client->profile_setFBML( null, $uid, $fbml_profile, null, $fbml_mobile, $fbml_main);

Note: The above new reference no longer includes the $profile_action parameter, which was deprecated. The client library needs to be updated.
Perl:
old - $facebook->profile->set_fbml( profile => $markup, uid => $uid );
new - $facebook->profile->set_fbml( profile => $markup, uid => $uid, profile_main => $main_markup );

Indirect
Usage Example
You have 1,000 users. Each gets listings of upcoming concerts according to their city. Using profile_setFBML, when your listings update, you'd have to make
1,000 calls to set the content for each user. On the other hand, if you set a handle like "city_boston" on the user's profile when they add your app, you can
update the profile widget for every user in Boston with one API call.

<fb:ref handle="UNIQUE_HANDLE_HERE" />

Using the direct method, above, place one or more <fb:ref handle> tags on the user's profile. Now each time you want to update the user's profile, you just need
to set the value of the handle.
Handy Hint: This method's beauty is in using non-unique handles. Place a global and a unique handle on everyone's page and you have the ability to set a
global message at any time you want to.

107 | P a g e

<fb:ref handle="global_announcement" /><fb:ref handle="$user_id" />

You could also distinguish groups of users and add a handle for that group. Then every time you want to update everyone in that group, you have a handle.
Each app has its own handle namespace.

Updating the handle

To update the handle, you once again need an infinite session. Use your own.
facebook.fbml.setRefHandle( handle: <handle>, markup: <markup> )

This will update the profile of every user that has the given <handle> and replace the fb:ref tag with the <markup> (Note: It will not remove content placed by
other handles)
PHP:
$facebook->api_client->fbml_setRefHandle($handle, $markup);

Perl
$facebook->fbml->set_ref_handle( handle => $handle, fbml => $markup );

<fb:ref url="http://www.mysite.com/update.php?handle=UNIQUE_HANDLE_HERE" />

The alternate to using a handle, is to set the FBML as above, but with a callback URL. Then, using refreshRefUrl(), you can have Facebook call your URL to
create the FBML.
Handy Hint: This option is particularly useful if you already have an interface for setting the profile code on your canvas page. That interface can be re-used to
answer to this call.

108 | P a g e

Updating the handle

To update the handle, you once again need an infinite session. Use your own.
facebook.fbml.refreshRefUrl( url: <url> )

PHP:
$facebook->api_client->fbml_refreshRefUrl("http://www.mysite.com/update.php?handle=UNIQUE_HANDLE_HERE")

Perl:
$facebook->fbml->refresh_ref_url( url => "http://www.mysite.com/update.php?handle=UNIQUE_HANDLE_HERE")

Setting Profile Content on Pages

You can use the same techniques to update the profile box on Pages, but instead of a user id you will need to pass in a page id. When your application is
viewed by the administrator of a page who has added your application, the page's id is appended to the URL of your canvas
page.http://apps.facebook.com/YOURAPPLICATION/?fb_page_id=XXXXXXXXXX.
You can access it via the $_GET/$_REQUEST variables in PHP, like so:
PHP:
if (array_key_exists('fb_page_id', $_REQUEST)) {
$page_id = $_REQUEST['fb_page_id'];
$facebook->api_client->profile_setFBML($markup, $page_id);
}

109 | P a g e

EDIT: This information also appears to be no longer valid. The variable passed now appears to be something like:http://apps.facebook.com/YOURAPP?
&_fb_fromhash=8da92dc5a431e813ca88b8e69940b4c3
If someone has details on this new format, please update this page.--837574389 14:36, 31 October 2008 (PDT)

See Also

http://wiki.developers.facebook.com/index.php/Requested_FBML_Tags#fb:ref_attribute_-_delayfetch

http://wiki.developers.facebook.com/index.php/Requested_FBML_Tags#fb:ref_attribute_-_timeout

Fb:share-button
Description
Renders a standard Share button in a profile for the specified URL or content.
Important: All attributes in the table below must be written in all lowercase letters.

Attributes
Required Name Type Description
required class
href
optional meta

string The type of share button. When used as an FBML tag, valid values are

url, to render a share of the URL specified with the href attribute, and meta, to render a
share with the given data. When used as an XFBML tag, the value must be url.

string The reference URL to share. This attribute is required for the

only.

string The metadata about the shared item. See descriptions of the necessary data. The meta class may contain this attribute. (This attribute is not supported

in XFBML.)

110 | P a g e

url class

link

string The content (such as image thumbnails) for the shared item. See descriptions of the necessary data. The metaclass may contain this attribute. (This attribute

is not supported in XFBML.)

Examples
<fb:share-button class="url" href="http://apps.facebook.com/example" />

<fb:share-button class="meta">
<meta name="medium" content="blog"/>
<meta name="title" content="Leonidas in All of Us"/>
<meta name="video_type" content="application/x-shockwave-flash"/>
<meta name="video_height" content="345"/>
<meta name="video_width" content="473"/>
<meta name="description" content="That's the lesson 300 teaches us."/>
<link rel="image_src"
href="http://9.content.collegehumor.com/d1/ch6/f/6/collegehumor.b38e345f621621dfa9de5456094735a0.jpg"/>
<link rel="video_src" href="http://www.collegehumor.com/moogaloop/moogaloop.swf?clip_id=1757757&autoplay=true"/>
<link rel="target_url" href="http://www.collegehumor.com/video:1757757"/>
</fb:share-button>

If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.
<fb:share-button href="http://apps.facebook.com/example"></fb:share-button>

111 | P a g e

{ General Discussion about share-button }

>Talk:Fb:share-button
>> javascript question
Instead of using the <fb:share-button>, I am using the javascript code shown here (as given on the Posted Items application page):
<script>function fbs_click() {
u=location.href;
t=document.title;
window.open('http://www.facebook.com/sharer.php?u='+encodeURIComponent(u)
+'&t='+encodeURIComponent(t),'sharer','toolbar=0,status=0,width=626,height=436');return false;
}
</script>

The reason I'm using this is because I want to use my own icon for sharing instead of facebook's "Share" button. This works fine, except that I lose the nice
popup dialog functionality -- instead it takes the user to a new page to share/post the link. Is it at all possible to get this to work with the contextual dialog
popup (or to get the fb:share-button to take some other css style? I tried using my own class definition, but it seems to only take 'url' or 'meta')??
Answer: use CSS to override the look of the .share class
.share {
display:block;
float:left;
width:12px;
height:0px;
padding:12px 0 0 0;
margin:0;
border:none;

112 | P a g e

background:url(http://www.yoursite.com/images/icon.png);
overflow:hidden;
}
.share:hover {
border:none;
background:url(http://www.yoursite.com/images/icon.png);
}

Change the "12px" to the width/height of your icon.

how to add html tag to <meta name="description" content='<a href="">test</a>'>

who knows it?

You need to escape the html first

how to add the image on the 'Share' button

I developed an application. On my profile page, there is a 'Share' button. When I click on it, though, there is no image (on the bottom of the popup, next to
the text). How do I add the image here, because I thought that I added the image everywhere where I could find.
-- To add one image, use <link rel="image_src" href="..." /> My question is, how to add more than one image? The share dialog always says, "1 of 1", but
I'd like to let the user choose among several.
Yeah, doesn't seem like there's any way to allow multiple thumbnails short of creating a dummy page with multiple images. Even then, you have to
redirect to the facebook share.php and get your page to redirect to an appropriate page once users are sent to the link in the posted item. Arg.
- 193700405 08:54, 2 December 2008 (PST)

113 | P a g e

here is the bug tracker link if anyone else wants to add their votes: http://bugs.developers.facebook.com/show_bug.cgi?id=2128 -193700405 09:05, 2
December 2008 (PST)

How to add APP's title and description with share button?

I got the button to work:
<fb:share-button class='url' href='http://apps.facebook.com/myapp/'></fb:share-button>
However, when I use "share" button it opens a dialog with apps.facebook.com as a subject line and my app's link below. I've added <fb:title>My
title</fb:title> but it still does not use it. Also, how do I add app description?
Thanks.

.Answer
You need to use the meta class instead of the url class e.g.
<fb:share-button class="meta">
<meta name="medium" content="mult"/>
<meta name="title" content="***ITEM'S TITLE***"/>
<meta name="description" content="***DESCRIPTION OF ITEM THAT IS BEING SHARED***"/>
<link rel="image_src" href="***IMAGE THUMBNAIL URL***" />
<link rel="target_url" href="***LINK URL***"/>
</fb:share-button>
It is not necessary to include an image.

114 | P a g e

Fb:time
Description
Renders the date and time in the user's time zone. In order to show dates in a more flexible format, use Fb:date.

Attributes
Required Name

Type

Description

required t

int

The time to display in epoch seconds.

optional tz

string

The time zone in which to display t. Acceptable formats include PHP's List of Supported Timezones and +/- formats such as Etc/GMT-7. Note: Due to
bug (see below) when using a timezone in theEtc/GMT format the time is relative to the timezone. (Default value is loggedinuser's timezone.)

bool

Indicates whether to automatically insert prepositions as appropriate into the time, where "at" prepends the time and "on" prepends the date if it
appears. (Default value is false.)

prepositio
n

Examples
<fb:time t='1191648451'/>

<fb:time t="1180502413" tz="America/New_York" />

115 | P a g e

Notes

The time expands as needed. If t took place in the same day, only hour:minutes[am|pm] appears. For more flexible date formats, please see Fb:date.

When timezone is entered in the Etc/GMT format the time is the opposite of what is expected. See [1]. The takeaway is that GMT-5 (EST) should be
passed to tz as Etc/GMT+5 because of the odd convention.

See Also
You can see a real world example of this tag in the Footprints demo application. Go to Demos for more details and to download and install the demo apps.

Fb:title
Description
Sets the page's <title> tag to its contents. Alternatively, when used inside fb:comments, sets the title for the Wall.

Examples
<fb:title>This is the canvas page window title</fb:title>
App Name on Facebook | This is the canvas page window title

116 | P a g e

I.

Forms

Fb:submit
Description
Creates a JavaScript submission mechanism for a form, which makes image or text links act as Submit buttons. Markup contained by this tag is surrounded
with an <a> tag that includes a submit onclick action.
This article or section needs expansion

Attributes
Required
optional

Name

Type

Description

form

string

The ID of the form to be submitted.

Examples
<fb:submit><img src="http://sleekupload.com/uploads/submit.png"></fb:submit>

117 | P a g e

J. Additional Permissions

Fb:prompt-permission
Description
Renders the content of the tag as a link that, when clicked, initiates a dialog requesting the specified extended permissions from the user. You can prompt the
user for a series of permissions.
If the user has already granted a permission, a dialog for that permission does not appear. If the user has not already authorized the application before clicking
the link, he or she is prompted to authorize it before being prompted for the permission.
You can prompt a user to approve the following extended permissions for your application:

Allowing email to be sent to the user

Reading from a user's stream

Publishing posts to a user's stream

Granting offline access (what used to be known as an infinite session) for your application

Updating user status

Uploading and tagging photos

Creating and modifying events

Setting a user's RSVP status for an event

Sending SMS to the user

Uploading videos to user profiles

Writing, editing, and deleting notes on user profiles

Posting links to user profiles

118 | P a g e

Attributes
Required Name

Type

Description

required perms

string

A comma-separated string representing the extended permissions being requested. Specify any of the following
permissions: email, read_stream, publish_stream, offline_access, status_update, photo_upload,create_event, rsvp_event, sms, video_upload, create_note,

optional next_fbj
s

string

The FBJS that will be called if the user grants the requested permission.

Examples
Whether you are formatting this tag as FBML or XFBML, it requires a closing tag.
<fb:prompt-permission perms="email">Would you like to receive email from our application?</fb:prompt-permission>

<fb:prompt-permission perms="read_stream,publish_stream">Would you like our application to read from and post to your
News Feed?</fb:prompt-permission>

See Also

Prompting a user for an extended permission

users.hasAppPermission

>>> User Discussion

119 | P a g e

Question: next_fbjs is called regardless of choice?

The article states that next_fbjs is called "if the user grants the requested permission" but is called if the user clicks 'don't allow'... Am I doing something wrong,
or is something not working as intended?

Question: Normal users and infinite session

That example looks like it might be for the iframe'ers? Is all that really necessary for a normal app too? Maybe it is and that's why I couldn't get it to work in my
quick test :-( --543396022 13:05, 14 July 2008 (PDT)
Actually, I grabbed the source for the form from the Smiley sample app: http://apps.dev.facebook.com/mysmiley/.
It appears that all that is necessary for normal users is something like this:
<fb:prompt-permission perms="infinite_session">infinite_session<br /></fb:prompt-permission> <fb:prompt-permission
perms="email">email<br /></fb:prompt-permission> <fb:prompt-permission perms="status_update">status_update<br
/></fb:prompt-permission> <fb:prompt-permission perms="photo_upload">photo_upload<br /></fb:prompt-permission>
<fb:prompt-permission perms="create_listing">create_listing<br /></fb:prompt-permission>

But I cannot get infinite_session working. Anybody else having this issue? 26716424 09:28, 25 July 2008 (PDT)
Use offline_access to get infinite session.

Question: How do I make the link that fb:prompt-permission generates PRETTY?

I set <fb:prompt_permission class="inputsubmit" perms="offline_access">Generate Permanent Login</fb:prompt_permission>, but it
appears to have stripped out my class attribute!!! --186000005 12:23, 12 August 2008 (PDT)
The best is probably to put an image in this link, as the text will remain ugly...

120 | P a g e

Question: How do I make the link that fb:prompt-permission generates REDIRECT

somewhere after the user grants the permission?
I set <fb:prompt_permission perms="offline_access" next_fbjs="window.location = window.location" >Generate Permanent
Login</fb:prompt_permission>, but the convert my window.location to a18600904100_window.location, rendering it
ineffectual. --18600000512:23, 12 August 2008 (PDT)
sample code in php:
<script type="text/javascript">
function permissionGranted() {
document.setLocation('http://apps.facebook.com<%=$_SERVER['REQUEST_URI']%>');
}
</script>
<fb:prompt-permission next_fbjs="permissionGranted()" perms="offline_access">enable offline access</fb:promptpermission>
<fb:prompt-permission next_fbjs="permissionGranted()" perms="email">allow email responses</fb:prompt-permission>

Question: Is there any other way to grant an application offline access?

I haven't found a way in the application settings anywhere. I think this is a pretty big limitation as some users would like to give access
before the application has made the transition.
Yes. You can use the promptpermission attribute in a form.
See UsageNotes/Forms#Prompting_a_User_for_an_Extended_Permissionfor details. -- Pete User:563683308

Question: Incorrect post-grant redirect

121 | P a g e

I'm successfully using this FBML to show the dialog box for enabling email permissions to the user, but the text of the dialog box has my application name in
there with an incorrect link -- it is linking to the "Callback URL" instead of either the "Canvas URL" or "About Page" URL. Is this a bug, or something I can fix
through configuration? --544836835 17:02, 22 September 2008 (PDT)
This is likely a bug. An engineer is looking into it currently. Thanks for reporting. -- Pete (User:563683308)
I read on the forum the possibility of adding a callback to the function. This, however, does not use the <fb:prompt-permission> tag. I also tried the 'next_fbjs'
method but all it does it stop loading the page after a successful click. My text (that should disappear) stays on the page.
Is there a fix for this problem? Or is there a callback solution that is working?
See http://forum.developers.facebook.com/viewtopic.php?pid=117374 for the forum discussion.

Question: Is there any way to grant extended permissions from the mobile facebook
site?
None of the three methods (FBML, form based, or even directing to the authorize.php page) work. There is currently no way to enable any extended permissions
from a mobile phone. Is this going to be fixed?
It's a feature that's being worked on at the moment. I can't offer you a completion date at this time, sorry. -- Pete (563683308 14:28, 7 January 2009 (PST))

Question: It looks as if the prompt-permission tag doesn't work inside dialog boxes
inside IE, however works in FF. Sounds like a bug?
Thanks for noting this Mike. We're not aware of this being an issue. Please file a bug and note with which versions of IE it doesn't work. Thanks! -- Pete
(563683308 12:01, 9 February 2009 (PST))
Bug has been filed, http://bugs.developers.facebook.com/show_bug.cgi?id=4357

122 | P a g e

Question: Is there any update on the mobile facebook prompt-permission capability

please?
Question: Progress on setting extended permission with m.facebook.com?
Pete, what is the progress on setting the extended permission with m.facebook.com? Or, even just get it to work with other two ways (FBML or Form) with
PocketIE? Please let us know. Thanks!!
Koko at [email protected]

Question: Is there any way to handle the event in case user clicks on Cancel?
There is a parameter next_fbjs which will be called if the user opts for any extended permission. If the user clicks on cancel, is there a way to capture and handle
this event?

Question: Is there a way to initiate the same "Settings" link/dialog that FB

Applications page uses, giving the user a quick way to remove permissions from
within the application?
Question: how to auto display prompt-permission automatically?
Question: How can I call prompt-permission from AS3?
I want to call the prompt-permission from my AS3, but cant find how to do that. Can anyone help?

123 | P a g e

Adobe supports the AS3 library, and you can find their docs at http://facebook-actionscript-api.googlecode.com/svn/release/current/docs/index.html. Specifically,
there's a method in the Facebook class calledgrantExtendedPermission() -- passing a comma-separated list of extended permissions to that call should do the
trick. Pete (56368330814:20, 28 July 2009 (PDT))

K. Notifications and Requests

Fb:req-choice
Description
Specifies a button to be shown at the bottom of a request on the user's requests page.

Attributes
Required
required

Name

Type

Description

url

string

The URL to which the button should take the user upon click. must be an absolute.

label

string

Specifies the text to display on this button.

Examples
<fb:req-choice url="http://apps.facebook.com/yourapp" label="Confirm" />

124 | P a g e

Notes
An Ignore button is added by default and will dismiss the request. Including Ignore as a req-choice often results[who says?][possible bug?] in the loss of all buttons. Using
the same URL for multiple buttons will cause only the last button with the URL to be shown. In most cases, the URL should be either the facebook add
application URL (e.g. http://www.facebook.com/add.php?api_key=FACEBOOK_API_KEY&v=1.0), or the root URL for your application (e.g.
http://apps.facebook.com/yourapp).

Fb:request-form
Description
Creates a form that sends requests to the selected users. To send requests/invitations to multiple users, create one of these forms and include either
an fb:multi-friend-selector or any combination of fb:multi-friend-input, fb:friend-selector and fb:request-form-submit. The form is submitted after the user confirms
the sending of the request.
If you want to invite only one friend, without making the user select from a list of friends, use the fb:request-form-submit tag within the fb:request-form tag, and
make sure to set the appropriate attributes (uid, label) on the submit button to indicate that you are sending an invite to only one friend.
In general, use fb:multi-friend-selector in a nearly full-page invitation interface where the user is intended to select a large number of people, andfb:friendselector or fb:multi-friend-input in situations where the user is selecting a smaller number of users and you want to integrate it into the context of your own page.
As a middle-ground alternative, you can use the fb:multi-friend-selector (condensed) for places where the user might select a medium-sized list of people
without needing a full-page interstitial invitations interface.
For developers using iframes, you can use XFBML and the fb:serverfbml tag to render fb:request-form. In addition, you can send requests using
the Multi_friend_selector, or you can use the fb_force_mode parameter to render a particular canvas page with FBML.
For developers wishing to utilize more form parameters, typical form input can be used with the attribute
submit tag. The fb_protected attribute prevents FBJS from touching secure elements in the form.

125 | P a g e

fb_protected="true"

within anyfb:request-form-

Attributes
Required Name

Type

Description

required type

string

The type of request or invitation to generate. This corresponds to the word that is displayed on the home page. For example, "event."

string

The contents of the request or invitation to be sent. It should use FBML formatting that contains only links and the special tag <fb:req-choice url="" label="
/> to specify the buttons to be included in the request. Make sure that you properly encode this attribute. For example, use the PHP "htmlentities" function.

bool

Set this to true if you want to send an invitation or false if you want to send a request. The difference between them is in the content that the user
sees. (Default value is false.)

action

string

The place where a user gets redirected after submitting the form through the fb:request-form-submit button or when they click Skip this Step. By default
the user is directed to http://apps.facebook.com/yourapp/null.Note: This default behavior may not be preserved.[verify]

method

string

Set it to either GET or POST, as you would with a form.

content
optional invite

POST Variables
Required

Name

Type

Description

typeahead

string

The string containing any content the user typed into the multi-selector box.

ids

array

A zero-based array containing all of the user IDs of the people the user invited.

Examples
Example FBML Invite Page
<fb:fbml>
<fb:request-form
action="index.php"
method="POST"
invite="true"
type="YOUR APP NAME"

126 | P a g e

content="Your text goes here. <?php echo htmlentities("<fb:req-choice url=\"YOUR CANVAS URL\" label=\"Authorize My
Application\"") ?>" >
<fb:multi-friend-selector showborder="false" actiontext="Invite your friends to use YOUR APP NAME.">
</fb:request-form>
</fb:fbml>
Note: The <?php echo htmlentities("<fb:req-choice url=\"YOUR CANVAS URL\" label=\"Authorize My Application\"") ?> is needed to add a button to
accept the invite.

Example Java Invite Page

Here is the FBML:
<fb:request-form
action="start.htm"
method="POST"
invite="true"
type="sample network"
content="This network is the best place on Facebook for viewing, sharing and giving
friends the highest quality stuff. Join me on this network!
<fb:req-choice url='http://www.facebook.com/login.php?api_key=<c:out value='${apiKey}' />'
label='Check out this network!' />
">
<fb:multi-friend-selector
showborder="false"
actiontext="Invite your friends to this network."
exclude_ids="<c:out value='${appUserFriends}' />"
max="20" />
</fb:request-form>

127 | P a g e

Here is the server side Java:

protected Map referenceData(HttpServletRequest request) throws Exception {
logger.info("InviteFriendsFormController.referenceData ...");
FacebookRestClient facebookRestClient = getFacebookUtils().getFacebookRestClient(request);
//get the list of friends who are app users so they can be excluded from the invite page
String appUserFriends = getFacebookUtils().getAppUsersFriendsString(facebookRestClient);

HashMap referenceData = new HashMap();

referenceData.put("appUserFriends", appUserFriends);
referenceData.put("apiKey", PropertyUtils.getInstance().getPropertyValue("API_KEY"));
getFacebookUtils().loadUrlData(referenceData);
return referenceData;
}

Example PHP Invite Page

<?PHP
// Get these from http://developers.facebook.com
$api_key = 'xxx';
$secret = 'xxx';
// Names and links
$app_name = "Application name";
$app_url = "app-url"; // Assumes application is at http://apps.facebook.com/app-url/
$invite_href = "invite.php"; // Rename this as needed

128 | P a g e

require_once 'facebook.php';
$facebook = new Facebook($api_key, $secret);
$facebook->require_frame();
$user = $facebook->require_login();
if(isset($_POST["ids"])) {
echo "<center>Thank you for inviting ".sizeof($_POST["ids"])." of your friends on <b><a
href=\"http://apps.facebook.com/".$app_url."/\">".$app_name."</a></b>.<br><br>\n";
echo "<h2><a href=\"http://apps.facebook.com/".$app_url."/\">Click here to return to ".
$app_name."</a>.</h2></center>";
} else {
// Retrieve array of friends who've already authorized the app.
$fql = 'SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1='.$user.') AND is_app_user = 1';
$_friends = $facebook->api_client->fql_query($fql);
// Extract the user ID's returned in the FQL request into a new array.
$friends = array();
if (is_array($_friends) && count($_friends)) {
foreach ($_friends as $friend) {
$friends[] = $friend['uid'];
}
}
// Convert the array of friends into a comma-delimeted string.
$friends = implode(',', $friends);
// Prepare the invitation text that all invited users will receive.
$content =

129 | P a g e

"<fb:name uid=\"".$user."\" firstnameonly=\"true\" shownetwork=\"false\"/> has started using <a

href=\"http://apps.facebook.com/".$app_url."/\">".$app_name."</a> and thought it's <u>so cool even you should try it
out</u>!\n".
"<fb:req-choice url=\"".$facebook->get_add_url()."\" label=\"Put ".$app_name." on your profile\"/>";
?>
<fb:request-form
action="<? echo $invite_href; ?>"
method="post"
type="<? echo $app_name; ?>"
content="<? echo htmlentities($content,ENT_COMPAT,'UTF-8'); ?>">
<fb:multi-friend-selector
actiontext="Here are your friends who don't have <? echo $app_name; ?> yet. Invite whoever you want -it's
free!"
exclude_ids="<? echo $friends; ?>" />
</fb:request-form>
<?PHP
}
?>

130 | P a g e

Example Overloaded Form

<fb:fbml>
<fb:request-form method="POST" action="compare.php" content="some content" type="" invite="false">
<input id="first_overloaded_id" type="hidden" fb_protected="true" value="first_overloaded_value"
name="first_overloaded_name"/>
<input id="second_overloaded_id" type="hidden" fb_protected="true" value="second_overloaded_value"
name="second_overloaded_name"/>
<div class="clearfix" style="padding-bottom: 10px;">
<fb:multi-friend-selector condensed="true" style="width:80%;" />
</div>
<fb:request-form-submit />
</fb:request-form>

131 | P a g e

</fb:fbml>

Example ASP.NET Invite Page

<p>Invite a friend to use this application...
<fb:request-form method="POST" invite="true"
type="Application Name" content="You have been invited to the Application Name application .
<%= Server.HtmlEncode("<fb:req-choice url=""http://apps.facebook.com/appurl/"" label=""OK"" />") %> " >
<fb:multi-friend-selector showborder="false" actiontext="Invite your friends to use this application." />
<fb:request-form-submit />
</fb:request-form>
</p>

Example Python (Django + PyFacebook) Invite Page

def invite_friends(request):
#HTML escape function for invitation content.
from cgi import escape
facebook_uid = request.facebook.uid
fql = "SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1='%s') AND is_app_user = 1" %
facebook_uid
result = request.facebook.fql.query(fql)
# Extract the user ID's returned in the FQL request into a new array.
if result and isinstance(result, list):
friends_list = map(lambda x: str(x['uid']), result)
else:

132 | P a g e

friends_list = []
# Convert the array of friends into a comma-delimeted string.
exclude_ids = ','.join(friends_list)
# Prepare the invitation text that all invited users will receive.
content = """<fb:name uid="%s" firstnameonly="true" shownetwork="false"/>
wants to invite you to play Online board games,
<fb:req-choice url="%s"
label="Put Online Gaming and Video Chat on your profile!"/>
""" % (facebook_uid, request.facebook.get_add_url())
invitation_content = escape(content, True)
return render_to_response('facebook/invite_friends.fbml',
{'content': invitation_content, 'exclude_ids': exclude_ids })

Example Python (Django + PyFacebook) Invite Friends template

<fb:request-form action="http://apps.facebook.com/livevideochat/?skipped=1"
method="POST" invite="true" type="Online Games"
content="{{ content }}">
<fb:multi-friend-selector max="20"
actiontext="Here are your friends who aren't using Online Games and Live Video Chat. Invite them to play
Games Online today!"
showborder="true" rows="5" exclude_ids="{{ exclude_ids }}">
</fb:request-form>

Notes

Make sure to include whatever attributes you would normally include if you were creating a <form> tag, such as

133 | P a g e

action

and method, as mentioned above.

The fb:multi-friend-selector tag does not show up in Internet Explorer 6.[verify][I have IE 6 and it works fine]

The type attribute appears to have a hard limit of 20 characters. Anything else is truncated.

When sending invitations (invite="true") users can also choose to invite friends who aren't using Facebook via email. Invitations sent this way do not
count towards your allocations, and recipients of those invitations are taken directly through Express Registration to join both Facebook and the application.

You can not add line breaks or any other formatting to the message (forum)

You can not add regular <input> fields directly to <fb:request-form> or the form will be post to an invalid page when the user clicks "skip" button (forum).

Discussion
Working sample of Multi Friend Selector for IFRAME applications
It was a bit of a struggle, but here is working PHP code that uses the new multi_friend_selector.php approach to initiating invites to your application. I am also
including the code for the old style approach; the soon to be deprecated approach using $facebook->api_client->notifications_sendRequest.
The biggest challenge I encounteed is the URL signing process. It is very easy to get signing errors when trying to redirect to the multi_friend_selector.php
page, due to URL and HTML encoding. In order to discover the source of the verification issues, I literally had to start with a minimalist set of arguments to the
multi_friend_selector.php page, and build them up in a trial and error fashion. I discovered that using PHP functions like htmlentities() and urlencode() on the
arguments and/or the URL can cause the final URL to differ from the raw aguments passed to the signature generator. If the URL passed to $facebook>redirect() is encoded in any way, it will appear to not pass the signature verification.
So here is the code that works. Like I said, adding calls to htmlentites() and urlencide() can caue the verfication to break down. I also discovered that using
double quotes in the $content string also throws things off the verification.

134 | P a g e

Hopefully this article will help others out there make the switch from $facebook->api_client->notifications_sendRequest to multi_friend_selector.php.
define( 'FB_API_KEY', 'abcdabcdabcdabcdabcdabcdabcdabcd' );
define( 'FB_SECRET', 'abcdabcdabcdabcdabcdabcdabcdabcd' );
define( 'FB_APPID', '0123456789' );
define( 'FB_CANVAS_URL', 'http://apps.facebook.com/myapp/' );
define( 'FB_APP_HOME_URL', 'http://www.mycompany.com/myapp/' );
// Call this function to send an invitation
// $to - a comma separated list of Facebook userids to invite.

It can be null for the NewStyle case.

// $bNewSytle - a bool indicating whether the new style mechanism should be used (multi_friend_selector.php)
function SendStandardInvitation($to, $bNewStyle = false)
{
$typeword = FB_APP_NAME;
// Warning: double quotes in the content string will screw up the invite signature process
$content

= FB_APP_NAME . ' let\'s you blah blah blah.

You can even blah blah blah!';

$content .= '<fb:req-choice url=\' ' . FB_CANVAS_URL . 'Home.php\' label=\'Check out ' . FB_APP_NAME . ' />';
$actionText = 'Spread the word!

Help your friends discover ' . FB_APP_NAME . '.';

if ($bNewStyle)
$bOK = SendNewRequest($to, $typeword, $content, $actionText);
else
$bOK = SendRequest($to, $typeword, $content);
return $bOK;
}
// The new style invite approach using multi_friend_selector.php
function SendNewRequest($to, $typeword, $content, $actionText, $bInvitation = true)
{
global $facebook;
$bInviteAll = (!$to || $to == "" ? true : false);
$excludeFriends = null;
if ($bInviteAll) // Get all friends
$excludeFriends = $facebook->api_client->friends_get();

135 | P a g e

else // Get all friends with the app

$excludeFriends = $facebook->api_client->friends_getAppUsers();
$excludeFriendsStr = null;
foreach ($excludeFriends as $userid)
{
$pos = strpos($to, (string)$userid);
if ($pos !== false)
continue;
if ($excludeFriendsStr)
$excludeFriendsStr .= ',';
$excludeFriendsStr .= $userid;
}
$params = array();
$params['api_key'] = FB_API_KEY;
$params['content'] = $content; // Don't use htmlentities() or urlencode() here
$params['type'] = $typeword;
$params['action'] = FB_CANVAS_URL . 'Mobilize';
$params['actiontext'] = $actionText;
$params['invite'] = ($bInvitation ? 'true' : 'false');
$params['rows'] = '5';
$params['max'] = '20';
$params['exclude_ids'] = $excludeFriendsStr;
$params['sig'] = $facebook->generate_sig($params, FB_SECRET);
$qstring = null;
foreach ($params as $key => $value)
{
if ($qstring)
$qstring .= '&';

136 | P a g e

$qstring .= "$key=$value";
}
$inviteUrl

= 'http://www.facebook.com/multi_friend_selector.php?';

$facebook->redirect($inviteUrl . $qstring);
return true;
}
// The old style invite approach using $facebook->api_client->notifications_sendRequest
function SendRequest($to, $typeword, $content, $bInvitation = true)
{
global $facebook;
$image = FB_APP_HOME_URL . 'logo.gif'; // To be shown beside the invite; resized to be 100 pixels wide
$result = $facebook->api_client->notifications_sendRequest($to, $typeword, $content, $image, $bInvitation);
$url = $result;
if (isset($url) && $url)
{
$facebook->redirect($url . '&canvas=1&next=Home.php');
return true;
}
$bOK = ($result && $result != "");
return $bOK;
}

I hope this helps.

Jim McCurdy Face To Face Software --- Hi Jim,
I tried this code and the only thing that I am getting is the blank page. Can you please advice what I am doing wrong. Application
ishttp://apps.facebook.com/bezisfriends/

137 | P a g e

Thanx, Bez

>> Fb:multi-friend-selector
Description
There are actually two versions of this button - the full version and the condensed version. This page describes the full version. For information about the
condensed version, see fb:multi-friend-selector (condensed).
This is a nearly full-page interface intended to be used on canvas pages to allow the user to send a "large" number of requests or invitations (where "large" is
generally some number more than 4). This tag must be used inside anfb:request-form tag. This interface includes a series of <input type="hidden" name="ids[]"
value="[friend id]"> which are included for selected users in the form that gets submitted to your <fb:request-form> action URL. Both the Skip this Step button
and theSubmit button take the user to the parent fb:request-form action URL.
Your users can invite their friends who aren't yet on Facebook by entering their email addresses in the text box at the bottom of the multi-friend selector. You
need to use Express Registration in order to have those friends join Facebook and authorize your application at the same time. After the friend authorizes your
application, it gets bookmarked automatically.
For developers using iframes, a full page version of this is available. Please see Multi_friend_selector for information about using it.
As a best practice suggestion, please choose the appropriate bypass string for the context in which the multi-friend selector appears. For example, if the user
clicks a link to explicitly arrive at the multi-friend selector, "Cancel" may be the appropriate string. However, if the user arrives at the multi-friend selector within
the context of an application flow, the default "Skip" is more appropriate, as "Cancel" may imply the cancellation of the application flow instead.
A user may invite a number of people each day equal to the maximum number of requests allocated to your application. If a user attempts to go over this limit,
the following message appears:

138 | P a g e

Attributes
Required Name

Type

Description

required actiontext

string

An instructional message to display to users at the top of the multi-friend-selector.

optional showborder

bool

Indicates whether you want a border around the outside of the multi-friend-selector.

rows

int

The number of rows of friends to show in the multi-friend-selector. (Default value is 5 and the value must be between 3 and 10.)

max

int

The maximum number of users that can be selected. This value ranges from 1 to 35, and is capped at the number of friend requests the user has
remaining under their limit. This attribute is ignored if it is greater than the number of requests your application is able to send.

exclude_ids

array

A comma-separated list of user IDs to exclude from the multi-friend-selector.

bypass

string

The version of the Bypass button you want to use. Set this attribute to "step", "cancel", or "skip", which results in Skip This Step, Cancel, or Skip,
respectively. (Default value is skip.)

email_invite

bool

Indicates whether you want to display an email invite section in the multi-friend-selector.

cols

int

The number of columns of friends to show in the multi-friend selector, which also determines the width of the invite box. The value must be one
of: 2 (which sets the box to 368px wide), 3 (which sets it to 466px wide), or 5 (which sets it to 740px wide). (Default value is 5.)

POST Variables
Required

139 | P a g e

Name

Type

Description

ids

array

An array of the user IDs chosen by the user.

Examples
<fb:multi-friend-selector actiontext="Select the
friends you want to invite. (All of them.)" rows="3"/>

140 | P a g e

141 | P a g e

>>Fb:multi-friend-selector (condensed)
Description
There are actually two versions of this button - the full version and the condensed version. This page describes the condensed version. For information about
the full version, see fb:multi-friend-selector.
This is a more condensed version of an interface which must be used inside an fb:request-form to select some number of friends to send an invitation or
request. This interface includes a series of <input type="checkbox" name="ids[]" value="[friend id]"> which is included for selected users in the form that gets
submitted to your <fb:request-form> action URL. For more information, check out fb:request-form.
There are two versions of the condensed multi-friend-selector - a one box version and a two box version. With selected_rows set to 0, the one box version
appears; it works like a normal check box where clicking a user selects that user. With selected_rows set to anything larger, the two box version is used; this
results in an upper list containing unselected users and a lower list containing selected users.
The condensed multi-friend-selector behaves like a normal block level element, which is to say that you can style it with a style attribute or by giving it a CSS
class, and its width stretches to fit into the containing block.

Attributes
Required Name

Type Description

required condensed

bool

Set this to true to use the condensed version of the multi-friend-selector. If not set, the full fb:multi-friend-selector is used.

optional max

int

The maximum number of users that can be selected. This value ranges from 1 to 35, and is capped at the number of friend requests the user has
remaining under their limit. This attribute is ignored if it is greater than the number of requests your application is able to send.

exclude_ids

array

A comma-separated list of user IDs to exclude from the condensed multi-friend-selector.

unselected_rows

int

The number of rows of friends to display in the unselected part of the condensed multi-friend-selector.(Default value is 6, and must be a number
between 4 and 15.)

selected_rows

int

The number of rows of friends to display in the selected part of the condensed multi-friend-selector.(Default value is 5, and must be a number
between 5 and 15; or set it to 0 to indicate that you want only a single box for both selected and unselected friends.)

142 | P a g e

POST Variables
Required

Name

Type

Description

ids

array

An array of the user IDs chosen by the user.

Examples
<div style="padding: 10px;">
<fb:request-form method="post" action="index.php" content="hey" type="sample" invite="true">
<div class="clearfix" style="padding-bottom: 10px;">
<fb:multi-friend-selector condensed="true" style="width: 200px;" />
</div>
<fb:request-form-submit />
</fb:request-form>
</div>

<div style="padding: 10px;">

<fb:request-form method="post" action="index.php" content="hey" type="sample" invite="true">

143 | P a g e

<div class="clearfix" style="padding-bottom: 10px;">

<fb:multi-friend-selector condensed="true" selected_rows="0" style="width: 200px;" />
</div>
<fb:request-form-submit />
</fb:request-form>
</div>

>> Fb:request-form-submit
Description
Creates a button that submits an fb:request-form. Use this along with any combination of fb:multi-friend-input or fb:friend-selector tags inside anfb:requestform if you would like to have the user send a request or invitation. When this button is clicked, a confirmation dialog appears that allows the user to confirm the
sending of the request or invitations.
You can also use a single user ID as the label for the button. This means that instead of using other elements in the fb:request-form, the button results in a
request being sent to the user that you specify for the label.
Note: When using a user ID as the button label, the user ID must belong to a friend of the current user. Using either the user ID of the current user or a user ID
that does not belong to a friend of the current user results in a dialog with a message of "Please select some friends first" when the button is clicked. (see bug)

Attributes
Required Name Type Description
optional uid
label

144 | P a g e

int

Set this to the user ID of a person you would like a request to be sent to.

string If you are using uid, use this tag to specify the text you want to appear as the label for the button. The text must include "%n" or "%N" which gets replaced

with the first name or full name for the user ID, respectively.

Examples
<fb:request-form-submit />

Fb:request-form-submit
Description
Creates a button that submits an fb:request-form. Use this along with any combination of fb:multi-friend-input or fb:friend-selector tags inside anfb:requestform if you would like to have the user send a request or invitation. When this button is clicked, a confirmation dialog appears that allows the user to confirm the
sending of the request or invitations.
You can also use a single user ID as the label for the button. This means that instead of using other elements in the fb:request-form, the button results in a
request being sent to the user that you specify for the label.
Note: When using a user ID as the button label, the user ID must belong to a friend of the current user. Using either the user ID of the current user or a user ID
that does not belong to a friend of the current user results in a dialog with a message of "Please select some friends first" when the button is clicked. (see bug)

Attributes
Required Name Type Description
optional uid
label

int

Set this to the user ID of a person you would like a request to be sent to.

string If you are using uid, use this tag to specify the text you want to appear as the label for the button. The text must include "%n" or "%N" which gets replaced

with the first name or full name for the user ID, respectively.

145 | P a g e

Examples
<fb:request-form-submit />

Fb:application-name
Description
Renders the application name. Use this tag to render the name of an application.
You can also use this tag in instances when you cannot use the application name directly. For example, to include the application name in a Mini-Feed or News
Feed story when that application name contains the word "message".

Attributes
Required Name Type Description
optional linked bool

Indicates whether the application name is linked to the application's About page. When set to true, the name is linked; when set to false, the name is not
linked. (Default value is true.)

Examples
<fb:application-name />

146 | P a g e

L. Status Messages

Fb:error
Description
Renders a standard Facebook error message. The content within the <fb:error> tags is used as the error message text.

Attributes
Required
required
optional

Name

Type

Description

message

string

The heading text to display in the error box. Alternately, you can specify the heading text using anfb:message child.

decoration

string

Customize the appearance of the error by choosing among two styles:

no_padding

shorten

Examples
<fb:error message="Error message" />

147 | P a g e

- Removes the 20 pixels of padding that surrounds the error message by default.

- Removes the 20 pixels of padding from the bottom of the error message.

<fb:error>
<fb:message>Error message</fb:message>
This is the error message text.
</fb:error>

Notes

The error must contain at least one fb:message child or the message attribute as the heading text.

You can center the text of the messages by adding this CSS:

.standard_message, .standard_message p {
text-align:center;
}

Fb:explanation
Description
Renders a standard Facebook explanation message. The content contained within the <fb:explanation> tags is used as the explanation text.

Attributes
148 | P a g e

Required

Name

Type

Description

required

message

string

The heading text to display in the explanation box. Alternately, you can specify the heading text using anfb:message child.

optional

decoration

string

Customize the appearance of the explanation by choosing from two styles:

no_padding

shorten

- Removes the 20 pixels of padding that surrounds the explanation by default.

- Removes the 20 pixels of padding from the bottom of the explanation.

Examples
<fb:explanation message="Explanation message" />

<fb:explanation>
<fb:message>Explanation message</fb:message>
This is the explanation message text.
</fb:explanation>

Notes
The explanation must contain at least one fb:message child or the message attribute as the heading text.

149 | P a g e

Fb:success
Description
Renders a standard Facebook success message. The content within the <fb:success> tags is used as the success explanation.

Attributes
Required Name

Type

Description

required message

string

The heading text to display in the success box. Alternately, you can specify the heading text using anfb:message child.

optional decoration

string

Customize the appearance of the success message box by choosing among two styles:

no_padding

shorten

- Removes the 20 pixels of padding that surrounds the message by default.

- Removes the 20 pixels of padding from the bottom of the message.

Examples
<fb:success message="Success message" />

<fb:success>
<fb:message>Success message</fb:message>
150 | P a g e

This is the success message text.

</fb:success>

Notes
The message must contain at least one fb:message child or the message attribute as the heading text.

Fb:message
Description
Renders the heading text for an error, explanation or success message.

Examples
<fb:message>
This is the heading text for the message.
</fb:message>

151 | P a g e