Getting Started with Facebook Application Development using ColdFusion/Railo

June 2010

There are other CFML Facebook articles on the internet such as Ray Camden’s tutorial with ColdFusion 8; however Facebook continues to innovate and change, and a majority of those resources are out of date for Facebook’s 2010 updates. Things such as “profile boxes” are passé, and now you have to work with “Application Tabs.” In addition, I have found that there are some general concepts of how Facebook applications work. These have not been covered well in other resources.

Why Facebook?

According to statistics, Facebook is the 3rd highest traffic site in the US right now (statistics for the rest of the world weren’t readily available). The nature of Facebook is that people socialize, and look at what other people are doing, which means that if your friends post that they are using certain applications or visiting certain sites, you know about it, and for most of us, that’s a good enough reason to check it out.  Thats what's called Grass roots marketing, and it works.

“The average U.S. Internet user spends more time on Facebook than on Google, Yahoo, YouTube, Microsoft, Wikipedia and Amazon combined.”

That should tell you something. There is a big market to tap into, and should answer the question—why Facebook. Even if you think Facebook isn't a useful tool for you, you can’t argue with the numbers when it comes to reaching potential customers.

Why CFML with Facebook?

Hopefully your interest in ColdFusion and/or Railo answers this. Since CFML is such an easy to learn and powerful extensible programming language, it only makes sense that we should be able to build Facebook applications with it.

There are always some cautions with making websites talk to each other. Using CFML with Facebook is no different; however most of these have been overcome by people already, and you can easily zip through this by copy/pasting the work of others. The basic framework for my applications is the same, and you can use this as your jumping-off point to work on your own applications.

Understanding Data Flow

Facebook is rather unique in how it is structured, and understanding this structure is critical to being able to build applications properly. You will save yourself a lot of frustration by reviewing this section before you begin writing code.

In most websites or web applications, people type in a web address, and they connect directly to your web server, where your application handles the business logic, database interaction and any other work, and then gives web content back to the requesting user.

This is not the case with Facebook. With Facebook applications, users open up their web browsers to a Facebook web address (the “Canvas URL”), Facebook’s servers make a “behind the scenes” request to your web server (the “Callback URL”), your application then responds to Facebook’s request, and then, Facebook does the final markup and sends the web page content back to the user’s browser.

If you followed that, you see that users always interact with Facebook, while Facebook’s server is the one that talks to your application. You can also connect back to Facebook via their RESTful API to get information about users, friends, photos, posts and more. So here are two important concepts to understand:

  1. Your Facebook application code lives on your web server, separate from Facebook.
  2. You will get web requests from Facebook on behalf of Facebook users.
  3. Users should always be interacting with Facebook’s web site; They should never go directly to your web server

The Canvas URL is a Facebook address, which you will setup in the next section. The Callback URL is the root where you put your application files (*.cfc and *.cfm). It is also where you will put your CSS files, images, and anything else your application needs.

The Callback URL can be a directory on any web hosting account, so there is no need to setup a separate web host for your Facebook application.

Setting up a new Facebook application

Generally speaking, setting up a new Facebook application is pretty easy. There are a few things that can trip you up, and I will highlight them.

The first thing to do is log into your Facebook account, and authorize the Facebook Developer application by going to this URL:

Once you have authorized this application, you will see a link to create a new application.

Create a new application, and give it a name:

Fill in the description if you want, give it an icon and logo if you wish.

Click on the Canvas menu option.

