Facebook 2008 FBML Reference Guide

facebook FBML Reference Guide

Consolidated by: yapish.com

Last updated: 03/10/2008

facebook FBML Reference Guide Page 2 of 159

FBML

From Facebook Developers Wiki

Jump to: navigation, search Facebook Markup Language (FBML) enables you to build full Facebook Platform applications that deeply integrate into a user's Facebook experience. You can hook into several Facebook integration points, including the profile, profile actions, Facebook canvas, News Feed and Mini-Feed. FBML is an evolved subset of HTML with some elements removed, and others which have been added that are specific to Facebook. You set the FBML for a profile box by calling profile.setFBML through the API . The FBML is cached on Facebook's server until profile.setFBML is called again through a canvas page. For a highlevel technical spec for FBML, please see FBMLspec .

Valid HTML Elements

a fieldset ol textarea abbr font optgroup tfoot acronym form option th address h1 p thead b h2 pre tr bdo h3 q tt big h4 s u blockquote h5 samp ul br h6 script var caption hr select center i small cite img span code input strike dd ins strong del kbd style dfn label sub div legend sup dl li table dt link tbody em meta td

www.yapish.com

facebook FBML Reference Guide Page 6 of 159

Facebook tags

Summary:

User/Groups Deprecated Tags Profile-specific Visibility on Profile Embedded media Tools Misc Forms Message/Wall attachments Notifications and requests Status messages Editor display Page navigation Dialog Wall

User/Groups

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.

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

Attributes

Required Name Type Description

required uid

optional firstnameonly

uid

bool

The ID of the user or Page whose name you want to show. You can also use "loggedinuser" or "profileowner".

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

linked

lastnameonly

bool

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

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

www.yapish.com

facebook FBML Reference Guide Page 7 of 159

possessive

reflexive

shownetwork

useyou

ifcantsee

capitalize

subjectid

Examples

<fb:name uid="12345" />

bool

string

bool

uid

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

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

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

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

Alternate text to display if the logged in user cannot access the user specified. (default value is [empty string])

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

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.

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

Fb:user

Description

Forces the enclosed content to be restrained to site privacy checks[verify] based on the viewer of the information. The content within the tag "belongs" to the user specified.

Note: This tag does not appear to work at all when I test it, it does nothing. See bug report number 404.

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 can see user 12345.

www.yapish.com

facebook FBML Reference Guide Page 9 of 159

Fb:pronoun

Description

Renders a pronoun for a specific user.

Attributes

Required Name Type Description

required uid

int

The user ID for whom to generate the pronoun. You can substitute actor for the user ID so you can more easily aggregate feed stories.

optional useyou

possessive

reflexive

bool

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

Use the possessive form (his/her/your/their). (default value is false)

Use the reflexive form (himself/herself/yourself/themselves). (default value is false)

objective

usethey

capitalize

bool

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

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

Force a capital letter for the pronoun. (default value is false)

Examples

<fb:pronoun uid="12345" />

<fb:pronoun uid="actor" possessive="true" useyou="false"/>

www.yapish.com

facebook FBML Reference Guide Page 10 of 159

Fb:profile-pic

Description

Turns into an img tag for the specified user's or Facebook Page's profile picture. The tag itself is treated like a standard img tag, so attributes valid for img are valid with fb:profile-pic as well.

Attributes

Required Name Type Description

required uid

optional size

linked

int

string

bool

The user ID of the profile or Facebook Page for the picture you want to display.

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

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

Examples

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

<fb:profile-pic uid="12345" size="square" linked="true" />

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

<fb:eventlink eid="21150032416" />

www.yapish.com

facebook FBML Reference Guide Page 12 of 159

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

<fb:grouplink gid="2541896821" />

www.yapish.com

facebook FBML Reference Guide Page 13 of 159

Fb:networklink

Description

Prints the specified network name and formats it as a link to the network's page.

Attributes

Required Name Type Description

required nid

int

Network ID for the network whose name and link you want to retrieve.

Examples

<fb:networklink nid="67108896" />

www.yapish.com

facebook FBML Reference Guide Page 14 of 159

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

optional uid

int

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

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

Examples

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

Notes

This tag renders content on canvas pages and for notifications and feed stories. It doesn't work with profiles, email and notifications.

You can use the fb:networklink FBML to display the name/link of the network.

www.yapish.com

facebook FBML Reference Guide Page 15 of 159

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

optional what

int

string

The user ID to check.

