| ================= |
| 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 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 ``manage.py syncdb``. |
| |
| .. _INSTALLED_APPS: ../settings/#installed-apps |
| .. _MIDDLEWARE_CLASSES: ../settings/#middleware-classes |
| |
| How it works |
| ============ |
| |
| ``manage.py syncdb`` creates a ``django_redirect`` 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: ../settings/#site-id |
| .. _middleware docs: ../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.py`_. You can access redirect |
| objects via the `Django database API`_. |
| |
| .. _Django model: ../model_api/ |
| .. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py |
| .. _Django database API: ../db_api/ |