Usage

Get django-la-facebook into your python path:

pip install django-la-facebook

Add la_facebook to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = (
    ...
    'la_facebook',
    ...
    )

Add la_facebook to your root urlconf (urls.py):

urlpatterns = patterns('',
    ...,
    url(r"^la_facebook/", include("la_facebook.urls")),
    ...,
)

Settings

In order to authenticate your site’s users with Facebook, you need a unique identifier for Facebook to associate your site with. Facebook considers your site an “app” and so you must acquire an FACEBOOK_APP_ID and FACEBOOK_APP_SECRET from the Facebook Developer app.

You will need to enter your sites domain into the Facebook developer app, and the site will restrict authentication requests to that domain. For initial testing and experiments, you will want to enter “http://localhost/” for the website URL. For later testing, you will probably want create a staging or testing subdomain. The domain set here must match the domain entered into Django’s sites framework.

See the documentation for Settings about how to enter these values in your Django settings file.

Using the default authentication flow

By default, the la_facebook application:

  • provides a method of creating a django.contrib.auth user model for an authenticated facebook user
  • Updates fields in the model pointed to by the AUTH_PROFILE_MODULE setting that match available fields in Facebook’s user data.
  • Creates and manages an association object that stores the user’s associated facebook id, authentication token (which is used to access the information in the users facebook profile as authorized by the user), and the expiration date of that token.

These steps are handled by directing a user to the la_facebook login view. By default this view, like Django’s login url LOGIN_URL, will use a next querystring parameter to redirect the browser to a page after user authenticates with Facebook.

If an error occurs during authentication, or the user denies to authenticate, the browser is redirected to a template located at la_facebook/fb_error.html (see the provided template for some information about what context variables may be provided in the case of an error).

If you wish a more customized behavior for Facebook authentication, see the Callbacks documentation.

Templates

In your login page, or as part of your login form, you should include a link to the Facebook login view, which will then redirect the user to facebook to login and authenticate to your site. A simple example might look like this:

<p><a href="{% url la_facebook_login %}?next={{ next }}">Login with FaceBook</a></p>

You can used the following image provided by facebook as a graphical link:

http://static.ak.fbcdn.net/images/fbconnect/login-buttons/connect_light_medium_long.gif

Other than the error template mentioned above, no particular templates are used or customized.

Changing the display layout of the login page

By default the login flow redirects you to facebook for login in your main browser window, and the layout of this page is suited to be a complete page. Facebook also supports an alternate “popup” display style, which is better suited for popup windows. This can reduce the feeling that the user is leaving your site. You must pass the display:popup option to the login view in your own project urls.py, and you must handle the creation and destruction of the actual popup window yourself.

Template Tags

TODO