.. _installation:

Installation and configuration
==============================

Fandjango is best installed with `pip`_::

    $ pip install fandjango

.. _pip: http://www.pip-installer.org/en/latest/

.. _configuration:

Configuration
-------------

In your ``settings`` module...

* Add ``fandjango`` to ``INSTALLED_APPS``
* Add ``fandjango.middleware.FacebookMiddleware`` to ``MIDDLEWARE_CLASSES``
* Add ``url(r'^fandjango/', include('fandjango.urls'))`` to your patterns.
* Specify your Facebook application's id, secret key and namespace::

    FACEBOOK_APPLICATION_ID = '...'
    FACEBOOK_APPLICATION_SECRET_KEY = '...'
    FACEBOOK_APPLICATION_NAMESPACE = '...'

.. note::

    If you're using Django's CSRF protection middleware, you need to make sure Fandjango's
    middleware precedes it. Otherwise, Facebook's requests to your application will qualify
    as cross-site request forgeries.

Finally, synchronize your database::

    $ python manage.py syncdb

.. note::

    If you're using `South`_, run schema migrations instead.

Mobile/Web Middleware
^^^^^^^^^^^^^^^^^^^^^
``fandjango.middleware.FacebookWebMiddleware``
    Add beneath ``fandjango.middleware.FacebookMiddleware`` to support Facebook mobile apps and web based Facebook login.

Optional settings
^^^^^^^^^^^^^^^^^

``FACEBOOK_APPLICATION_CANVAS_URL``
    A string describing the Facebook application's canvas URL.

``FANDJANGO_DISABLED_PATHS``
    A list of regular expressions describing paths on which Fandjango should be disabled.

``FANDJANGO_ENABLED_PATHS``
    A list of regular expressions describing paths on which Fandjango should be enabled.

``AUTHORIZATION_DENIED_VIEW``
    A string describing a view that will be rendered for users that refuse to authorize the application.

``FACEBOOK_APPLICATION_INITIAL_PERMISSIONS``
    A list of strings describing `permissions <http://developers.facebook.com/docs/reference/api/permissions/>`_
    that will be requested upon authorizing the application.

``FANDJANGO_SITE_URL``
    Only applicable when using ``fandjango.middleware.FacebookWebMiddleware``. Determines where to redirect user post authentication. If not set, Fandjango will attempt to construct the redirect URL automatically.

.. _dependencies:

Dependencies
------------

In order to install and use Fandjango, you will need five primary pieces of software:

* `Python`_
* `Setuptools`_
* `Django`_
* `Facepy`_
* `Requests`_

.. _Python: http://python.org/
.. _Setuptools: http://pypi.python.org/pypi/setuptools
.. _Django: http://djangoproject.com
.. _Requests: http://github.com/kennethreitz/requests
.. _Facepy: http://github.com/jgorset/facepy

.. _development dependencies:

Development dependencies
------------------------

If you are interested in contributing to Fandjango, you will also need to install
some or all of the following packages:

* `Nose`_
* `Sphinx`_
* `South`_

For an up-to-date list of exact testing/development requirements, including version numbers, please
see the ``DEPENDENCIES`` file included with the source distribution. This file is intended to be used
with ``pip``, e.g. ``pip install -r DEPENDENCIES``.

.. _South: http://south.aeracode.org/
.. _Nose: http://readthedocs.org/docs/nose/en/latest/
.. _Sphinx: http://www.pip-installer.org/en/latest/

 .. _upgrading:

Upgrading
---------

You may have to change your database schema when you upgrade Fandjango. Thankfully,
Fandjango bundles `South`_ migrations and so upgrading your database is as simple as
running ``python manage.py migrate fandjango``.

If you're not using South, you're on your own.

.. _South: http://south.aeracode.org/

.. _source-code-checkouts:

Source code checkouts
---------------------

To follow Fandjango's development via Git instead of downloading official releases, please see our `Github mirror`_.

.. _Github mirror: http://github.com/jgorset/fandjango/