django-facebook 5.0.1prealpha

Facebook open graph API client in python. Enables django applications to register users using facebook. Fixes issues with the official but unsupported Facebook python-sdk. Enables mobile facebook authentication. Canvas page authentication for facebook applications. FQL access via the server side api.

######################################################################
Django Facebook by Thierry Schellenbach (`mellowmorning.com <http://www.mellowmorning.com/>`_)
######################################################################

.. image:: https://secure.travis-ci.org/tschellenbach/Django-facebook.png?branch=master

**New in 4.0**

4.0 introduces improved compatiblity for the offline access migration.
I highly recommend upgrading. These are some of the awesome new features:

* Standalone registration support (we no longer require django userena and django registration)
* Local image storage is now easy to setup and enabled by default
* Automatic reauthentication for expired tokens (Great for the offline access migration)
* Travis - `CI tested <http://travis-ci.org/#!/tschellenbach/Django-facebook/>`

Backwards incompatible changes:

* You need to explicitly send connect_facebook=1 to connect an existing account to your Facebook account
* You need to specify a custom backend when using Django registration or Userena. See the section on django userena and django registration support.
* You should make sure your media settings are ok to support image upload

**The docs can also be found at: http://django-facebook.rtfd.org/**


Demo & About
------------

Django Facebook enables your users to easily register using the Facebook API.
It converts the Facebook user data and creates regular User and Profile objects.
This makes it easy to integrate with your existing Django application.
After registration it gives you access to user's graph. Allowing for applications such as:

* Open graph/ Timeline functionality
* Seamless personalization
* Inviting friends
* Finding friends
* Posting to a users profile

I've built it for my startup Fashiolista.com and it's currently used in production there with thousands of signups per day.
For a demo of the signup flow have a look at Fashiolista's landing page (`fashiolista.com <http://www.fashiolista.com/intro_wide_minimal/>`_)

Before you get started building your application, know that contributions are very welcome.
Seriously, if you see a bug or think of an improvement just open a pull request or issue.
Feel free to contact me if you have questions.

Updates and tutorials can be found on my blog `mellowmorning <http://www.mellowmorning.com/>`_

Further demos and tutorials will soon be available on `django-facebook.com <http://www.django-facebook.com/>`_



Features
--------

**Features**

* Access the Facebook API, from:
* Your website (Using javascript OAuth)
* Facebook canvas pages (For building facebook applications)
* Mobile (Or any other flow giving you a valid access token)
* Django User Registration (Convert Facebook user data into a user model)
* Store likes, friends and user data locally.
* Facebook FQL access
* OAuth 2.0 compliant
* Automated reauthentication (For expired tokens)
* Includes Open Facebook (stable and tested python client to the graph API)


Installation
------------

Download the source code or use ``pip install django_facebook``.


**Create a Facebook App**

You need a facebook app to use the open graph API and make the login process work.
If you don't have a facebook app, now is the time to create one.
You can create a facebook app at `this url <http://www.facebook.com/developers/createapp.php>`_.

Facebook authentication only works if the domain you are working on matches your app domain.
Be sure to configure the right app domain in your facebook application settings.

An example:

Your site is www.fashiolista.com, your app domain is set to fashiolista.com and you do your development at ``local.fashiolista.com``.
If you try to authenticate with Facebook from a different domain you will get an authentication error.

**Settings**

Define the following settings in your settings.py file:

::

FACEBOOK_APP_ID
FACEBOOK_APP_SECRET

**Url config, context processor, auth backend**

add django facebook to your installed apps::

'django_facebook',

Add this line to your context processors (``TEMPLATE_CONTEXT_PROCESSORS`` setting)::

'django_facebook.context_processors.facebook',

The full setting on a new django 1.4 app looks like this::