Enter the canvas page url (this becomes the URL on facebook’s site that you and your users will go to –

Enter the callback URL (the full URL to YOUR web server directory where your CFML code will reside.

Very important: Select Render method to be “FBML” (which stands for Facebook Markup Language).

The other options you can leave as their default values.

When you are done, save your changes.

The application summary page will show you some important information, specifically the API Key and Application Secret, which you will need in your application later.

Consider using Facebook’s “sandbox” mode which makes your application invisible to the world while you are developing it. Likewise, when you are done with your application, consider using Facebook’s application directory to promote your application.

Setting up the application code

Here is the code for download. There are a few CFML files to help you get started. These include the base application files (Application.cfc, apiClient.cfc, _Application directory, and _includes directory) as well as sample files with code that you can copy/paste and fool around with.

To get started, copy the included files to your application’s directory (the Callback URL you defined in your Facebook Application) on your web server.

Next, edit _Application/fb_app_config.cfm file and set the apiKey, secret, appurl and callbackUrl variables. All of these are on the application summary screen in Facebook.

<cfset application.apiKey = "812f21368e7a88d4e2c729c10075b817">
<cfset application.secret = "99d7240e95210c514e98e5275d1131c9">
<cfset application.appurl = "">
<cfset application.callbackUrl = "">
<cfset application.adminUserIds = "">
<cfset application.permSessionKey = "">
<cfset application.requiredPermissions = "publish_stream">

The rest of the variables can be left as they are.

Now open up _Application/config.cfm and set the two variables:

<cfset application.datasource = "YourDatasource">
<cfset application.errorEmail = "">

If you have a database for your application, put the datasource name here.

Browsing the sample code

If you did all the above steps correctly, you should be able to open the Canvas URL in a web browser and get the sample index.cfm page I created.

Each tab in this collection of code shows how to use different features of Facebook application development.

Variables and Forms

When Facebook connects to your application on behalf of a Facebook user, it sends along a bunch of variables. These variables help you determine who is using your application, whether or not they have authorized your application and some other useful bits as well. If you click on the Variables tab, it will show a dump of variables that Facebook sends.

Getting started, the important ones you should note are FORM.fb_sig_user (the current user’s Facebook ID) and FORM.fb_sig_session_key (the Facebook user’s session key, which you need if you want to communicate directly with Facebook’s API).

The form example shows a simple web form, and once submitted, it passes back the form variables you expect along with the Facebook variables. The form example is nothing other than a way for you to see how your information gets passed back. It helps you see that it is still quite easy to implement plain html web forms.

Connecting to the Facebook API

The next tab labeled User Info makes a connection back to Facebook with the current user’s Facebook ID (FORM.fb_sig_user), and requests information from Facebook’s database. This example makes a request for user information using FQL or Facebook Query Language, which looks and functions similar to SQL (Structured Query Language).

In userinfo.cfm, you will see this code:

<cfset myFQL = "SELECT first_name,last_name,name, is_app_user,
has_added_app FROM user WHERE uid = #FB_SIG_USER#">
<cfset qrsData = application.apiClient.fqlQuery

This code requests information from the user object, and passes the user’s Facebook ID. The second line uses an API call and passes in the user’s session key, which is necessary to request information about any user.

There is a log of objects or “tables” containing information which you can get from Facebook using this API. Take a look at

FBML Goodies

One of the great things about Facebook application development is the built in FBML widgets. With just a few bits of code, you can add functionality to your application that would take many hours, days or months of coding to build on your own. If you use these tools properly, you can assemble a beautiful Facebook application with very minimal effort.

Lets take a moment and explain what FBML is. We already know that users go to your application, Facebook talks to your server, and gets the response back. Your response back from the server can contain FBML tags in its content. Now if you loaded those FBML tags into a plain html page and looked at it with a browser, they wouldn’t do anything, but if you put them in your application’s output, Facebook processes them (very much like Railo or ColdFusion processes tags), and replaces the tags with rich content.

For example, putting this code in your application’s output:


Facebook processes this and puts in an interactive mini wall where users can post comments! User’s comments, photos and links to the user’s profiles all get displayed. This is just one example of how a simple line of code yields fantastic functionality.

If you are displaying a bit of content, and you want users to be able to share it on their profile, you can add this line of code:

<fb:share-button class="url" href=""></fb:share_button>

And Facebook will create a “Facebook styled” share button. When you click it, it will automatically use Facebook’s system to share and post the link you specified, and will even pull a thumbnail photo for you.

The goodies page has these examples and a few more in-depth examples for you to play with.

Sending Requests

Facebook has made some significant changes to how Applications can contact users. In the past it was encouraged to use a “proxied email” address, however this is now discouraged. In its place, applications are encouraged to let users send invitations or “requests.”

In the sample code, take a look at request.cfm. This page lets you pick several friends from your friend list, and send them an invitation to look at a URL. This URL could be your application, or a news article, or anything else.

The request process handles some important logic to understand. First you will see a block of code that checks to see if the current Facebook user has provided the correct level of permission for you to send requests on their behalf:

<!-- check user permission level --->
<cfset askForPermission = false>
<cfset strArguments = StructNew()>
<cfset strArguments.ext_perm = "publish_stream">
<cfset strArguments.session_key = FB_SIG_SESSION_KEY>
<cfset rc = application.apiClient.
<cfif XmlParse(rc).XmlRoot.XmlText NEQ 1>
<cfset askForPermission = true>
<cfcatch type="any">
<cfset askForPermission = false>

The request process handles some important logic to understand. First you will see a block of code that checks to see if the current Facebook user has provided the correct level of permission for you to send requests on their behalf:

<!--- request higher permission from the user --->
<cfif askForPermission>
<script type="text/javascript">
function requestPermission()

This pops up a nice Facebook window and explains to the user that more permission is needed.

Once the user has given the proper access, and you fill out the request form, Facebook automatically handles processing the requests.

method="POST" type="Event" invite="false"
content="Come to my presentation at NCDevCon 2010!
label='Go There'>">
<fb:multi-friend-selector condensed="false" max="35"
showborder="false" actiontext="Invite your friends to come">
<fb:request-form-submit />

In this example, we also call an action page (request-action.cfm) which sets some variables and writes to the current user’s wall.

If all goes well, then all the users you selected will receive a custom request with the information you provide. You can use this technique to post relevant messages to a user’s wall after they perform certain actions, such as completing a survey, or beating a game.

Application Boxes and Application Tabs

Prior to Jan 2010, Facebook profiles had cool little boxes that you could put in the left side of your profile with custom content. These “profile boxes” were what everybody wanted to add to your profile. Well as of January 2010, Facebook is phasing those out. Instead of profile boxes, you can now add Application tabs. At the top of your profile you have a few tabs usually showing your Wall, photos and some others. When you authorize an application, if that application has defined an Application Tab URL, then you will also be able to add that Application as a tab.

Take a look in your Application settings, and you will see that you can specify a page to be called and a label for an Application Tab. Application tabs are unique in one respect, because once you add them to your profile, anybody can see them, whether they authorize the application or not. For this reason, it is important to note that when somebody clicks on your Application tab, it isn’t the user’s Facebook ID that is sent to your application, its YOUR Facebook ID that gets sent. This is one place where the rules change. So if Joe adds your app and adds an Application tab for it, and Sally clicks on Joe’s profile and on the application tab, when the request gets to your server, it will have Joe’s Facebook ID, not Sally’s.

Application tabs are useful for displaying information about the user whose profile you are on, so many applications will display that user’s last status or activities.

Take a look at tab.cfm in the sample code, which contains an entire Facebook Application by itself. It pulls news from an RSS feed, and dynamically displays comment boxes for each article.

This is a good application to play around with and get comfortable with how CFML and FBML interact.


This has been a quick overview of what you need to know to get your feet wet with Facebook application development using CFML. Take a look at the included sample code, as it is the best way to learn and build your own applications. Other places to look are Facebook’s developer documentation, which is always changing.

You've been reading an excerpt of:

ColdFusion 8 Developer Tutorial

Explore Title