Hello MiniFB.py: Tutorial

by Steven Chow
September 23, 2007 [Articles Index]

[View Hello MiniFB.py Facebook App] - [Discuss Hello MiniFB.py] - [View Source Code]

Introduction

This guide describes how to quickly get started building your own Facebook application by copying / installing the Hello MiniFB.py on your own server and using it as a base for your own application (the code is free to use and free of restrictions see code for more details). Hello MiniFB.py is basically a "Hello World" application a la Facebook which provides an initial skeleton for an Facebook application calling most of the Facebook APIs using minifb.py and implementing the callbacks required to create a full FBML application.

"Hello World" + minifb.py = "Hello MiniFB.y".

You should have some working knowledge of Python and mod_python. This tutorial just helps you get a skeleton application setup and working on your webserver, but you need to take the development from there.

Article Contents

Step 1. Get to know Hello MiniFB.py

 The first thing you may want to do is get acquainted with "Hello MiniFB.py" itself and adding it your account http://apps.facebook.com/hellominifb so you are familiar with how the application behaves (and know that it actually works). This may make it easier to understand when you're looking at the code and know what it should be like when you've copied it into your own app.

Some things you may want to notice so you can look for them later in the code:

  1. Most of the application is accessible without having to actually install it, however to leave a Testimonial or Invite Friends you have to add the application. Not requiring app adds can be a great way for you to be able to provide a feel for what your application is about before people add it to their Facebook account
  2. When you add the Hello MiniFB.py App it adds a simple message to your profile in a "Profile Module" (which btw you may want to remove once you've seen it)
  3. When you post a message to the Hello MiniFB.py Testimonials message board it adds a mini-feed entry to your profile
  4. If you "Invite Friends" it sends them a "hellominifb request" to check it out.

Step 2. Get Pre-requisites

 Now that you know what Hello MiniFB.py provides, there are a couple pieces of software that "Hello MiniFB.py" depends on that you will need before getting underway with this tutorial:
  1. apache2 - a commonly used open source webserver
  2. mod_python - an apache2 module that allows apache modules to be implemented using Python
  3. minifb.py v1.1 - a beautifully simple library that provides a good interface to call Facebook APIs and retrieve results
  4. simplejson.py - a simple library that parses json
You probably already have #1 and #2 installed on your system. For #3 and #4 you basically have to just download and untar/zip those files and place simplejson.py and minifb.py into a directory which you can include in your sys.path. Untar/zipping these files usually takes the form of the command: 
tar -xzvf minifb-1.1.tar.gz
tar -xzvf simplejson-1.7.1.tar.gz
I just put the resulting files into /home/[userid]/lib which for me is: 
/home/etienne/lib
Now that we have all the required software lets move onto setting things up. One important note here is that since Facebook is essentially proxing requests from the user to your webserver, your webserver has to be accessible from Facebook.com (i.e. not behind a home router somewhere)

Step 3. Test mod_python

 Now that you have all the prerequisites, lets configure this and test your basic setup and then get the Hello MiniFB.py code downloaded and configured. First create a directory to hold your application file: 
mkdir /var/www/hellominifb
Then edit your apache2.conf (or in some cases /etc/apache2/sites-available/default) and add in the necessary lines to let apache2 know how to execute Python files in that directory 
    # Hello MiniFB.py program for Facebook
    <Directory "/var/www/hellominifb>
       AddHandler mod_python .py
       PythonHandler mod_python.publisher
       DirectoryIndex hello.py
       PythonPath "sys.path+['/home/etienne/lib']"
    </Directory>
Make sure to substitute whichever directory you untarred your simplejson and minifb.py files into instead of '/home/etienne/lib' should be something like '/home/myuserid/lib' and also that you've put the appropriate directory for "/var/www" for your configuration. You may want to use a directory name more appropriate for your application than "hellominifb". At this point lets run a test to make sure that mod_python itself is working as we expect it. Create simpletest.py and include this code: 

def index(req):
   return "<html><h1>test mod_python</h1></html>"
Place this in your equivalent of /var/www/hellominifb and then visit the url using your browser. The url should roughly look like this with "yourservername" and "hellominifb" changed. 
http://yourservername.com/hellominifb/simpletest
You should see something like this as output:

Also here is simpletest runnig on my server so you can see what it should look like: simpletest. At this point you know that your mod_python setup is basically working.

Step 4. Test that "import minifb" works

Copy the "Hello MiniFB.py" code (i.e. hello.py) onto your server and verify that you've setup your sys.paths correctly and that hello.py can find and import minifb/simplejson.

Here is the code you need to download: hello.py

Make sure when you copy it into your equivalent of the /var/www/hellominifb directory that the file is actually named hello.py NOT hello.py.txt And now you can try to access the basic page to verify that it by going to: 

http://yourservername.com/hellominifb/
You should see a page similar to this: http://keepnix.com/hellominifb/ serving from your own server. If you haven't set your DirectoryIndex to hello.py in your apache2.conf as described above you may need to access it through http://yourservername.com/hellominifb/hello If there are problems you may get an "Internal Server Error" message and you can refer to your error_logs to see the stack trace (my error_logs are located at /var/log/apache2/error_log, but it varies by configuration).

Step 5. Get App Keys / Set up your Facebook Application on Facebook.com

 Now that the basic installation of your server / software is complete and working you can install the Facebook Developers application into your Facebook account and use it to tell Facebook about your new app. You'll also need to do this so that you can get your application key and application secret from Facebook. Click on "Set Up New Application":

Now enter your application name and open the "Optional Fields" area of the "Add Application" page. You see a section for "Optional Fields" (the first red X marked below) which you can open to display the rest of the fields you'll need to set.

Scroll down on the above screen shot of the "Add Application" page to see the 7 pertinent red X's that are important to configure. Remember to substitute your own servername instead of keepnix and own url name if you've changed the directory.

Once you've created your appication you can view your app keys by clicking on the "See My Apps" link (located just below the "+Set Up New Application" button on the Developers Application main page).

You can see the api key and app secret in the above image marked with 2 red x's.

Step 6. Configuring hello.py

Open hello.py (in my install it is at /var/www/hellominifb/hello.py) using your favorite text editor and go to the first section (labeled "[1] app settings"). There are five required settings and one optional setting: 

##################################################
# [1] app settings

_FbApiKey = ""
_FbSecret = minifb.FacebookSecret("")
_canvas_url = "http://apps.facebook.com/hellominifb"
_app_name = "Hello MiniFB.py"
_userdb = "/tmp/hellominifb.txt" # must be a file writable by the webserver

_google_analytics_id = None  # optional setting

Enter the apikey and the fbsecret key from Step 4 into the first two values and also set the _canvas_url to the url you specified from Step 4. At this point your setup and install of "Hello MiniFB.py" should be complete.

Step 7. Test your install

At this point you should be able to view your application through your app's canvas url: 
http://apps.facebook.com/yourappurl
and be able to add it to your Facebook account just like any other application. Remember if you have any problems you can check your apache error_log to see if there was an unhandled exception also you can refer to the Hello MiniFB.py Discussion Board or contact me.

Conclusion

That is it to getting the skeleton application working. You're basically ready to start adding in your own functionality. Please let me / other folks know this worked for you / your experience by posting on the Testimonials board. It took a little time to put this together so it would be nice to know if it helped someone.

I've tried to comment the hello.py code to make it straightforward to understand. Please let me know via the Hello MiniFB.py Discussion Board or contact me directoy if there are any areas that can be improved so it can be more easily understood. Also please send in any feedback / suggestions for what other features could be added to the skeleton, how this tutorial could be improved, etc.

© 2007 Steven Chow