TEMPLATE_CONTEXT_PROCESSORS = (
'django_facebook.context_processors.facebook',
'django.contrib.auth.context_processors.auth',
'django.core.context_processors.debug',
'django.core.context_processors.i18n',
'django.core.context_processors.media',
'django.core.context_processors.static',
'django.core.context_processors.tz',
'django.contrib.messages.context_processors.messages',
)

Add this to your ``AUTHENTICATION_BACKENDS`` setting::

'django_facebook.auth_backends.FacebookBackend',

The full setting on a new django 1.4 app looks like this::

AUTHENTICATION_BACKENDS = (
'django_facebook.auth_backends.FacebookBackend',
'django.contrib.auth.backends.ModelBackend',
)

Now, add this line to your url config::

(r'^facebook/', include('django_facebook.urls')),
(r'^accounts/', include('django_facebook.auth_urls')), #Don't add this line if you use django registration or userena for registration and auth.


**Update your models**

Django uses a custom Profile model to store additional user information.
Read more about this topic in the `Django Docs <https://docs.djangoproject.com/en/dev/topics/auth/#storing-additional-information-about-users>`_.

If you don't already have a custom Profile model, simply uses the provided model by setting your AUTH_PROFILE_MODULE to FacebookProfile::

AUTH_PROFILE_MODULE = 'django_facebook.FacebookProfile'

Be sure to run manage.py syncdb after setting this up.

Otherwise Django Facebook provides an abstract model which you can inherit like this::

from django_facebook.models import FacebookProfileModel


class MyCustomProfile(FacebookProfileModel):
user = models.OneToOneField('auth.User')
....

from django.contrib.auth.models import User
from django.db.models.signals import post_save

#Make sure we create a MyCustomProfile when creating a User
def create_facebook_profile(sender, instance, created, **kwargs):
if created:
MyCustomProfile.objects.create(user=instance)

post_save.connect(create_facebook_profile, sender=User)

Don't forget to update your database using syncdb or south after this step.


Check the example & Customize!
------------------------------

Right now you should have a working registration/connect/login in flow available at /facebook/connect/
Test if everything is working and ensure you didn't miss a step somewhere.
If you encounter any difficulties please open an issue.


**Registration Backends**

Django Facebook uses registration backends to integrate with various registration frameworks.
No registration backend is required. However if you want to integrate with django registration,
django userena or a custom backend you need to point us in the right direction.

**Django Registration support**
Simply set your facebook registration backend to your preferred backend.

::

FACEBOOK_REGISTRATION_BACKEND = 'registration.backends.default.DefaultBackend'

**Django Userena support**

We recommend using Django Userena. It seems easier to work with than Django Registration.
Both are supported and good packages though.
To use django userena simply point to the userena compatability layer.

::

FACEBOOK_REGISTRATION_BACKEND = 'django_facebook.registration_backends.UserenaBackend'


Also have a look at the userena settings file in the facebook example project.
It provides a clear example of how to configure Userena and Django Facebook to work together.

**Old Django Registration Support**

Even older version of Django Registration are supported. Simply point to the old django registration
compatability backend.

::

FACEBOOK_REGISTRATION_BACKEND = 'django_facebook.registration_backends.OldDjangoRegistrationBackend'

Supporting any other registration system is quite easy.
Adjust the above settings to point to your own code.
Note that the form's save method needs to return the new user object.


**Common bugs**

Django Facebook expects that you are using static files in order to load the required javascript.
If you are not using staticfiles you should load facebook.js provided in the static directory manually.

Another common issue are the url matching settings from Facebook. Facebook requires you to fill in a domain for your application.
In order for things to work with local development you need to use the same domain. So if you production site is www.mellowmorning.com you
should run your development server on something like local.mellowmorning.com in order for facebook to allow authentication.

If you encounter any difficulties please open an issue.

**Customize and integrate into your site**

Not it's time to customize things a little.
For an example you can look at connect.html in the templates directory.

First load the css:

::

<link href="{{ STATIC_URL }}css/facebook.css" type="text/css" rel="stylesheet" media="all" />

Secondly load the javascript:

::

{% include 'django_facebook/_facebook_js.html' %}

If you encounter issues here you probably don't have django static files setup correctly.
Alternatively you might be missing the context processor.


Subsequently implement a form which calls Facebook via javascript.
Note that you can control which page to go to after connect using the next input field.

::

<form action="{% url facebook_connect %}?facebook_login=1" method="post">
<a href="javascript:void(0);" style="font-size: 20px;" onclick="F.connect(this.parentNode);">Register, login or connect with facebook</a>
<input type="hidden" value="{{ request.path }}" name="next" />
</form>



Signals
-------

Django-facebook ships with a few signals that you can use to easily accommodate Facebook related activities with your project.

``facebook_user_registered`` signal is sent whenever a new user is registered by Django-facebook, for example:

::

from django.contrib.auth.models import User
from django_facebook import signals

def fb_user_registered_handler(sender, user, facebook_data, \*\*kwargs):
# Do something involving user here

signals.facebook_user_registered.connect(user_registered, sender=User)


``facebook_pre_update`` signal is sent just before Django-facebook updates the profile model with Facebook data. If you want to manipulate Facebook or profile information before it gets saved, this is where you should do it. For example:

::

from django_facebook import signals
from django_facebook.utils import get_profile_class

def pre_facebook_update(sender, profile, facebook_data, \*\*kwargs):
profile.facebook_information_updated = datetime.datetime.now()
# Manipulate facebook_data here

profile_class = get_profile_class()
signals.facebook_pre_update.connect(pre_facebook_update, sender=profile_class)


``facebook_post_update`` signal is sent after Django-facebook finishes updating the profile model with Facebook data. You can perform other Facebook connect or registration related processing here.

::

from django_facebook import signals
from django_facebook.utils import get_profile_class

def post_facebook_update(sender, profile, facebook_data, \*\*kwargs):
# Do other stuff

profile_class = get_profile_class()
signals.facebook_post_update.connect(post_facebook_update, sender=profile_class)

``facebook_post_store_friends`` signal is sent after Django-facebook finishes storing the user's friends.

::

from django_facebook import signals
from django_facebook.utils import get_profile_class

def post_friends(sender, user, friends, current_friends, inserted_friends, \*\*kwargs):
# Do other stuff

profile_class = get_profile_class()
facebook_post_store_friends.connect(post_friends, sender=profile_class)

``facebook_post_store_likes`` signal is sent after Django-facebook finishes storing the user's likes. This is usefull if you want to customize what topics etc to follow.

::

from django_facebook import signals
from django_facebook.utils import get_profile_class

def post_likes(sender, user, likes, current_likes, inserted_likes, \*\*kwargs):
# Do other stuff

profile_class = get_profile_class()
facebook_post_store_likes.connect(post_likes, sender=profile_class)



Facebook App Center
-------------------

The Facebook App center requires your app to authenticate the user when landing on your site.
It already provides you with the required token. (Honestly I think it's a really weird user experience.)
But to get it working you must use the following url for site url (App -> Settings -> Basic -> Website with Facebook Login)

http://www.mydomain.com/facebook/connect/?facebook_login=1&attempt=1

Note that the given tokens can't be used for local testing. (Facebook checks the url for which the authorization was given.)


Contributing and Running tests
------------------------------
Tests are run from within the example project. You
can run them yourself as follows:

install from git

facebook_example/manage.py test django_facebook

Todo:

* Canvas utility functions (abstracting javascript redirects) (in progress)
* Token expiration detection (check out https://github.com/aidaeology/Django-facebook/commit/8585ce223e18cf19f410b4e6aa56b1478913162e for an older version of this concept)
* Improve testing


Django Jobs
-----------
Do you also see the beauty in clean code? Are you experienced with high scalability web apps?
Currently we're looking for additional talent over at our Amsterdam office.
Feel free to drop me a line at my personal email for more information: thierryschellenbach[at]gmail.com