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