Fandjango

Facebook applications are simply websites that load in iframes on Facebook. Facebook provide documents loaded within these iframes with various data, such as information about the user accessing it or the Facebook Page it is accessed from. This data is encapsulated in signed requests.

Fandjango is a module that parses signed requests, abstracts the information contained within and populates the request object accordingly.

Getting started

You may find a sample application and a walkthrough to replicate it at the Fandjango Example repository.

Usage:

Users

Fandjango saves clients that have authorized your application in its User model. You may access the corresponding model instance in request.facebook.user.

Instances of the User model have the following properties:

 facebook_id - An integer describing the user's Facebook ID.
 facebook_username - A string describing the user's Facebook username.
 first_name - A string describing the user's first name.
 last_name - A string describing the user's last name.
 profile_url - A string describing the URL to the user's Facebook profile.
 gender - A string describing the user's gender.
 hometown - A string describing the user's home town (requires 'user_hometown' extended permission).
 location - A string describing the user's current location (requires 'user_location' extended permission).
 bio - A string describing the user's "about me" field on Facebook (requires 'user_about_me' extended permission).
 relationship_status - A string describing the user's relationship status (requires 'user_relationships' extended permission).
 political_views - A string describing the user's political views (requires 'user_religion_politics' extended permission).
 email - A string describing the user's email address (requires 'email' extended permission).
 website - A string describing the user's website (requires 'user_website' extended permission).
 locale - A string describing the user's locale.
 verified - A boolean describing whether or not the user is verified by Facebook.
 birthday - A datetime object describing the user's birthday (requires 'user_birthday' extended permission)
 oauth_token - An OAuth Token object.
 created_at - A datetime object describing when the user was registered.
 last_seen_at - A datetime object describing when the user was last seen.

You may synchronize these properties with Facebook at any time with the model's synchronize method.

oauth_token is an instance of the OAuthToken model, which has the following properties:

- token - A string describing the OAuth token itself.
- issued_at - A datetime object describing when the token was issued.
- expires_at - A datetime object describing when the token expires (or None if it doesn't)

If the client has not authorized your application, request.facebook.user is None.

Authorizing users

You may require a client to authorize your application before accessing a view with the facebook_authorization_required decorator.

from fandjango.decorators import facebook_authorization_required

@facebook_authorization_required()
def foo(request, *args, **kwargs):
 pass

This will redirect the request to the Facebook authorization dialog, which will in turn redirect back to the original URI. The decorator accepts an optional argument redirect_uri, allowing you to customize the location the user is redirected to after authorizing the application:

from settings import FACEBOOK_APPLICATION_TAB_URL
from fandjango.decorators import facebook_authorization_required

@facebook_authorization_required(redirect_uri=FACEBOOK_APPLICATION_TAB_URL)
def foo(request, *args, **kwargs):
 pass

If you prefer, you may redirect the request in a control flow of your own by using the redirect_to_facebook_authorization function:

from fandjango.utils import redirect_to_facebook_authorization

def foo(request, *args, **kwargs):
 if not request.facebook.user:
 return redirect_to_facebook_authorization(redirect_uri='http://www.example.org/')

Pages

If the application is accessed from a tab on a Facebook Page, you'll find an instance of FacebookPage in request.facebook.page.

Instances of the FacebookPage model have the following properties:

- id -- An integer describing the id of the page.
- is_admin -- A boolean describing whether or not the current user is an administrator of the page.
- is_liked -- A boolean describing whether or not the current user likes the page.
 url -- A string describing the URL to the page.

If the application is not accessed from a tab on a Facebook Page, request.facebook.page is None.

What is new in this release:

• Fandjango will now set request.facebook to False for invalid signed requests rather than raising an exception.
• Fandjango now uses the latest versions of requests and facepy.

What is new in version 4.0.6:

• Fandjango will now only extend OAuth tokens that have not already been extended.

What is new in version 4.0.5:

• Fandjango will now ignore internal Facebook Errors upon attempting to extend an access token.

What is new in version 4.0.4:

• Fixed a bug that caused the 'redirect_uri' argument to 'facebook_authorization_required' to be ignored.

What is new in version 4.0.3:

• You may now set view-specific permissions.
• Added User#permissions.
• Added FACEBOOK_APPLICATION_CANVAS_URL setting.
• OAuth tokens are now extended (see Deprecation of Offline Access Permission)
• Fixed an issue that prevented users from authorizing applications under Internet Explorer.

What is new in version 4.0.2:

• Fixed a bug that caused an AttributeError upon issuing a HTTP GET request to the deauthorization view.
• Fixed a bug that caused application deauthorization to fail.
• Fixed a bug that prevented the norwegian localization from being applied.

Requirements:

• Python