docs/redirects.txt

   1 =================
   2 The redirects app
   3 =================
   4
   5 Django comes with an optional redirects application. It lets you store simple
   6 redirects in a database and handles the redirecting for you.
   7
   8 Installation
   9 ============
  10
  11 To install the redirects app, follow these two steps:
  12
  13     1. Add ``"django.contrib.redirects"`` to your INSTALLED_APPS_ setting.
  14     2. Add ``"django.contrib.redirects.middleware.RedirectFallbackMiddleware"``
  15        to your MIDDLEWARE_CLASSES_ setting.
  16     3. Run the command ``django-admin.py install redirects``.
  17
  18 .. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps
  19 .. _MIDDLEWARE_CLASSES: http://www.djangoproject.com/documentation/settings/#middleware-classes
  20
  21 How it works
  22 ============
  23
  24 ``django-admin.py install redirects`` creates a ``django_redirects`` table in
  25 your database. This is a simple lookup table with ``site_id``, ``old_path`` and
  26 ``new_path`` fields.
  27
  28 The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django
  29 application raises a 404 error, this middleware checks the redirects database
  30 for the requested URL as a last resort. Specifically, it checks for a redirect
  31 with the given ``old_path`` with a site ID that corresponds to the SITE_ID_
  32 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
  41 The middleware only gets activated for 404s -- not for 500s or responses of any
  42 other status code.
  43
  44 Note that the order of ``MIDDLEWARE_CLASSES`` matters. Generally, you can put
  45 ``RedirectFallbackMiddleware`` at the end of the list, because it's a last
  46 resort.
  47
  48 For more on middleware, read the `middleware docs`_.
  49
  50 .. _SITE_ID: http://www.djangoproject.com/documentation/settings/#site-id
  51 .. _middleware docs: http://www.djangoproject.com/documentation/middleware/
  52
  53 How to add, change and delete redirects
  54 =======================================
  55
  56 Via the admin interface
  57 -----------------------
  58
  59 If you've activated the automatic Django admin interface, you should see a
  60 "Redirects" section on the admin index page. Edit redirects as you edit any
  61 other object in the system.
  62
  63 Via the Python API
  64 ------------------
  65
  66 Redirects are represented by a standard `Django model`_, which lives in
  67 `django/contrib/redirects/models/redirects.py`_. You can access redirect
  68 objects via the `Django database API`_.
  69
  70 .. _Django model: http://www.djangoproject.com/documentation/model_api/
  71 .. _django/contrib/redirects/models/redirects.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models/redirects.py
  72 .. _Django database API: http://www.djangoproject.com/documentation/db_api/