Debian Codegraph @

docs/ref/contrib/redirects.txt

raw
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`.