FBML Essentials | O'Reilly Media

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

I generally cringe when I see “Hello World” examples in modern books on software development. It’s been used so often that it almost doesn’t teach anything anymore. However, because the social Web brings a new layer to web development, I’d like to show you a new layer to the “Hello World” example. A social application is all about interaction—it’s about establishing a conversation with your friends.

When writing social applications, you have to consider the fact that, in a way, you’re having a conversation with the people you are writing software for. Not only must your application talk to your users, but it must also allow them to talk to you and to each other. Simply taking an existing website and putting it on a social site such as Facebook will not bring you millions of users in weeks or months like the apps described in this chapter. Your Facebook application must give users the ability to share their actions with friends, broadcast to the world, find people with similar interests, and most of all, identify themselves in ways they never could before on traditional websites. Instead of asking yourself, “How will my users utilize my application?,” you should now ask yourself, “How will my users’ friends utilize my application?”

The following list shows some examples of several applications on Facebook, all with 100,000 daily active users or more at the time of this writing. Examine them and see if you can figure out why they have become as popular as they are. Then, apply those features to your own Facebook application design:

iLike (http://www.facebook.com/apps/application.php?id=2413267546&b): I can’t tell you the number of clients who come to me asking for an application “just like iLike.” iLike has all the elements of a good Facebook app, allowing you to track the songs you’re listening to and share them with your friends on Facebook. This is the ultimate example of an external website that successfully integrated into Facebook.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

I generally cringe when I see “Hello World” examples in modern books on software development. It’s been used so often that it almost doesn’t teach anything anymore. However, because the social Web brings a new layer to web development, I’d like to show you a new layer to the “Hello World” example. A social application is all about interaction—it’s about establishing a conversation with your friends.

When writing social applications, you have to consider the fact that, in a way, you’re having a conversation with the people you are writing software for. Not only must your application talk to your users, but it must also allow them to talk to you and to each other. Simply taking an existing website and putting it on a social site such as Facebook will not bring you millions of users in weeks or months like the apps described in this chapter. Your Facebook application must give users the ability to share their actions with friends, broadcast to the world, find people with similar interests, and most of all, identify themselves in ways they never could before on traditional websites. Instead of asking yourself, “How will my users utilize my application?,” you should now ask yourself, “How will my users’ friends utilize my application?”

The following list shows some examples of several applications on Facebook, all with 100,000 daily active users or more at the time of this writing. Examine them and see if you can figure out why they have become as popular as they are. Then, apply those features to your own Facebook application design:

iLike (http://www.facebook.com/apps/application.php?id=2413267546&b): I can’t tell you the number of clients who come to me asking for an application “just like iLike.” iLike has all the elements of a good Facebook app, allowing you to track the songs you’re listening to and share them with your friends on Facebook. This is the ultimate example of an external website that successfully integrated into Facebook.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The first step in creating a Facebook app is to register a developer account. Of course, you can develop applications using your normal Facebook account, but then you risk potentially exposing your app to competitors and others while it’s still under development. It is generally better practice to always develop and test your app in an account designated as a developer on Facebook. To set up a developer account, do the following:

Log out of your normal Facebook account.
On the Facebook home page, click the “Sign Up” button:
Fill in the form with any information you want. This could be completely fake, as it will be only your developer account, not your main account.
Submit the form, and wait for a confirmation email. In the email, click on the link. You’re now logged into your new account!
Now that you’re logged in, copy this URL into your browser’s URL bar: http://www.facebook.com/developers/become_test_account.php
On the next screen, click on the “Make [your developer username] a Test Account” button:
That will take you to a final confirmation page. Congratulations, you now have a developer account! Remember the email address you used for this account, as you’ll need it to log in every time you want to test your app.

Don’t follow these steps using your real account or you will lose very important functionality!

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This step is simple. To add the developer app, in your developer account click on “Developers.”
On the subsequent page, click on “Get Started” in pink.
Click on the “Add Facebook Developer Application” button:
Or you can just copy this link and skip the process above:
http://www.facebook.com/developers
Leave everything checked, and click “Add Developer.”
You now have the developer app installed and can begin creating applications on Facebook. You’ll notice a new “Developer” link on the left now.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Click on the “Developer” link on the left in your developer account.
That should take you to the Developer page. Click on “Set Up New .”
You now have the opportunity to enter an application name. We’ll call this app “FBML Essentials”. Click on the checkbox:
Click on “Optional Fields,” and more form fields should become available to you. Here are the optional fields and what they will do:
Developer Contact Email
This is the email address Facebook will use if it ever needs to contact you about your application. For this example app, we will enter ad⁠min@fbmlessentials.stayna⁠live.com.
User Support Email
On your app’s Help page, users can send support requests. Requests from that page will be sent to the address you set here. We’ll enter support@f⁠b⁠m⁠l⁠e⁠s⁠s⁠e⁠n⁠t⁠i⁠a⁠l⁠s.staynalive.com for this app.
Callback URL
The callback URL is the anchor for your entire application. All Facebook requests get forwarded to this URL behind the scenes. For the purposes of this app, we’ll use http://fbmlessentials.staynalive.com. You will want to enter the URL of your own website, one that you control. It is important to add a trailing slash to this URL because all requests to http://apps.facebook.com/fbmlessentials (see the “Canvas Page URL” field, next) get translated to this URL behind the scenes, and adding a slash ensures that the URL http://apps.facebook.com/fbmlessentials/foo.php does not end up becoming something like http://fbmlessentials.staynalive.comfoo.php.
Canvas Page URL
There is one box here that follows apps.facebook.com. The text you enter in this box must be unique and unused by other Facebook app developers. For the purposes of this app, we’ll enter “fbmlessentials” in the box, which means that the canvas page URL will be http://apps.facebook.com/fbmlessentials

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

HTML on an FBML-parsed page renders in just the same way that the FBML renders. On the whole, most HTML tags in the Facebook environment will render the same as normal HTML. However, for the developer’s benefit, as well as for the security and protection of your app, and to integrate better with the Facebook environment, Facebook parses a few tags differently than your normal HTML. This chapter covers a few things to be aware of when designing your Facebook application in FBML.

Forms in FBML are almost the same as forms in HTML, but when rendered by Facebook, they produce a few more hidden input fields. The following section covers the specs for the form tag.

The form tag renders a form in HTML, adding five additional hidden input fields—the fb_sig_profile, fb_sig_user, fb_sig_session_key, fb_sig_time, and fb_sig parameters—that give more information about the user submitting the form to the processing script. The fb_sig parameter is essentially just a hash (see http://en.wikipedia.org/wiki/Hash_algorithm) of all the other fb_sig_ values preceding it.

It is important to note that the fb_sig_user and fb_sig_session_key parameters are added only if the user using your app has successfully authenticated and logged into Facebook.

FBML-Specific Attributes

requirelogin=[true|false] default: true

If true, the user will be prompted to log in (if they have not already done so), and then they will be asked if they want to submit data to your app. The login redirects the user to the posted form, with the fb_sig_user and fb_sig_session values attached to that form.

The following optional attributes can be applied to any form element within the form:

clicktoenable=[element id]: When added to any element within a form, this enables the element specified by element id when the current element is clicked. Multiple element IDs can be submitted if they are separated by commas.
clicktodisable=[

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Forms in FBML are almost the same as forms in HTML, but when rendered by Facebook, they produce a few more hidden input fields. The following section covers the specs for the form tag.

The form tag renders a form in HTML, adding five additional hidden input fields—the fb_sig_profile, fb_sig_user, fb_sig_session_key, fb_sig_time, and fb_sig parameters—that give more information about the user submitting the form to the processing script. The fb_sig parameter is essentially just a hash (see http://en.wikipedia.org/wiki/Hash_algorithm) of all the other fb_sig_ values preceding it.

It is important to note that the fb_sig_user and fb_sig_session_key parameters are added only if the user using your app has successfully authenticated and logged into Facebook.

FBML-Specific Attributes

requirelogin=[true|false] default: true

If true, the user will be prompted to log in (if they have not already done so), and then they will be asked if they want to submit data to your app. The login redirects the user to the posted form, with the fb_sig_user and fb_sig_session values attached to that form.

The following optional attributes can be applied to any form element within the form:

clicktoenable=[element id]: When added to any element within a form, this enables the element specified by element id when the current element is clicked. Multiple element IDs can be submitted if they are separated by commas.
clicktodisable=[element id]: When added to any element within a form, this disables the element specified by element id when the current element is clicked. Multiple IDs can be submitted if they are separated by commas.
clickthrough=[true|false] default: false: When added to any element within a form in which Dynamic FBML (such as the previous attributes, or Mock AJAX or Visibility attributes) is being used, and if it is set to

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

All images in FBML get cached by Facebook’s servers. Facebook makes a request to your application, and as your application serves up tags, Facebook parses those images, ensures that they aren’t too big and that they meet various requirements, and then stores a copy of each image on the Facebook servers. From that point on, the cached version of your image on Facebook’s servers gets rendered by your browser, which saves your own servers from unneeded bandwidth costs.

Your images must be smaller than 50 MB, cannot be animated, and cannot be served as a script (a common method to track a cookie or even serve malicious code). This ensures quality among applications and keeps Facebook users feeling safe and secure when using your app. Images must be given as an link to the callback URL that you specified in your application installation settings (described in ).

If the cache of your image does not work for some reason, Facebook renders a blank image in your application. If you need to refresh your image from the Facebook cache, it is recommended you get your hands dirty with some actual Facebook API code. Look up the facebook.fbml.refreshImgSrc() API tag on the Facebook Developer Wiki for more information about how to do this (see http://developers.facebook.com/documentation.php?v=1.0&method=fbml.refreshImgSrc).

Facebook also recommends that application developers do not append cache breaking strings (random strings to break the image cache) to the end of their URLs. This ensures that if your image ever actually does change, there is only one version of your image on Facebook’s servers to update. It will also keep the load off your servers.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

CSS in FBML can be tricky if you don’t recognize the quirks associated with it. FBML supports tags for importing external files into your rendered HTML, as well as style attributes and <style/> tags for rendering the CSS inline. One must recognize, however, that Facebook reads these external files and parses them into its own formats.

Facebook treats tags very similarly to references in that, on first load of the file, it stores a cached copy of the file on the Facebook servers. The difference is that once the file is cached, that file never gets deleted. Therefore, it might be wise to append a ?version=2.0 or similar parameter if you want to indicate the file was changed. URLs in a href attribute must be absolute, just like tags, and must link to the callback URL specified in the application’s installation settings.

Here’s an example tag in FBML (referring back to our “Hello World” application in ):

<link rel="stylesheet" type="text/css" href="http://fbmlessentials.
    staynalive.com/facebook.css?version=1.0" />

CSS within your FBML, whether it’s within tags or documents linked from tags, must adhere to certain guidelines. Facebook, when reading id attributes in the DOM from your HTML, rewrites those IDs with the string app, appended by the ID of your application, followed by an underscore, and then the original ID you specified. The following HTML that you send to Facebook through your app:

<div id="foo">bar</div>

gets rendered by Facebook as:

<div id="app0123456789_foo">bar</div>

Therefore, in your CSS, all rules for IDs (those prefixed by #) must have the app0123456789_ prefixed to the ID. Which means:

#foo { ... }

should be:

#app0123456789_foo { ... }

in your CSS <style/> element or file. Take some time to practice these examples. Improper CSS and prefixing with application IDs in the wrong places have been the cause of some of the largest headaches I’ve had when using FBML.

As a reference, see for a list of the default CSS styles for each of the major HTML elements in Facebook. Every time you insert one of these HTML elements, the associated CSS gets assigned to that HTML element. This is important to remember as you are trying to assign your own CSS to these elements.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Facebook provides an FBML-specific version of JavaScript parsing called FBJS (Facebook JavaScript). This helps protect and not confuse the external scripts Facebook uses on the rest of its site. (We’ll cover FBJS in much more detail in .) Facebook wants to maintain security on profile pages so that users don’t get inundated with music, videos, and pop ups right when they visit a profile page.

Similar to tags in CSS, you can load external JavaScript files through tags that get cached in exactly the same way as tags. For example, to load external JavaScript, you would load a tag such as the following:

<script src="http://fbmlessentials.staynalive.com/facebook.js?version=
    1.0"></script>

Calls to the tag are limited to canvas pages only. Profile boxes can use FBJS, but they must be called with inline JavaScript rather than by an external JavaScript file.

Here are some rules regarding FBJS:

Methods are prepended with app, followed by the application ID of your app and an underscore. Be sure when referencing the method later to reference the parsed method name instead of your original method name. Global functions provided by Facebook are not rewritten in this manner.
Only the onclick attribute is supported in FBML/HTML elements for your app. To access other events for your FBML/HTML, you must set up an event listener.
Profile FBJS only activates after a user performs some sort of click action in the application’s profile box. This prevents music, pop ups, and other things happening without the user’s permission when visiting another user’s profile page.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Thus far, we’ve covered most of the basic HTML techniques you need to consider when writing your Facebook application. In the following sections, we’ll cover a few more miscellaneous techniques and caveats that you will want to know as you are developing your app.

User IDs supplied to FBML are 64-bit integers created by Facebook to identify each user. You might notice when you visit your Facebook profile that the URL is structured like this: http://www.facebook.com/profile.php?id=683545112.

The number after the id= is your Facebook ID. When planning your app, you may want to store this ID in a database for later reference. In MySQL, I use the BIGINT(20) data type to do this. You will want to find the equivalent for your database environment.

In addition to the ID, whenever there is a uid attribute in FBML, you can use the following identifiers in place of the actual ID of the user:

loggedinuser: Returns the Facebook ID of the user who is visiting the profile or canvas page on which your app is installed.
profileowner: Returns the Facebook ID of the user who has actually installed your app (the profile owner), not the visiting user.

By default, your application’s canvas page is publicly searchable by search engines and viewable by those not logged into Facebook. This makes it very important to ensure that your application’s canvas pages are tuned for Search Engine Optimization (SEO), so that others can use your app outside Facebook or are at least encouraged to log in and use your application.

All FBML is built to work on canvas pages even when the user is not logged in. To force a user to be logged in before using your app, use the tag, described in the next section.

This tag enables only certain content to be viewable if the user is logged out. If the user is logged in, the content between the tags is rendered. Note that <fb:is-logged-out/> has no FBML-specific attributes.

Example FBML

The following example demonstrates the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

“Where is the best place to host?” is one of the biggest questions I hear from my clients who want to build Facebook applications for their businesses. With a traditional web application, traffic buildup is gradual because you are dealing with a new audience in a nonviral channel for building hype for your website. On Facebook, however, the situation is different. With a good idea and the right viral elements in place, some applications have gone from zero page views to hundreds of millions in a matter of days. Without the proper infrastructure in place to handle this kind of traffic, your app could go down within minutes and your maximum potential for spreading the application could go out the door.

There are two hosting services at the time of this writing that I suggest you look into. I won’t go into detail, but these services provide a means of quick scaling as traffic to your application increases. The first—and my is Amazon EC2 (Elastic Compute Cloud) combined with S3 (Simple Storage Service) for backups. EC2 gives you a very fast way to programmatically scale your app as needed, while requiring you to pay only for the bandwidth and servers you need. The second service is Joyent. Joyent provides speedy scaling to new servers as needed, and it provides a direct line to Facebook so that your applications will have the fastest connection possible to Facebook’s servers. Beyond those two suggestions, of course, you can always find a good hosting center if you know what you’re doing and negotiate your prices as you need to scale. Just be prepared to have some servers of your own ready as a backup!

Once you have selected your service, what’s the best way to set up your servers to prepare for an influx of traffic such as I mentioned? That would take an entire book to detail, but my best suggestion is to keep your data as persistent as possible, so that if you need to fire up another instance of your server, it can automatically know where to retrieve the data. I strongly recommend hiring a good system administrator if this is not something you think you can handle, and at least have him on hand to prepare for the event of heavy traffic.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

When you visit any application on Facebook, it looks just as though it were being hosted right on the Facebook servers. In reality, Facebook is simply a proxy, reading the browser requests, passing them onto your servers, reading your servers’ responses, and then parsing that information back to the user in HTML format (see ).

Figure : When you access a Facebook app, you are actually talking to Facebook’s servers, which in turn communicate back to your servers

The one exception to this process is when data is rendered within an iframe. iframes on Facebook are not parsed by Facebook, so they allow you to do almost anything you want without worrying whether Facebook is able to parse the data you are providing. iframes have their limitations, however, because FBML is not possible in an iframe! I’ll explain more of those limitations in the section in .

is intended to be a reference to FBML. In it, I will include examples of the code you’ll be writing and show you what these examples render. I hope you’ll be able to refer back frequently to the next chapter as you continue your development on Facebook.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Throughout this chapter, I’ll cover the details of FBML, every single tag available at the time of this writing, and how each tag works. Please refer back to this chapter often as you write your FBML.

Letʼs start by showing how you can test these tags in your own browser without the need of a web server.

The Facebook FBML Test Console is an invaluable tool for any Facebook developer to test his FBML tags before putting them into production. Because Facebook has no true sandbox environment, every change to your application that you publish is available for any of your users to see (unless you have two versions of the same application, which is what a lot of developers end up doing). To help you avoid making errors in the Facebook Platform before your code goes live, Facebook has provided a test console for your FBML so that you can see what your code will look like when it gets rendered by Facebook.

To use this console, simply go to the Facebook developers website at http://developers.facebook.com and click on “Tools” in the top navigation. Youʼll see a series of test consoles you can play with. These include a console for the API, another for previewing the feeds you create, and—the one weʼre concerned with here—the FBML Test Console. Click on the “FBML Test Console” tab, and now you can test to your heartʼs content! If you want to skip these steps, this link will take you straight there: http://developers.facebook.com/tools.php?fbml.

The FBML Test Console enables you to specify any profile ID, any application API key, and any set of HTML, FBJS, and/or FBML code so that you can see how Facebook will render it. When you enter a bit of FBML code and click “Preview,” you will be shown the browser output, along with the rendered HTML and any errors for that output. See .

Figure : The FBML Test Console

The rest of this chapter will serve as a reference for you as you write your FBML. I suggest reading through the chapter and trying out each of the tags in the FBML Test Console to see what they produce. There may be times when you donʼt want to use FBML but instead want to reproduce what the FBML would do as HTML. The Test Console is ideal for that. Practice using the tags described in this chapter with the FBML Test Console, and soon youʼll be a pro!

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The Facebook FBML Test Console is an invaluable tool for any Facebook developer to test his FBML tags before putting them into production. Because Facebook has no true sandbox environment, every change to your application that you publish is available for any of your users to see (unless you have two versions of the same application, which is what a lot of developers end up doing). To help you avoid making errors in the Facebook Platform before your code goes live, Facebook has provided a test console for your FBML so that you can see what your code will look like when it gets rendered by Facebook.

To use this console, simply go to the Facebook developers website at http://developers.facebook.com and click on “Tools” in the top navigation. Youʼll see a series of test consoles you can play with. These include a console for the API, another for previewing the feeds you create, and—the one weʼre concerned with here—the FBML Test Console. Click on the “FBML Test Console” tab, and now you can test to your heartʼs content! If you want to skip these steps, this link will take you straight there: http://developers.facebook.com/tools.php?fbml.

The FBML Test Console enables you to specify any profile ID, any application API key, and any set of HTML, FBJS, and/or FBML code so that you can see how Facebook will render it. When you enter a bit of FBML code and click “Preview,” you will be shown the browser output, along with the rendered HTML and any errors for that output. See .

Figure : The FBML Test Console

The rest of this chapter will serve as a reference for you as you write your FBML. I suggest reading through the chapter and trying out each of the tags in the FBML Test Console to see what they produce. There may be times when you donʼt want to use FBML but instead want to reproduce what the FBML would do as HTML. The Test Console is ideal for that. Practice using the tags described in this chapter with the FBML Test Console, and soon youʼll be a pro!

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Each of the following tags verify in some way the permissions for a user’s role on Facebook. These tags can be quite useful for virally promoting your app. For instance, if you want to encourage non-app users to install your app, use the tag in your application’s profile box to provide a message that encourages non-app users to add your application. Or, if you want to provide an admin interface that allows the owner of an app or the admin of a page to administer settings within your app, use the tag with a uid of profileowner, and only the user who added your app will have access to those settings.

In this section, we will define the specifications of each authorization-related FBML tag on Facebook. The first half of the tags render only on a user’s canvas page or on a canvas page for a Facebook Page. The second half of the tags render only on a user’s profile or on a Facebook Page; they will not render on a canvas page. Each section in this chapter includes a brief description of the tag, followed by required and optional attributes that can be passed to the tags, as well as examples of how those tags can be used.

<fb:user/>

<fb:user uid="...">...</fb:user>

Depending on the user’s privacy settings, the content rendered within this tag displays only to users who actually have permission to see that user’s profile.

FBML-Specific Attributes

Required

uid=[string]: The ID of the user to protect content for.

Optional

None.

Example FBML

Here is example FBML code for a user whose information you would like to protect:

<fb:user id="4">
The content rendered here will only display if you have permission to 
    view Mark Zuckerberg's Profile.
</fb:user>

Rendered HTML for Single Instance of Tag

If you have permission to see Mark Zuckerberg’s profile, the following will appear where you place the FBML example just shown:

The content rendered here will only display if you have permission to 
view Mark Zuckerberg's Profile.

Of course, if you don’t have permission to see Mark Zuckerberg’s profile, nothing will appear where the tag is placed.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

To set profile-specific tags, or to render anything in a user’s profile for the application, you must either place the code in your “Default FBML” box in your application settings or make an explicit profile.setFBML call via the API. It’s important to understand that FBML on a user’s profile is not dynamic. This means that if you change the FBML, you must either set it through the “Default FBML” box in your application settings or make an API call via profile.setFBML again to reset the FBML for that user’s profile. Just refreshing the user’s profile page will not refresh it with your new FBML! The following tags work only in the application’s profile box on a user’s profile.

<fb:wide/>

<fb:wide>...</fb:wide>

FBML placed between these tags displays only when the application’s profile box is in the wide column on a user’s profile. See the description of the tag next for how to display in the narrow column. In your application settings, I strongly suggest that you set the default column for your application to narrow. This is because most application developers set the default column to wide (as that is the default). However, it is important to set how the application will look in the wide column on a user’s profile using the tag.

FBML-Specific Attributes

Required

None.

Optional

None.

Example FBML

Here is example FBML code for the <fb:wide/> tag; add this to your “Default FBML” box in your application settings (or you can set it via the setFBML API call):

<fb:wide>
  When a user drags the application profile box into the wide column 
  on their profile, this code will appear.
</fb:wide>

Rendered HTML for Single Instance of Tag

In our FBML Essentials application, when dragging the profile to the wide column of your profile (after adding the app), it will look like .

Figure : The application profile box in the wide column of a user’s profile

Additional Information

Code within the tags renders in a 388-pixel-wide box on the user’s profile (not including margins). There is also an 8-pixel left margin, and no right margin. To center your content, make your content 380 pixels wide.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

<fb:name/>

<fb:name uid="..."/>

Renders the name of the specified user. With various attributes you can customize how that name is displayed.

FBML-Specific Attributes

Required

uid=[string|loggedinuser|profileowner]: The ID of the user whose name you would like to display. loggedinuser displays the name of the user viewing the profile, whereas profileowner can be used to display the name of the owner of the profile being viewed.

Optional

firstnameonly=[true|false] default: false: If true, displays just the first name of the user.
linked=[true|false] default: true: If true, links the name to the listed user’s profile.
lastnameonly=[true|false] default: true: If true, displays just the last name of the user.
possessive=[true|false] default: false: If true, makes the name possessive (adds ’s to the name, turning Jesse into Jesse’s).
reflexive=[true|false] default: false: If true, and useyou is true, turns the pronoun “you” into “yourself.”
shownetwork=[true|false] default: false: If true, and an actual Facebook ID other than profileowner or loggedinuser is used, the name will display the user’s network in parentheses to the right of the name (see the example for this tag).
useyou=[true|false] default: true: If true, and the profile owner is the same as the logged-in user, displays “you” as the user’s name.
ifcantsee=[string] default: empty string: Specifies text to display in case a user viewing the current user’s profile or canvas page doesn’t have permission to see the user’s name.
capitalize=[true|false] default: false: If useyou is true and the specified uid is the logged-in user, capitalizes “YOU”.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The following sections cover general HTML display tags and page navigation tags.

<fb:title/>

<fb:title>...</fb:title>

When placed anywhere in a canvas page, this sets the tag in HTML for a specific canvas page.

FBML-Specific Attributes

Required

None.

Optional

None.

Example FBML

Here is the FBML code for <fb:title/> used in the FBML Essentials app:

<fb:title>O'Reilly FBML Essentials - Examples, Tips, Tricks, and 
    Trivia About Facebook!</fb:title>

Rendered HTML for Single Instance of Tag

The example produces a title tag that looks like the following in <header/> in the canvas page’s HTML ( shows the result):

<title>O'Reilly FBML Essentials - Examples, Tips, Tricks, and 
    Trivia About Facebook!</title>

Figure : The title bar that results from our <fb:title/> example

Additional Information

This tag works only on canvas pages. It will not work on a user’s profile page.

<fb:iframe/>

<fb:iframe src="..."/>

An excellent tool when you need to render complex JavaScript, Flash, or unsupported FBML. This tag links to an external web address and renders the content from that URL inside an HTML tag on the canvas page. From the external URL, any HTML, JavaScript, or Flash may be used, but keep in mind that content will not be parsed by Facebook, and therefore FBML will not be supported for anything output by the tags. is not supported on user profile pages.

FBML-Specific Attributes

Required

src=[string] default: none: External URL (non-Facebook, e.g., your own servers) to render in the iframe. All Facebook variables mentioned in the ” section in are appended to this URL, including fb_sig_profile, fb_sig_user, fb_sig_session_key, fb_sig_time, and fb_sig, in addition to an fb_sig_in_iframe parameter to let the app know it is being called from an iframe.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The following section describes several tags that you can use to virally promote your application. One of the strengths of Facebook is the rich access it provides to friends lists, and the tools it offers for promoting applications through those friends. As an application developer, with just knowledge of FBML you can do many things to spread your app to others on Facebook very quickly.

Notification tags require some API knowledge and access, but as you saw in the “Hello Friends” example in , with request tags you can create simple invite forms using just a series of FBML tags.

<fb:notif-subject/>

<fb:notif-subject>...</fb:notif-subject>

Specifies the subject of an email sent using the notifications.send() API method. This FBML works only within that FBML call.

FBML-Specific Attributes

Required

None.

Optional

None.

Example FBML

Send the following FBML code in a notifications.send() API call:

<fb:notif-subject>This is the subject of the E-mail</fb:notif-subject>

<fb:notif-page/>

<fb:notif-page>...</fb:notif-page>

Specifies the content of the notification, displayed on a user’s notifications page. It works only from within a notifications.send() API method call.

FBML-Specific Attributes

Required

None.

Optional

None.

Example FBML

Send the following FBML code in a notifications.send() API call:

<fb:notif-page>Add the <a href="http://apps.facebook.com/fbmlessentials">
FBML Essentials app!
</a></fb:notif-page>

<fb:notif-email/>

<fb:notif-email>...</fb:notif-email>

Specifies the content of the email to be sent to the user in a notifications.send() API method call. It can be used only in the notifications.send() API call. This is a great way to send an email to the user (not the user’s Facebook inbox, but the user’s real email address) and parse FBML beforehand as part of the email.

FBML-Specific Attributes

Required

None.

Optional

None.

Example FBML

To specify the FBML to be parsed for the user, send the following in a notifications.send() API call:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

<fb:time/>

<fb:time t="..."/>

Renders the time to the user. You pass in a time and date, in epoch seconds, and it gives you a nicely formatted time. If the time you enter is the same day as the current day, only the time is displayed in hour:minutes[am|pm] format. If not the same day, but the same year, the year is not displayed, so the format is Month Day hour:minutes[am|pm]. If neither the same day nor year, it is displayed in

Month Day, Year
        hour:minutes[am|pm]

format.

FBML-Specific Attributes

Required

t=[int] default: none: The time to display, in epoch seconds.

Optional

tz=[string] default: the logged-in-user's time zone: The time zone to display. Accepted formats are PHP’s list of supported time zones (see http://us.php.net/manual/en/timezones.php) and +/– such as Etc/GMT-7.
preposition=[true|false] default: false: The preposition, as necessary, added to the date and time (“at,” “on”).

Example FBML

The following are some examples of the <fb:time/> tag and what they produce. This FBML code:

<fb:time t="1"/>

would produce this:

December 31, 1969 5:00pm

whereas this FBML code:

<fb:time t="1" tz="America/Boise" preposition="true"/>

would produce this:

5:00pm on December 31, 1969

<fb:fbmlversion/>

<fb:fbmlversion/>

Prints the version of FBML currently in scope. If used outside of tags, prints the latest version of FBML.

FBML-Specific Attributes

Required

None.

Optional

None.

Example FBML

In the following example, the first instance of will print “1.0”. The second will print “1.1”, which is the current version of FBML at the time of this writing:

<fb:fbml version="1.0">
  The version listed here is <fb:fbmlversion/>
</fb:fbml>
The version listed here is <fb:fbmlversion/>

<fb:redirect/>

<fb:redirect url="..."/>

Redirects the page to the specified URL. This is the best way to redirect a user to a new page in a Facebook application canvas page.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

From within your FBML, you can apply special attributes to specific FBML and HTML tags that allow you to perform AJAX, dynamically hide and show elements, and other common JavaScript functions. The methods in this section offer you an easy way to get things done without having to worry too much about getting JavaScript to work in Facebook.

With just a few attributes added to most elements in your FBML, you can dynamically allow the displaying and hiding of data upon a click of a mouse button. The following attributes can include more than one element ID, separated by commas:

clicktoshow: When the current element is clicked, the element IDs contained will switch to display:block.
clicktohide: When the current element is clicked, the element IDs contained will switch to display:none.
clicktotoggle: When the current element is clicked, the element IDs contained will switch between their existing state and display:none and vice versa, depending on the current state.
clickthrough: Set this to true when using radio buttons or checkboxes with which you want to use clicktoshow, clicktohide, or clicktotoggle. Not setting clickthrough="true" when using these elements will render the element inoperable.

Here are three examples that show how to use the visibility attributes:

<div id="example1" style="display:none">Visible</div>
<a href="#" clicktoshow="example1">Click here to make "Visible" 
    appear.</a>

<div id="example2">Visible2</div>
<a href="#" clicktohide="example2">Click here to make "Visible2" 
    dissapear.</a>

<div id="example3">Visible3</div>
<a href="#" clicktotoggle="example1,example2,example3">
  Click here to toggle visibility of Visible1, Visible2, and Visible3
</a>

It is important to note that all styling (display:none, display:block, etc.) that is affected by the attributes just described should be done inline, via style attributes. Styling cannot be done inside a stylesheet document or via tags.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

JavaScript is very possible to use in Facebook applications. A book about FBML would not be complete without at least a short introduction to FBJS. I’m going to keep this discussion “in a nutshell,” but you can find much more information on the Facebook Developer Wiki at http://wiki.developers.facebook.com/index.php/FBJS.

FBJS is a very limited form of JavaScript, which Facebook has placed controls on to prevent malicious code in applications from accessing data it shouldn’t. Privacy is of the utmost importance on Facebook, and FBJS controls reflect that. Despite the restrictions, with a little practice, FBJS can provide almost all necessary functions that JavaScript can provide in an external application.

For even more flexibility in a JavaScript-heavy site, you should take some time and look up the JavaScript Client Library on the Facebook Developer Wiki: http://wiki.developers.facebook.com/index.php/JavaScript_Client_Library.

JavaScript in Facebook, just like FBML and HTML, gets parsed and rewritten by Facebook before it is rendered for the user. Therefore, it is important that you follow some specific rules to ensure that your JavaScript is fully compatible with Facebook. The rules to keep in mind are as follows:

JavaScript methods and variables should be prepended with the application ID, followed by an “_” in Facebook. This won’t affect your code too much, but it’s important to remember, as in certain instances you may need to call the method or variable with the application ID attached. In most cases you can just call the method name or variable name by itself and Facebook will handle all the magic!
On profiles, JavaScript will not run without the user making some sort of click action first. Therefore, it’s necessary to have an onClick event handler of some sort within a link or element in order to launch anything on profile pages. On canvas pages, the click action is not necessary.
Most DOM methods will work, but to retrieve information you must prepend the method with

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|

Table of Contents

FBML-Specific Attributes

FBML-Specific Attributes

Example FBML