| 1 |
================= |
| 2 |
The redirects app |
| 3 |
================= |
| 4 |
|
| 5 |
.. module:: django.contrib.redirects |
| 6 |
:synopsis: A framework for managing redirects. |
| 7 |
|
| 8 |
Django comes with an optional redirects application. It lets you store |
| 9 |
redirects in a database and handles the redirecting for you. It uses the HTTP |
| 10 |
response status code ``301 Moved Permanently`` by default. |
| 11 |
|
| 12 |
Installation |
| 13 |
============ |
| 14 |
|
| 15 |
To install the redirects app, follow these steps: |
| 16 |
|
| 17 |
#. Ensure that the ``django.contrib.sites`` framework |
| 18 |
:ref:`is installed <enabling-the-sites-framework>`. |
| 19 |
#. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting. |
| 20 |
#. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` |
| 21 |
to your :setting:`MIDDLEWARE` setting. |
| 22 |
#. Run the command :djadmin:`manage.py migrate <migrate>`. |
| 23 |
|
| 24 |
How it works |
| 25 |
============ |
| 26 |
|
| 27 |
``manage.py migrate`` creates a ``django_redirect`` table in your database. This |
| 28 |
is a lookup table with ``site_id``, ``old_path`` and ``new_path`` fields. |
| 29 |
|
| 30 |
The :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` |
| 31 |
does all of the work. Each time any Django application raises a 404 |
| 32 |
error, this middleware checks the redirects database for the requested |
| 33 |
URL as a last resort. Specifically, it checks for a redirect with the |
| 34 |
given ``old_path`` with a site ID that corresponds to the |
| 35 |
:setting:`SITE_ID` setting. |
| 36 |
|
| 37 |
* If it finds a match, and ``new_path`` is not empty, it redirects to |
| 38 |
``new_path`` using a 301 ("Moved Permanently") redirect. You can subclass |
| 39 |
:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` |
| 40 |
and set |
| 41 |
:attr:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_redirect_class` |
| 42 |
to :class:`django.http.HttpResponseRedirect` to use a |
| 43 |
``302 Moved Temporarily`` redirect instead. |
| 44 |
* If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone") |
| 45 |
HTTP header and empty (content-less) response. |
| 46 |
* If it doesn't find a match, the request continues to be processed as |
| 47 |
usual. |
| 48 |
|
| 49 |
The middleware only gets activated for 404s -- not for 500s or responses of any |
| 50 |
other status code. |
| 51 |
|
| 52 |
Note that the order of :setting:`MIDDLEWARE` matters. Generally, you can put |
| 53 |
:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` at the |
| 54 |
end of the list, because it's a last resort. |
| 55 |
|
| 56 |
For more on middleware, read the :doc:`middleware docs |
| 57 |
</topics/http/middleware>`. |
| 58 |
|
| 59 |
How to add, change and delete redirects |
| 60 |
======================================= |
| 61 |
|
| 62 |
Via the admin interface |
| 63 |
----------------------- |
| 64 |
|
| 65 |
If you've activated the automatic Django admin interface, you should see a |
| 66 |
"Redirects" section on the admin index page. Edit redirects as you edit any |
| 67 |
other object in the system. |
| 68 |
|
| 69 |
Via the Python API |
| 70 |
------------------ |
| 71 |
|
| 72 |
.. class:: models.Redirect |
| 73 |
|
| 74 |
Redirects are represented by a standard :doc:`Django model </topics/db/models>`, |
| 75 |
which lives in :source:`django/contrib/redirects/models.py`. You can access |
| 76 |
redirect objects via the :doc:`Django database API </topics/db/queries>`. |
| 77 |
For example: |
| 78 |
|
| 79 |
.. code-block:: pycon |
| 80 |
|
| 81 |
>>> from django.conf import settings |
| 82 |
>>> from django.contrib.redirects.models import Redirect |
| 83 |
>>> # Add a new redirect. |
| 84 |
>>> redirect = Redirect.objects.create( |
| 85 |
... site_id=1, |
| 86 |
... old_path="/contact-us/", |
| 87 |
... new_path="/contact/", |
| 88 |
... ) |
| 89 |
>>> # Change a redirect. |
| 90 |
>>> redirect.new_path = "/contact-details/" |
| 91 |
>>> redirect.save() |
| 92 |
>>> redirect |
| 93 |
<Redirect: /contact-us/ ---> /contact-details/> |
| 94 |
>>> # Delete a redirect. |
| 95 |
>>> Redirect.objects.filter(site_id=1, old_path="/contact-us/").delete() |
| 96 |
(1, {'redirects.Redirect': 1}) |
| 97 |
|
| 98 |
Middleware |
| 99 |
========== |
| 100 |
|
| 101 |
.. class:: middleware.RedirectFallbackMiddleware |
| 102 |
|
| 103 |
You can change the :class:`~django.http.HttpResponse` classes used |
| 104 |
by the middleware by creating a subclass of |
| 105 |
:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` |
| 106 |
and overriding ``response_gone_class`` and/or ``response_redirect_class``. |
| 107 |
|
| 108 |
.. attribute:: response_gone_class |
| 109 |
|
| 110 |
The :class:`~django.http.HttpResponse` class used when a |
| 111 |
:class:`~django.contrib.redirects.models.Redirect` is not found for the |
| 112 |
requested path or has a blank ``new_path`` value. |
| 113 |
|
| 114 |
Defaults to :class:`~django.http.HttpResponseGone`. |
| 115 |
|
| 116 |
.. attribute:: response_redirect_class |
| 117 |
|
| 118 |
The :class:`~django.http.HttpResponse` class that handles the redirect. |
| 119 |
|
| 120 |
Defaults to :class:`~django.http.HttpResponsePermanentRedirect`. |