django / docs / redirects.txt

=================
The redirects app
=================

Django comes with an optional redirects application. It lets you store simple
redirects in a database and handles the redirecting for you.

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

To install the redirects app, follow these two steps:

    1. Add ``"django.contrib.redirects"`` to your INSTALLED_APPS_ setting.
    2. Add ``"django.contrib.redirects.middleware.RedirectFallbackMiddleware"``
       to your MIDDLEWARE_CLASSES_ setting.
    3. Run the command ``django-admin.py install redirects``.

.. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps
.. _MIDDLEWARE_CLASSES: http://www.djangoproject.com/documentation/settings/#middleware-classes

How it works
============

``django-admin.py install redirects`` creates a ``django_redirects`` table in
your database. This is a simple lookup table with ``site_id``, ``old_path`` and
``new_path`` fields.

The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django
application raises a 404 error, this middleware checks the redirects database
for the requested URL as a last resort. Specifically, it checks for a redirect
with the given ``old_path`` with a site ID that corresponds to the SITE_ID_
setting.

    * If it finds a match, and ``new_path`` is not empty, it redirects to
      ``new_path``.
    * If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone")
      HTTP header and empty (content-less) response.
    * If it doesn't find a match, the request continues to be processed as
      usual.

The middleware only gets activated for 404s -- not for 500s or responses of any
other status code.

Note that the order of ``MIDDLEWARE_CLASSES`` matters. Generally, you can put
``RedirectFallbackMiddleware`` at the end of the list, because it's a last
resort.

For more on middleware, read the `middleware docs`_.

.. _SITE_ID: http://www.djangoproject.com/documentation/settings/#site-id
.. _middleware docs: http://www.djangoproject.com/documentation/middleware/

How to add, change and delete redirects
=======================================

Via the admin interface
-----------------------

If you've activated the automatic Django admin interface, you should see a
"Redirects" section on the admin index page. Edit redirects as you edit any
other object in the system.

Via the Python API
------------------

Redirects are represented by a standard `Django model`_, which lives in
`django/contrib/redirects/models/redirects.py`_. You can access redirect
objects via the `Django database API`_.

.. _Django model: http://www.djangoproject.com/documentation/model_api/
.. _django/contrib/redirects/models/redirects.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models/redirects.py
.. _Django database API: http://www.djangoproject.com/documentation/db_api/
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.