The redirects app

Ginger 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:

  1. Ensure that the ginger.contrib.sites framework is installed.

  2. Add 'ginger.contrib.redirects' to your INSTALLED_APPS setting.

  3. Add 'ginger.contrib.redirects.middleware.RedirectFallbackMiddleware' to your MIDDLEWARE setting.

  4. Run the command manage.py migrate.

How it works

manage.py migrate creates a ginger_redirect table in your database. This is a lookup table with site_id, old_path and new_path fields.

The RedirectFallbackMiddleware does all of the work. Each time any Ginger 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 using a 301 (“Moved Permanently”) redirect. You can subclass RedirectFallbackMiddleware and set response_redirect_class to ginger.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 MIDDLEWARE 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.

How to add, change and delete redirects

Via the admin interface

If you’ve activated the automatic Ginger 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 Ginger model, which lives in ginger/contrib/redirects/models.py. You can access redirect objects via the Ginger database API. For example:

>>> from ginger.conf import settings
>>> from ginger.contrib.redirects.models import Redirect
>>> # Add a new redirect.
>>> redirect = Redirect.objects.create(
...     site_id=1,
...     old_path="/contact-us/",
...     new_path="/contact/",
... )
>>> # Change a redirect.
>>> redirect.new_path = "/contact-details/"
>>> redirect.save()
>>> redirect
<Redirect: /contact-us/ ---> /contact-details/>
>>> # Delete a redirect.
>>> Redirect.objects.filter(site_id=1, old_path="/contact-us/").delete()
(1, {'redirects.Redirect': 1})

Middleware

class middleware.RedirectFallbackMiddleware

You can change the HttpResponse classes used by the middleware by creating a subclass of RedirectFallbackMiddleware and overriding response_gone_class and/or response_redirect_class.

response_gone_class

The HttpResponse class used when a Redirect is not found for the requested path or has a blank new_path value.

Defaults to HttpResponseGone.

response_redirect_class

The HttpResponse class that handles the redirect.

Defaults to HttpResponsePermanentRedirect.