1 | P a g e

Collect by Babon Mandal

FBMLFacebook 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 o 1.5 Social Widgets

o 1.6 Platform Internationalization o 1.7 Tools o 1.8 Misc o 1.9 Forms o 1.10 Message Attachments o 1.11 Additional Permissions o 1.12 Notifications and Requests o 1.13 Status Messages o 1.14 Editor Display

2 | P a g e

o 1.15 Page Navigation o 1.16 Dialog o 1.17 Wall

2 Deprecated Tags 3 Dynamic FBML attributes

4 Usage Notes 5 Invalid CSS Attributes 6 See Also

7 External Links

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

3 | P a g e

Social Widgets fb:comments (XFBML) fb:live-stream

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

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 fb:switch

o fb:default fb:user-agent

fb:typeahead-input o fb:typeahead-option

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

Forms 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 o fb:multi-friend-selector (condensed) o fb:request-form-submit

fb:application-name

4 | P a g e

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

5 | P a g e

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.

This also works for Facebook Pages with the ID of the Page passed as the uid parameter.

6 | P a g e

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 Show only the user's first name. (Default value is false.)

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

lastnameonly bool 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 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 strin

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

7 | P a g e

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 subjectid="219770" uid="219770" /> = himself<fb:name subjectid="219770" uid="1160" /> = you<fb:name subjectid="1160" uid="219770" /> = Josh Gibson<fb:name subjectid="1160" uid="1160" /> = yourself<fb:name 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 | P a g e

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

Attributes

Required Name Type Description

required 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. It should only be shown to people who have not been blocked by user 12345.</fb: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

NameType

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.

9 | P a g e

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

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.

10 | P a g e

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.

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 strin

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

facebook-logo

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.

11 | P a g e

<fb:profile-pic uid="12345" width="32" height="32" linked="true" />

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 Name Type Description

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

Examples

12 | P a g e

If you're formatting the tag as FBML, you don't need to use a closing tag.

<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 Name Type Description

required 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" />

13 | P a g e

If you're formatting the tag as XFBML for Facebook Connect, you must use a closing tag.

<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-networknetwork="16777229" uid="1230541">User 1230541, you are in the<fb:networklink nid="16777229" />network!</fb:is-in-network>

Notes 14 | P a g e

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.

* 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 strin

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

15 | P a g e

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.

* 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 strin

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

16 | P a g e

<fb:if-can-see-photo pid="54321" uid="6789"> <fb:photo pid="54321" uid="6789" /> 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 Name Type Description

optional 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!

17 | P a g e

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

* 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 Name Type Description

optional 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 18 | P a g e

Displays the enclosed content only if the specified user is a member of the specified group.

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

19 | P a g e

Examples

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

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

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

strin

g 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" />

23 | P a g e

</fb:if-section-not-added>

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 "max-

height: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

24 | P a g e

If no fb:narrow or fb:wide tag is specified, all content is displayed in either column.

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 Name Type Description

optional 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

26 | P a g e

Description

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 Name Type Description

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

27 | P a g e

Attributes

Required Name Type Description

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

28 | P a g e

The tag must be a child of either fb:dashboard or fb:subtitle.

Attributes

Required

Name Type Description

required href strin

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

optional onclick

strin

g 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 Name Type Description

optional 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 Name Type Description

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

31 | P a g e

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 Name Type Description

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

32 | P a g e

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 Name Type Description

optional 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 Name Type Description

optional 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 strin

g 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

35 | P a g e

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

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

age_distribution

array An array containing age and location restrictions for multiple areas.

type strin

g 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 37 | P a g e

<fb:21-plus>Ooooh la la<fb:else>Barney?</fb:else></fb:21-plus>

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 strin

g 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 strin

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

38 | P a g e

style strin

g Indicates a custom inline style for the iframe.

width int Indicates the width of the iframe.

height int Indicates the height of the iframe.

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 strin

g 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 strin 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

39 | P a g e

g 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 strin

g 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 strin

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

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-can-see-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 in-browser scaling and results may vary depending on the browser

Fb:mp3

Description

40 | P a g e

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.

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

41 | P a g e

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

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

42 | P a g e

Required

Name Type Description

required swfsrc strin

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

optional imgsrc strin

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

imgstyle strin

g The style attribute for the image.

imgclass strin

g The class attribute for the image.

flashvars strin

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

swfbgcolor strin

g 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 strin

g 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 strin

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

scale strin

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

align strin

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

wmode strin

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

43 | P a g e

Flash Variables

Facebook passes the following parameters to the SWF when it is loaded:

Required

Name Type Description

allowScriptAccess strin

g 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

strin

g The Facebook session key.

fb_sig_expires int The session expiration time.

fb_sig_api_key strin

g Your application's API key.

fb_sig_added bool Indicates whether the user has added your application.

fb_sig_ss strin

g 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 strin

g 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;"

44 | P a g e

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

45 | P a g e

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

Required

Name

Type Description

required src strin

g 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 strin

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

scale strin

g 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 strin The URL of the image displayed behind the play button before the movie starts playing. The URL must be absolute.

46 | P a g e

g

align strin

g 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 strin

g The hex value for background color while the movie plays. (Default value is #000000.)

Examples

<fb:flvsrc='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. 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

47 | P a g e

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

strin

g The URL of the Silverlight control.

optional imgsrc strin

g 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 strin

g The style attribute for the image.

imgclass strin

g The class attribute for the image.

swfbgcolor strin

g The hex-encoded background color for the Silverlight control.

Examples

<fb:silverlight silverlightsrc="http://www.somesite.com/silverlight" />

For now this feature has no functionality.

48 | P a g e

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

Required

Name Type Description

optional xid strin

g 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

49 | P a g e

page without the hash.)

numposts

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

