4a954cfd11
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
101 lines
3.8 KiB
Plaintext
101 lines
3.8 KiB
Plaintext
=================
|
|
The redirects app
|
|
=================
|
|
|
|
.. module:: django.contrib.redirects
|
|
:synopsis: A framework for managing redirects.
|
|
|
|
Django comes with an optional redirects application. It lets you store
|
|
redirects in a database and handles the redirecting for you. It uses the HTTP
|
|
response status code ``301 Moved Permanently`` by default.
|
|
|
|
Installation
|
|
============
|
|
|
|
To install the redirects app, follow these steps:
|
|
|
|
#. Ensure that the ``django.contrib.sites`` framework
|
|
:ref:`is installed <enabling-the-sites-framework>`.
|
|
#. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
|
|
#. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
|
|
to your :setting:`MIDDLEWARE` setting.
|
|
#. Run the command :djadmin:`manage.py migrate <migrate>`.
|
|
|
|
How it works
|
|
============
|
|
|
|
``manage.py migrate`` creates a ``django_redirect`` table in your database. This
|
|
is a lookup table with ``site_id``, ``old_path`` and ``new_path`` fields.
|
|
|
|
The :class:`~django.contrib.redirects.middleware.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
|
|
:setting:`SITE_ID` setting.
|
|
|
|
* If it finds a match, and ``new_path`` is not empty, it redirects to
|
|
``new_path`` using a 301 ("Moved Permanently") redirect. You can subclass
|
|
:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
|
|
and set
|
|
:attr:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_redirect_class`
|
|
to :class:`django.http.HttpResponseRedirect` to use a
|
|
``302 Moved Temporarily`` redirect instead.
|
|
* 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 :setting:`MIDDLEWARE` matters. Generally, you can put
|
|
:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` at the
|
|
end of the list, because it's a last resort.
|
|
|
|
For more on middleware, read the :doc:`middleware docs
|
|
</topics/http/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
|
|
------------------
|
|
|
|
.. class:: models.Redirect
|
|
|
|
Redirects are represented by a standard :doc:`Django model </topics/db/models>`,
|
|
which lives in :source:`django/contrib/redirects/models.py`. You can access
|
|
redirect objects via the :doc:`Django database API </topics/db/queries>`.
|
|
|
|
Middleware
|
|
==========
|
|
|
|
.. class:: middleware.RedirectFallbackMiddleware
|
|
|
|
You can change the :class:`~django.http.HttpResponse` classes used
|
|
by the middleware by creating a subclass of
|
|
:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
|
|
and overriding ``response_gone_class`` and/or ``response_redirect_class``.
|
|
|
|
.. attribute:: response_gone_class
|
|
|
|
The :class:`~django.http.HttpResponse` class used when a
|
|
:class:`~django.contrib.redirects.models.Redirect` is not found for the
|
|
requested path or has a blank ``new_path`` value.
|
|
|
|
Defaults to :class:`~django.http.HttpResponseGone`.
|
|
|
|
.. attribute:: response_redirect_class
|
|
|
|
The :class:`~django.http.HttpResponse` class that handles the redirect.
|
|
|
|
Defaults to :class:`~django.http.HttpResponsePermanentRedirect`.
|