How to build a Facebook app in Django

Facebook has a simple and robust API which allows users to build applications for the Facebook platform. We being the intelligent developers will use the superb Django framework to build our application.

The completed code for this is available at The completed application is deployed to facebook here.

How does a Facebook application work?

  1. The users make a request to
  2. The Facebook servers make a request to
  3. You get the requests and can make calls to Facebook API, and use FQL to query the Facebook tables.
  4. You send back a page written in FBML to FB servers.
  5. FB servers render your FBML to HTML.
  6. FB servers send a HTML request to the user.

What tools does FB provide you?

  1. FQL: Facebook Query Language. This is a language similar to SQL. Sample this

SELECT name, pic FROM user WHERE uid=211031 OR uid=4801660

  1. Facebook API: This is a set of RESTful urls which can be used to get data from Facebook and to do actions on the behalf of the logged in users.

  2. FBML: Facebook Markup Language. This is a set of tags, similar to Html tags, which allow you to get your page rendered with extra information on the facebook servers.

<fb:name uid="211031">

would show the name of the user with the id.

What else do you need?

  1. A server, which can run Django. Duh.
  2. We are using Python, so we can use FB rest API directly. But somebody has already done the hard work and written the awesome Pyfacebook library, which makes talking to Facebook a breeze.

What will we build?

We will build a application which allows you to store your favorite programming language at Facebook. This has a single page with single input box where you can store your favorite programming language.

The completed code for this is available at The completed application is deployed to facebook here.

Getting Started

  1. Go to
  2. Create a new app, give it a name.
  3. Get your application api key, and application secret.
  4. Map callback url to the base of your Server.
  5. Download the Pyfacebook library, and put it where Python can find it. The following import statements should work. import facebook and import facebook.djangofb

Setting up your App

  1. Edit and add the following settings.

    FACEBOOK_API_KEY = '1673458a9d3ddaa8c6f888d7150da256' FACEBOOK_SECRET_KEY = '666197caab406752474bd0c6695a53f6'

  2. Add facebook.djangofb.FacebookMiddleware to MIDDLEWARE_CLASSES

  3. Create an app named Favlang to hold our Code.

Our App

Its a simple Django app with Models, views and Urls. The only difference with a normal Django app is that, a. The templates are in FBML. b. We will use FQL and FBAPI to talk to FB.

from django.conf.urls.defaults import *

urlpatterns = patterns('favlang.views',
    (r'^$', 'canvas'),

A basic Urlpatter, mapping patterns to views, nothing FB specific to see here.

from django.db import models

class FacebookUser(models.Model):
    """A simple User model for Facebook users."""

    # We use the user's UID as the primary key in our database.
    id = models.IntegerField(primary_key=True)
    language = models.CharField(max_length=64, default='Python')

A normal Nothing FB specific to see here. (Instead of an autoincrementing PK, we have a PK which we will set manually to FB uid.)

from django.http import HttpResponse
from django.views.generic.simple import direct_to_template

import facebook.djangofb as facebook

from favlang.models import FacebookUser

def canvas(request):
    # Get the User object for the currently logged in user
    user, created = FacebookUser.objects.get_or_create(id = request.facebook.uid)

    # Check if we were POSTed the user's new language of choice
    if 'language' in request.POST:
        user.language = request.POST['language'][:64]

    # User is guaranteed to be logged in, so pass canvas.fbml
    # an extra 'fbuser' parameter that is the User object for
    # the currently logged in user.
    return direct_to_template(request, 'favlang/canvas.fbml', extra_context={'fbuser': user})

Ok. SO finally something FB specific. Lets see what is happening behind the scenes.

  1. We are putting our view behind a @facebook.require_login() decorator. This is similar to the login_required decorator. It makes sure that a valid FB user is logged in before it allows access to our view.

  2. The Middleware facebook.djangofb.FacebookMiddleware attaches a facebook object to the request, which provides access to the logged in user and some other relevant data.

  3. We created a FacebookUser for the currently logged in user, in our database, with this line.

user, created = FacebookUser.objects.get_or_create(id = request.facebook.uid)

  1. We returned the FBML with our data. The FBML is parsed by the Facebook servers and HTML returned to the user.

The template

  Welcome, <fb:name uid="" firstnameonly="true" useyou="false">!

<div class="clearfix" style="border: 1px solid rgb(216, 223, 234); padding: 10px; float: left; margin-left: 30px; margin-bottom: 30px; width: 500px;">
  Your favorite language is .

  <div class="grayheader clearfix">

    <form action="." method="post">
      <input name="language" value="" type="text">
      <input value="Change" type="submit">

This template is written in FBML. FBML is a superset of HTML. The tags which start with <fb: are=”” facebook=”” specific=”” tags.=”” for=”” example=”” the=”” tag=”” fb:name=”” =""><fb:name uid="" firstnameonly="true" useyou="false"> renders the name of the user whose uid is passed in uid.

There is also a form which allows user to change their Favorite language. In this is handled as

if 'language' in request.POST:
    user.language = request.POST['language'][:64]


  1. Facebook developers.
  2. Facebook developers wiki.
  3. Facebook developers forum.
  4. [Pyfacebook]
  5. FBAPI Documentation
  6. FQL Documentation
  7. FBML Documentation

  8. Code listing
  9. Live Application


Thank you for reading the Agiliq blog. This article was written by shabda on Feb 20, 2009 in facebook .

You can subscribe ⚛ to our blog.

We love building amazing apps for web and mobile for our clients. If you are looking for development help, contact us today ✉.

Would you like to download 10+ free Django and Python books? Get them here