This tutorial will show you how to build a simple Facebook application using Ruby on Rails and Facebook.

Contents

Introduction

Facebook applications are a great way to try out new social web ideas, no longer do you have to spend a dozen nights building a cool new website, only to leave it running for a few weeks and get less than a thousand unique visitors.

With Facebook applications you can leverage Facebook Markup Language (FBML), Facebooks authentication, your existing friend network and Facebooks viral promotion tools to get your app in front of more eyeballs.

Combined with Ruby on Rails, one of the best rapid application development tools, you can prototype an idea, put it in front of people and start getting feedback much much quicker.

Also – an often overlooked advantage of Facebook is that is has your non-technical friends on it, so you quickly get feedback from real people – not just your techie early adopter friends.

Feedback like“How do I send this to my friend? I want them to do this quiz”instead of “Oh man, you should’ve used XFBML+Jquery+SquidmooDB”

Facebook apps are about user engagement, measurement and growth, which is a different and interesting skillset from your usual web development role.

Anyway – I hope I have convinced you that Facebook applications are a great area to get into – so let’s get started.

 

What you will need

I will assume that you have rails installed on your system and you have done some of the Ruby on Rails tutorials. But to be sure – this tutorial expects you have:

• A working Rails 2.3 install.
  Run rails -v to get your rails version.

• Ability to install plugins via git.
  So you can install facebooker.

• A server you can use for a ssh tunnel.
  This is the simplest way to let facebook request pages from your development server. If you don’t have a server, slicehost is a good affordable solution, just get their smallest 256mb virtual machine.

Okay – so you’ve got those, got your macbook, a cup of coffee and a nice perch in your local coffee shop? Let’s go then.

Register your Application

Go to http://www.facebook.com/developers/createapp.php and create your application.

Enter name of your application, can be anything you like.

Then you will be taken to the ‘edit application’ form. There are plenty of options you can edit here, you should bookmark this page to come back and set a logo and description. For now, click ‘canvas’ on the left hand side and set a canvas page url.

The settings to create are:

Canvas Page URL: This is the URL to access your app. Many of these are gone and yours must be unique – so good luck finding something you like.

Canvas callback URL: This is the address that facebook uses to access your site – for your development site you should be:

http://yourslicehost.com:4007/

We will open an ssh reverse tunnel (via facebooker) to server port 4007 from your local dev environment.

Render Method: Set to FBML. Creating iframed pages isn’t covered in this tutorial.

Hit save and then bring up your terminal and get ready to do some rails.

You want to create two versions of your app – one for development and one for production. For the rest of this article we will be discussing setting up your development application. I tend to name my development applications with the dev suffix. For example /bestcities/ and /bestcitiesdev/.

Create your rails app

Open the terminal on your pc and type the following commands.

rails mygreatapp
cd mygreatapp
script/plugin install
git://github.com/mmangino/facebooker.git

Creating your first facebooker application

Then open mygreatapp in your text editor and open config/facebooker.yml. This file tells the facebooker plugin how to communicate securely with facebook. You have to configure your development environment before starting up your rails app. If you don’t configure facebooker.yml you will get an error when trying to start rails.

You need to go back to your ‘edit application’ form at facebook.com and copy out your API key and Secret. These go into the development section of facebooker.yml.

Getting your Application ID from facebook.com

development:
 api_key: 8b81627dfbdc1eac5d69f72d11ecb2083
 secret_key: 1f096ea634151345aa54a1a6dbb8db897bf
 canvas_page_name:
mygreatapp-dev
 callback_url:
http://bennolan.com:4007/

Configuring facebooker.yml with your application settings

The details you need to set are:

api_key Your API key from facebook

secret_key Your Applications secret key from facebook

canvas_page_name Address of your facebook page

callback_url Port 4007 (or another port number of your choice) of your
slicehost server.

You can leave the other settings to their default. You’re now ready to start development.

 

Creating your first view

Facebook application views use FBML. Because your html content is served embedded in a facebook page, you html is filtered and sanitized before being displayed. This means no javascript, no css to break out of frames etc.

Read more about FBML here:

http://wiki.developers.facebook.com/index.php/Category:FBML_tags

We will start by creating a welcome controller and generating a welcome view.

script/generate controller welcome

Create welcome controller

Then create a file in app/views/welcome/index.fbml.erb. This is a standard .erb and .html view, except if will only be served via facebook, and you can include facebook tags. Put this in your view:

<fb:header>My great application</fb:header>

<fb:tabs>
  <fb:tab-item href='<%= url_for :controller => 'welcome',
:action => 'index' %>' title='Home' selected='true'/>
  <fb:tab-item href='<%= url_for :controller => 'things',
:action => 'index' %>' title='Your things' />
</fb:tabs>

<p>
  Hi there <fb:name uid="loggedinuser" useyou="false" />!
Welcome to
  your first app.
</p>

app/views/welcome/index.fbml.erb

Now edit config/routes.rb and uncomment this line:

  map.root :controller => "welcome"

Enabling your default route

Start your engines

Bring up your terminal again. You need to start your local development server, and then make that server available to the wider internet. Do this like so:

script/server &
rake facebooker:tunnel:start &

Starting your facebook applicatio

Once your server has started, the second command will start a reverse ssh tunnel.

Now load http://apps.facebook.com/yourgreatapp_dev/ and you should be able to access your first facebooker application.

If you see this then you’re ready to go.

If it didn’t work – try these steps:

1. Load http://localhost:3000/ and check you get the ‘welcome to rails’ page

2. Load http://yourslicehost.com:4007/ and check you get the ‘welcome to rails’ page. If you don’t, either [a] your ssh tunnel didn’t start or [b] your server has a firewall running to prevent you getting access to port 4007

3. Check that your facebook application canvas page settings are set to http://yourslicehost.com:4007/

Once you have your rails app being served locally and displayed inside facebook you are ready to go!

Next steps

Now your basic application is going – you can start creating models and controllers. Facebooker will automatically correct your URLs so you can develop like normal. Your next best step is probably learning about authentication.

Check the Nolan Consulting site for further Facebooker tutorials.

http://www.nolanconsul.com/

The facebook developers wiki is a great reference source:

http://wiki.developers.facebook.com/

The facebooker rdoc documentation is available from rdoc.info:

http://rdoc.info/projects/mmangino/facebooker

To discuss with other facebook developers, try the forum:

http://forum.developers.facebook.com/