/docs/ref/contrib/redirects.txt

 1=================
 2The redirects app
 3=================
 4
 5.. module:: django.contrib.redirects
 6   :synopsis: A framework for managing redirects.
 7
 8Django comes with an optional redirects application. It lets you store simple
 9redirects in a database and handles the redirecting for you.
10
11Installation
12============
13
14To install the redirects app, follow these steps:
15
16    1. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS`
17       setting.
18    2. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
19       to your :setting:`MIDDLEWARE_CLASSES` setting.
20    3. Run the command :djadmin:`manage.py syncdb <syncdb>`.
21
22How it works
23============
24
25``manage.py syncdb`` creates a ``django_redirect`` table in your database. This
26is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields.
27
28The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django
29application raises a 404 error, this middleware checks the redirects database
30for the requested URL as a last resort. Specifically, it checks for a redirect
31with the given ``old_path`` with a site ID that corresponds to the
32:setting:`SITE_ID` setting.
33
34    * If it finds a match, and ``new_path`` is not empty, it redirects to
35      ``new_path``.
36    * If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone")
37      HTTP header and empty (content-less) response.
38    * If it doesn't find a match, the request continues to be processed as
39      usual.
40
41The middleware only gets activated for 404s -- not for 500s or responses of any
42other status code.
43
44Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you
45can put ``RedirectFallbackMiddleware`` at the end of the list, because it's a
46last resort.
47
48For more on middleware, read the :doc:`middleware docs
49</topics/http/middleware>`.
50
51How to add, change and delete redirects
52=======================================
53
54Via the admin interface
55-----------------------
56
57If you've activated the automatic Django admin interface, you should see a
58"Redirects" section on the admin index page. Edit redirects as you edit any
59other object in the system.
60
61Via the Python API
62------------------
63
64.. class:: models.Redirect
65
66    Redirects are represented by a standard :doc:`Django model </topics/db/models>`,
67    which lives in `django/contrib/redirects/models.py`_. You can access redirect
68    objects via the :doc:`Django database API </topics/db/queries>`.
69
70.. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py