Copyright 2009 Ryan Mark


=Intro=
django-facebookconnect extends the builtin django auth system to let your visitors use thier facebook account to log into your site. It works with existing user accounts and django-registration (although django-registration isn't required). Your visitors can still use their django username and password, or they can log in with their facebook account and link it to their existing django user account. If they don't have an existing user account, they can login with facebook and a dummy django Uuser will get setup for them seamlessly.

==Installation==
I'm dumping the code for the first rev into source control. Just pull it out with svn and put the facebookconnect directory somewhere in your python path. Either in your application with your other apps, or in your python site-packages directory.

Make sure you have pyfacebook installed. You can get code and instructions on github: http://github.com/sciyoshi/pyfacebook/tree/master

django-facebookconnect only relies the django auth app, but it plays nice with django-registration if you would like to give your users the option to log in without facebook.

Add facebookconnect and django auth to your INSTALLED_APPS:

{{{
INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.sessions',

    'facebookconnect',
)
}}}

Both pyfacebook and django-facebookconnect have middleware that needs to be used. Middleware is a funny thing and is sensitive to the order in which it is executed. This order works:

{{{
MIDDLEWARE_CLASSES = (
    'django.contrib.sessions.middleware.SessionMiddleware',
    'facebook.djangofb.FacebookMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'facebookconnect.middleware.FacebookConnectMiddleware',
)
}}}

If you have other middleware, you may have to experiment with where in the list you should put your middleware. If you change the order of the stuff above, it will break.

Add the facebook to your authentication backends. If you dont have an AUTHENTICATION_BACKENDS directive in your settings, just use this one:

{{{
AUTHENTICATION_BACKENDS = (
    'listr.facebookconnect.models.FacebookBackend',
    'django.contrib.auth.backends.ModelBackend',
)
}}}

One more thing you may want to know about is the dummy facebook data. If, for whatever reason, the code can't retrieve facebook profile information for a user, it will use dummy data. Facebook Connect drops requests from time to time, so instead of killing the application, it will just show something. You can set the DUMMY_FACEBOOK_INFO directive in the settings file to change the default stuff. Here is what the default stuff looks like:

{{{
DUMMY_FACEBOOK_INFO = {
    'uid':0,
    'name':'(Private)',
    'first_name':'(Private)',
    'pic_square_with_logo':'/public/images/t_silhouette.jpg',
    'affiliations':None,
    'status':None,
    'proxied_email':None,
}
}}}

There is an issue with the builtin django User model handling the facebook proxy email addresses. The User model uses the default 75 char length for the email field and facebook proxy email addresses are super long. You might want to patch your User model to increase the limit to something like 200 chars. Or you can just use the email field on the facebook_profile object that hangs off the user object.

===facebook API===
Setup a facebook applicaiton here: http://upload.facebook.com . You'll need to have a personal facebook account to set this up. Once you add a facebook app, go to the connect section of the setup and provide the url for your facebook connect site (developers can enter localhost). Once you save the settings, you get an API key and secret. In your django settings file enter this stuff:

{{{
FACEBOOK_API_KEY = '00000000000000000000000000000000'
FACEBOOK_SECRET_KEY = '00000000000000000000000000000000'
FACEBOOK_INTERNAL = True
}}}

The third setting is for pyfacebook. I don't know what it does completely. But it does cause pyfacebook to hold on to expired facebook sessions when it's False.

===caching===
So you have to use caching with facebook connect. Especially if you plan to display profile info from your facebook connect users. Caching is being used no matter what, but if you don't configure it, django will just cache to memory for the execution and not for the long term. Or something. Its probably bad.

So read this http://docs.djangoproject.com/en/dev/topics/cache/ and setup database caching or memcached. There is one more setting directive you might be interested in:

{{{
#Cache facebook info for x seconds. Default is 30 minutes
FACEBOOK_CACHE_TIMEOUT = 1800
}}}

Django's cache framework rocks by the way.

==Using facebook connect==
Once you've got everything installed, all user objects will magically have a 'facebook_profile' object hanging off them. That is if the user has logged in with facebook. The FacebookProfile object has all sorts of nifty methods and properties.

There are templates that you can override. The setup screen is presented to a new facebook user when they first log in. A user can then choose to link their facebook account to an existing account or not.

There is a template tag library called facebook which has a bunch of shortcuts for displaying facebook profile information for a user. Put {% initialize_facebook_connect %} at the bottom of your base.html file. It will install the facebook javascript and contains some javascript functions for publishing data to a facebook feed. Put {% show_connect_button %} wherever you want a 'Connect with facebook' button.

There is also a management command called 'installfacebooktemplates'. This command loads a file called facebook_templates.py from the base of your project, loads them into facebook as templates for your application, and stores the reference ids in the db. You can get at those templates through the FacebookTemplate class.