The privacy setting to check. (Default value is search). Other valid values are profile, friends, not_limited, online, statusupdates, wall, groups, courses, 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>

Notes

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

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

int

An API-supplied pid of the photo, or any pid found in the query string of a photo URL on Facebook.

optional uid

int

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

Examples

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

<fb:if-can-see-photo pid="543212" uid="6789"> <fb:photo pid="54321" uid="6789" /> This one is cool too! </fb:if-can-see-photo>

Notes

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

www.yapish.com

facebook FBML Reference Guide Page 17 of 159

Fb:if-is-app-user

Description

Displays the enclosed content only if the specified user has accepted the terms of service of the application. Use <fb:if-user-has-added-app> to determine whether the user has added the application to their account.

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! <fb:else>You should sign up and play!</fb:else> </fb:if-is-app-user>

Notes

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

www.yapish.com

facebook FBML Reference Guide Page 18 of 159

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>

Notes

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

www.yapish.com

facebook FBML Reference Guide Page 19 of 159

Fb:if-is-group-member

Description

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

Attributes

Required Name Type Description

required gid

optional uid

role

int

string

The group ID.

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

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>

Notes

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

www.yapish.com

facebook FBML Reference Guide Page 20 of 159

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.

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.

www.yapish.com

facebook FBML Reference Guide Page 21 of 159

Fb:if-user-has-added-app

Description

Displays the enclosed content only if the specified user has added the application to their account.

Attributes

Required Name Type Description

optional uid

int

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

Examples

<fb:if-user-has-added-app uid="12345"> This user has put this app into his account. <fb:else>That user hasn't put this app into his account.</fb:else> </fb:if-user-has-added-app>

<fb:if-user-has-added-app> Hey, welcome! <fb:else>You must add this to your account to use it</fb:else> </fb:if-user-has-added-app>

Notes

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

This tag seems to work inside <fb:subtitle> on a profile page.

www.yapish.com

facebook FBML Reference Guide Page 22 of 159

Deprecated Tags

Fb:userlink

Description

Prints the specified user's full name linked to their profile along with their network, optionally (as is normally displayed on the Wall, for example).

This tag is deprecated. It is still useful in one context, however: using it in feed.publishActionOfUser (with the user ID on whose behalf the action is being published) prevents the Mini-Feed from prepending the actor's name to your feed title.

Attributes

Required Name Type Description

required uid

optional shownetwork

ifcantsee

int

bool

string

The User ID for the user whose name and link you want to retrieve.

Indicates whether to display the network name. (default value is true)

The alternate text to display if the user cannot see the specified user ID.

Examples

<fb:userlink uid="123445" />

Fb:if-is-own-profile

Description

This tag is deprecated, since if- tags are no longer allowed on profile pages.

It was used to display content inside only if the viewer of the profile matches the profile owner.[verify]

Attributes

Examples

<fb:if-is-own-profile> Welcome back to your profile! <fb:else>This is not your profile.</fb:else> </fb:if-is-own-profile>

Notes

As of FBML v1.1 you can use this tag only on a canvas page. error=Not allowed in profile. How to replace this?

Profile-specific

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.

Attributes

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.

Fb:narrow

Description

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

Attributes

Examples

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

</fb:narrow>

Notes

If no fb:narrow or fb:wide tag is specified, all content is displayed in either column. The narrow profile box is 190 pixels wide, not including margins. The left margin is 10 pixels, but there is no right margin. For balanced margins, make your content 180 pixels wide. If you want your fb:narrow information to appear when installed, please remember to set the Default Profile

Box Column value to "Narrow" in Developer Application » My Apps » Application's Settings » Installation section.

www.yapish.com

facebook FBML Reference Guide Page 26 of 159

Fb:profile-action

Description

Renders a link on the user's profile under their photo (such as "View More photos of..").

Attributes

Required Name Type Description

required url

string

The URL to which the user is taken after clicking. Must be an absolute link.

Examples

<fb:profile-action url="http://www.mysite.com/action/"> Perform Action </fb:profile-action>

NOTE: 'if-is-own-profile' deprecated! See that function for details <fb:if-is-own-profile>

<fb:profile-action url="http://apps.facebook.com/myapplication/status/">

View Your Status </fb:profile-action> <fb:else>

<fb:if-is-app-user uid="profileowner">

<fb:profile-action url="http://apps.facebook.com/myapplication/status/">

View this person's status </fb:profile-action> <fb:else>