width strin

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

css strin

g The URL to your own stylesheet.

title strin

g 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 strin

g 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:commentsnumposts="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 Comments Box - Social Widget that shares xids with fb:comments. Comments Box Sample Site

50 | P a g e

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

strin

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

apikey strin

g 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 strin

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

51 | P a g e

Examples

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

Fora 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> <scriptsrc="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php"type="text/javascript"></script> <scripttype="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 52 | 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 Name Type Description

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

53 | P a g e

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

54 | 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 Name Type Description

required 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:

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

56 | P a g e

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

Attributes

Required Name Type Description

optional desc 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 user 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.

delimiters

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>

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

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

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

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

61 | 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 Description

required name string 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.

62 | 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 Name Type Description

required name string The name of the HTML tag to render.

63 | P a g e

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.

64 | 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 Name Type Description

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

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

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

67 | P a g e

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:

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

68 | P a g e

Examples

<fb:board xid="titans_board"

canpost="true"

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.

69 | P a g e

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

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

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

70 | P a g e

Detecting a User's Online Status

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.

71 | P a g e

Attributes

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

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

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>

72 | P a g e

<script>

document.getElementById('chat_invite_container').setInnerFBML(chatInvite);

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

73 | P a g e

efficient.

Note: If you render the fb:comments tag from FBJS using setInnerFBML(), you must set a callbackurl.

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

optional callbackurl 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.)

74 | P a g e

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, but rather refresh the page.

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

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.

75 | P a g e

See Also

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 Name Type Description

optional 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/>

76 | P a g e

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

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

optional uid 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.)

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

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

80 | 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:

81 | 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 Name Type Description

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

Examples

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

82 | 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!

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

84 | 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[]"/>

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

optional width 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_locked

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-friend-input> in a single page.

Examples

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

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

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

<script type="text/javascript">

_qoptions= {

"qacct":"p-123456",

"source":"fb-app"

};

quantserve();

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

<script type="text/javascript">

_qoptions= {

"qacct":"p-123456",

"media":"widget",

88 | P a g e

"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 Name Type Description

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

89 | 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 Name Type Description

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

90 | P a g e

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

91 | P a g e

Required Name Type Description

optional api_key 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-468x60-

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

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

93 | P a g e

<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" />

<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

94 | P a g e

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.

Examples

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

95 | P a g e

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

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.

96 | P a g e

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>

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

</fb:typeahead-input>

</fb:fbml>

Notes

97 | P a g e

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

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

Fb:typeahead-option

Description98 | P a g e

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 Name Type Description

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

H. Misc

Fb:js-string

99 | P a g e

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

See FBJS for more information.

Attributes

Required Name Type Description

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

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.

100 | P a g e

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

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

101 | P a g e

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

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

102 | P a g e

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 Type Description

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

xmlns 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">

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

103 | P a g e

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

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

104 | P a g e

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

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

105 | P a g e

Attributes

Required Name Type Description

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

handle 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> tag into the appropriate place in your markup:

<fb:ref handle="YourHandle" />

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:

106 | P a g e

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.

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

107 | P a g e

( 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

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);

108 | P a g e

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.

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

109 | P a g e

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.

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")

110 | P a g e

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);

}

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 )

111 | P a g e

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

href string The reference URL to share. This attribute is required for the url class only.

optional meta 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.)

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

112 | P a g e

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

{ 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):

113 | P a g e

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

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.

114 | P a g e

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)

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.

115 | P a g e

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

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.

116 | P a g e

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 a bug (see below) when using a timezone in theEtc/GMT format the time is relative to the timezone. (Default value is loggedinuser's timezone.)

preposition

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

Examples

<fb:time t='1191648451'/>

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

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

117 | P a g e

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

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

118 | P a g e

Attributes

Required Name Type Description

optional form string The ID of the form to be submitted.

Examples

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

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:

119 | P a g e

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

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

120 | P a g e

<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

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

121 | P a g e

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

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:prompt-

permission>

<fb:prompt-permission next_fbjs="permissionGranted()" perms="email">allow email responses</fb:prompt-permission>

122 | P a g e

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 redirectI'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?

123 | P a g e

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

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 kokolin@yahoo.com

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?

124 | P a g e

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?

125 | P a g e

I want to call the prompt-permission from my AS3, but cant find how to do that. Can anyone help?

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 Name Type Description

required 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" />

126 | 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:friend-

selector 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 fb_protected="true" within anyfb:request-form-

submit tag. The fb_protected attribute prevents FBJS from touching secure elements in the form.

127 | P a g e

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

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

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

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"

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

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

130 | 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 =

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

}

?>

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

133 | 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:

134 | 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 action and method, as mentioned above.

135 | P a g e

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.

136 | 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();

137 | 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 .= '&';

138 | 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/

139 | 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:

140 | 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 Name Type Description

ids array An array of the user IDs chosen by the user.

141 | P a g e

Examples

<fb:multi-friend-selector actiontext="Select the

friends you want to invite. (All of them.)" rows="3"/>

142 | P a g e

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

144 | 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">

145 | 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:request-

form 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 int Set this to the user ID of a person you would like a request to be sent to.

label 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

146 | P a g e

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:request-

form 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 int Set this to the user ID of a person you would like a request to be sent to.

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

147 | 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 />

148 | P a g e

L. Status Messages

Fb:errorDescription

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

Attributes

Required Name Type Description

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

optional decoration string Customize the appearance of the error by choosing among two styles:

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

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

Examples

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

149 | P a g e

<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

150 | 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 - Removes the 20 pixels of padding that surrounds the explanation by default.

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

151 | P a g e

Fb:successDescriptionRenders 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 - Removes the 20 pixels of padding that surrounds the message by default.

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

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

153 | P a g e