==========================
Django Social Registration
==========================

Django Social Registration enables developers to add alternative registration
methods based on third party sites.

Requirements
============
django
oauth
python-openid
pyfacebook

Installation
============

#. Add the *socialregistration* directory to your *PYTHON_PATH*.
#. Add *socialregistration* to your *INSTALLED_APPS* settings of Django.
#. Add *socialregistration.urls* to your *urls.py* file.

Configuration
=============

Facebook Connect
----------------
#. Add *FACEBOOK_API_KEY* and *FACEBOOK_SECRET_KEY* to your settings file
   representing the keys you were given by Facebook.
#. Add *socialregistration.auth.FacebookAuth* to *AUTHENTICATION_BACKENDS* in your settings file.
#. Add 'facebook.djangofb.FacebookMiddleware' to *MIDDLEWARE_CLASSES* in your settings file.
   See http://wiki.developers.facebook.com/index.php/User:PyFacebook_Tutorial#Add_the_middleware

#.  Add tags to your template file: ::

    {% load facebook_tags %}
    {% facebook_button %}
    {% facebook_js %}

#. If you wish on using the pyfacebook library to do API calls instead of the JavaScript
   lib, add *socialregistration.middleware.FacebookMiddleware* to *MIDDLEWARE_CLASSES*

Twitter
-------
#. Add the following variables to your *settings.py* file with the values you
   were given by Twitter: ::

    TWITTER_CONSUMER_KEY
    TWITTER_CONSUMER_SECRET_KEY
    TWITTER_REQUEST_TOKEN_URL
    TWITTER_ACCESS_TOKEN_URL
    TWITTER_AUTHORIZATION_URL

#. Add *socialregistration.auth.TwitterAuth* to *AUTHENTICATION_BACKENDS* in your settings file.

#. Add tags to your template file: ::

    {% load twitter_tags %}
    {% twitter_button %}

Other OAuth Services
--------------------
There is an example of how FriendFeed integration could work.
*socialregistration.models* provides a *FriendFeedProfile* model to save account
data, *socialregistration.auth* provides examples for different auth backends for
different service providers, *socialregistration.utils* provides a Twitter
and FriendFeed interface and *socialregistration.urls* provides examples based
on Twitter and FriendFeed how to hook in more OAuth based services.

OpenID
------
#. Add *socialregistration.auth.OpenIDAuth* to *AUTHENTICATION_BACKENDS* in your settings file.
#. Add tags to your template file: ::

    {% load openid_tags %}
    {% openid_form %}

If you wish to use the OpenID extensions `Simple Registration <http://openid.net/specs/openid-simple-registration-extension-1_0.html>`_
(*sreg*) and `Attribute Exchange <http://openid.net/specs/openid-attribute-exchange-1_0.html>`_
(*ax*), you have to define *OPENID_REGISTRATION_FIELDS* in your settings, e.g.: ::

    OPENID_REGISTRATION_FIELDS = {'required': ['email', 'nickname']}

Currently, only the *sreg*-fields *email*, *nickname* and their equivalents from *ax*
are picked up by socialregistration. If the OpenID provider returns values for
these fields, they are automatically used as inital values for the setup form.

.. note:: setting a field to *required* doesn't guarantee that the OpenID provider
   will return a value for that field. On the other hand, some providers
   (e.g. Google) only return a value if the field *is* required.    

Logging users out
-----------------
You can use the standard {% url auth_logout %} url to log users out of Django.
Please note that this will not log users out of third party sites though.
When using Facebook Connect, it is recommended to follow the `FBConnect developer
wiki <http://wiki.developers.facebook.com/index.php/Connect/Authorization_Websites#Logging_Out_Users>`_: ::

    <a href="#" onclick="FB.Connect.logoutAndRedirect('{% url auth_logout %}')">Logout</a>

HTTPS
-----
If you wish everything to go through HTTPS, set *SOCIALREGISTRATION_USE_HTTPS* in your settings file to
True

Other Information
-----------------
If you don't wish your users to be redirected to the setup view to create a username but rather have
a username generated for them, set *SOCIALREGISTRATION_GENERATE_USERNAME* in your settings file to True