<fb:profile-action url="http://apps.facebook.com/myapplication/invite/">

Invite this person to MyApplication

</fb:profile-action> </fb:else>

</fb:if-is-app-user>

</fb:else>

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

NOTE: example with fb:visible-to-user instead of the deprecated fb:if-is-own-profile

<fb:visible-to-user uid="loggedinuser">

<fb:profile-action url="http://apps.facebook.com/application/my_page">

View Your Application </fb:profile-action> <fb:else>

<fb:profile-action url="http://apps.facebook.com/application/">

www.yapish.com

facebook FBML Reference Guide Page 27 of 159

Check Out Application

</fb:profile-action> </fb:else>

</fb:visible-to-user>

Notes

Use profile.setFBML to add the button to a user's profile. If you add this to the profile of a user who has not added your application, it will appear only to those users who have added your application. By setting the default FBML (in Edit Settings, under My

Applications) to include an fb:profile-action, this action appears on every profile the user of your

application sees. There is a limit of about 30 characters in the action label. (Note: Leading and trailing white-space counts against this limit, so if your link is being elided, check for and remove any extra spaces between the tags and the label text.) For users for whom you have not called profile.setFBML, the actions are read from the content in "Default FBML" section of your application settings. For the most part, this applies to any user who has not added your application. For users for whom you have called profile.setFBML, the actions are read from whatever content you set when you last called profile.setFBML for that user. Example: There are three friends -- Larry, Curly and Moe. Both Larry and Curly add your application. When Larry views Curly’s profile, the profile actions that Larry sees on Curly’s profile come from the content you posted to Curly’s profile. When Larry views Moe’s profile, the profile actions Larry sees on Moe’s profile come from the default FBML content, because you haven’t called profile.setFBML on Moe, because you don’t necessarily know he exists

Errors

fb:profile-action: Required fbml_env var missing: "profile"

- If you get this error, it means you tried to use the fb:visible-to-owner, fb:visible-to-app-users, and the other fb:visible-to-*** elements on a Canvas page. fb:if-is-own-profile

- Not allowed in profile. Use fb:visible-to-owner, fb:visible-to-app-users, and the other fb:visible-to-*** elements instead. running example above through the [Facebook FBML validator] returns

- RUNTIME ERROR: fb:if-is-own-profile: "ifs" are not allowed in flavor ProfileBoxFBMLFlavor

--719255867 11:05, 19 November 2007 (PST) Most punctuation is stripped from the profiles box. Can someone write a working example that reproduces this behavior WITHOUT if-tags?

www.yapish.com

facebook FBML Reference Guide Page 28 of 159

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>

www.yapish.com

facebook FBML Reference Guide Page 29 of 159

Fb:user-item

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

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>

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

www.yapish.com

facebook FBML Reference Guide Page 30 of 159

Fb:subtitle

Description

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

Attributes

Required Name Type Description

optional seeallurl

string

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

Examples

<fb:subtitle seeallurl="http://apps.facebook.com/myapp/seeall" > <fb:action href="http://apps.facebook.com/wall/walltowall.php">Wall-to-wall</fb:action> Displaying 10 wall posts </fb:subtitle>

Notes

This tag always renders the HTML title attribute with Learn More About This Application for seeallurl. This tag does not function within fb:visible-to- tags.

[possible bug?]

At present there doesn't seem to be any way to prevent this.

[possible bug?]

Facebook 2008 FBML Reference Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

FBML

From Facebook Developers Wiki

Valid HTML Elements

Facebook tags

Summary:

User/Groups

Fb:name

Description

Attributes

Examples

See Also

Fb:user

Description

Attributes

Examples

Fb:pronoun

Description

Attributes

Examples

Fb:profile-pic

Description

Attributes

Examples

See Also

Description

Attributes

Examples

Fb:grouplink

Description

Attributes

Examples

Fb:networklink

Description

Attributes

Examples

Fb:is-in-network

Description

Attributes

Examples

Notes

Fb:if-can-see

Description

Attributes

Examples

Notes

See Also

Fb:if-can-see-photo

Description

Attributes

Examples

Notes

Fb:if-is-app-user

Description

Attributes

Examples

Notes

Fb:if-is-friends-with-viewer

Description

Attributes

Examples

Notes

Fb:if-is-group-member

Description

Attributes

Examples

Notes

Fb:if-is-user

Description

Attributes

Examples

Notes

Fb:if-user-has-added-app

Description

Attributes

Examples