This series of articles aims, in the clear step-by-step style of the Django tutorial, to take you through the process of building a Django application that exists as both a simple web application, and also as a Facebook application. The web and Facebook applications will store information in the same database, using the same models, and thus users of one interface will be able to interact with the other.
Also, in the spirit of capitalism and entrepreneurship, we are going to invade the Django tutorial's turf and build a big and better toy polling application. At this moment venture capitalists are trembling across Silicon Valley at the hit to their pocket books due to these polling apps. Or something alone those lines.
Lets take a look at what we're going to accomplish over the next hour or three:
Building models that we will share between the web app and the Facebook app.
Using generic views to avoid writing as much code as possible.
Templates using both HTML and FBML (Facebook Markup Language) for rendering our content.
Using the Django testing framework to bring Test Driven Development to the web.
Using newforms to validate data, as well as represent it.
A few things this series is unfortunately not going to cover:
How to adapt command line instructions to a Windows. I don't have a Windows box to play with.
Setting up mod_python or any other deployment mechanism on your server.
This tutorial aims to cover a lot of ground, but don't worry, it doesn't expect much previous knowledge from you. As long as you have a terminal, Python, and Subversion, we're going to get through this together.
Now, lets get started.
The very first thing we need to do is to install Django. We are using the SVN version of Django, which at the time of this writing is version 6794. So lets grab a copy. First navigate to a place you want the library to live.
Personally mine is in a directory like this '/Users/will/django/'. But its entirely a personal stylistic choice. Choose a directory, and go there and then type:
svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk
This will checkout the most recent version of the Django trunk into a folder named 'django-trunk'.
Now we need to tell Python where Django is. Do that... we need to know where Python is. So lets find out:
This creates a symbolic link in your site-packages folder, so that Python can operate as if your you can installed your package there in the first place.
Lets confirm that this just worked. Lets fire up Python...
(The -v flag makes python very verbose about what it is doing, which is a bit painful for actually working with the interpreter, but not so bad now since we're just checking that an import works.) And now lets try to import Django.
>>>importdjangoimportdjango# directory django# django/__init__.pyc matches django/__init__.pyimportdjango# precompiled from django/__init__.pyc
If things are not set up correctly, you'll get this instead:
As long as you don't get an ImportError thrown, then you have correctly configured everything.
Setting up our project folder.
First we need to start a new Django project:
django-admin.py startproject polling
(If django-admin.py isn't in your path, then you'll need to refer to it via a relative or absolute path. It will be at "django-trunk/django/bin/django-admin.py", but you'll have to remember where you decided to checkout django-trunk.)
Now lets go into the project directory
And our project is born. Now we're going to create three applications, each of which will be responsible for a separate slice of our project.
Our three apps will be:
core: will hold our models, and all code that is not specific to either the web app or the Facebook app.
web: will hold all code and resources specific to our web app.
fb: will hold all code and resources specific to our Facebook app.
PyFacebook has some functionality for setting up special facebook oriented Django apps, but it isn't particularly helpful, so we'll be setting things up ourselves.
Setting up our fb app
First your want to [download this file][middleware_replacement] into the polling/fb directory. It is explained more here, but is basically an unsophisticated set of functions I put together to avoid using the PyFacebook middleware. Save it as helpers.py, so it should be sitting at
Okay. Now we want to open up and edit the views.py file in fb.
(Full disclosure: its actually okay to use something other than emacs. Although, I can't officially condone it.)
And you'll want to throw all of these imports into it:
Remember that these folders should be at polling/templates, polling/templates/fb, and polling/templates/web. We'll be telling Django where to find these folders in a moment, when we edit the settings.py file.
A brief lesson in tedium: settings.py
Okay, the heading may be overstating the case a bit, its just not my favorite part of setting up a Django project. Fortunately, it won't take very long either. I promise I'll endure as long as you do.
So we have two groups of things to deal with in settings.py, the generic Django setup, and setting up the entries we need for PyFacebook. Setting up PyFacebook is easier, so lets start with that.
You'll need to add these global variables (just paste em in anywhere, is the less snobby explanation) to your polling/settings.py file. *Please note that you'll need to change the first values to real values, supplied to you via the Developer application on Facebook.*
Since all our models will actually be living in polling.core, we don't actually have to add the polling.web and polling.fb apps to the list of installed apps, but its a bit more consistent to do so anyway (and if we don't, but later did add some models to one or the other, we might be very confused why they weren't being noticed).
Phew. We're done with messing with settings.py.
Using the Django devel server to serve media
Again, as I've mentioned before, we're working on putting together our development setup, not a production setup. We are going to use the devel server to serve our media, but only because its very convenient: this is not an adequate solution to real world static file serving.
Okay, with that warning out of the way, lets get to it.
First we need to make a few folders (starting from inside the polling folder):
And then we need to open up polling/urls.py for just a quick moment, and edit it so it looks like this:
Like usual, the reference to /Users/will/django/polling/media/ will have to be edited to reflect the location of your polling folder.
And we're done... setting up
If you didn't feel like doing all the changes yourself, [here is a zipped copy of my setup][polling1]. You will have to edit the polling/settings.py abd polling/urls.py to refer to the correct places on your system.