The Django Book

Example 1: Reusing data on multiple sites

As we explained in Chapter 1, the Django-powered sites LJWorld.com and Lawrence.com are operated by the same news organization — the Lawrence Journal-World newspaper in Lawrence, Kansas. LJWorld.com focuses on news, while Lawrence.com focuses on local entertainment. But sometimes editors want to publish an article on both sites.

The brain-dead way of solving the problem would be to use a separate database for each site, and to require site producers to publish the same story twice: once for LJWorld.com and again for Lawrence.com. But that’s inefficient for site producers, and it’s redundant to store multiple copies of the same story in the database.

The better solution is simple: Both sites use the same article database, and an article is associated with one or more sites via a many-to-many relationship. The Django sites framework provides the database table to which articles can be related. It’s a hook for associating data with one or more “sites.”

Example 2: Storing your site name/domain in one place

LJWorld.com and Lawrence.com both have e-mail alert functionality, which lets readers sign up to get notifications when news happens. It’s pretty basic: A reader signs up on a Web form, and he immediately gets an e-mail saying, “Thanks for your subscription.”

It’d be inefficient and redundant to implement this signup-processing code twice, so the sites use the same code behind the scenes. But the “thank you for signing up” notice needs to be different for each site. By using Site objects, we can abstract the “thank you” notice to use the values of the current site’s name (e.g., 'LJWorld.com') and domain (e.g., 'www.ljworld.com').

The Django sites framework provides a place for you to store the name and domain for each site in your Django project, which means you can reuse those values in a generic way.

Using the sites framework

The sites framework is more of a series of conventions than a framework. The whole thing is based on two simple concepts:

• The Site model, found in django.contrib.sites, has domain and name fields.
• The SITE_ID setting specifies the database ID of the Site object associated with that particular settings file.

How you use these two concepts is up to you, but Django uses them in a couple of ways automatically via simple conventions.

To install the sites app, follow these steps:

1. Add 'django.contrib.sites' to your INSTALLED_APPS.
2. Run the command manage.py syncdb to install the django_site table into your database.
3. Add one or more Site objects, either through the Django admin site or via the Python API. Create a Site object for each site/domain that this Django project powers.
4. Define the SITE_ID setting in each of your settings files. This value should be the database ID of the Site object for the site powered by that settings file.

Things you can do with the sites framework

from django.db import models
from django.contrib.sites.models import Site

class Article(models.Model):
    headline = models.CharField(maxlength=200)
    # ...
    sites = models.ManyToManyField(Site)

from django.conf import settings

def article_detail(request, article_id):
    try:
        a = Article.objects.get(id=article_id, sites__id=settings.SITE_ID)
    except Article.DoesNotExist:
        raise Http404
    # ...

from django.db import models
from django.contrib.sites.models import Site

class Article(models.Model):
    headline = models.CharField(maxlength=200)
    # ...
    site = models.ForeignKey(Site)

from django.conf import settings

def my_view(request):
    if settings.SITE_ID == 3:
        # Do something.
    else:
        # Do something else.

from django.conf import settings
from django.contrib.sites.models import Site

def my_view(request):
    current_site = Site.objects.get(id=settings.SITE_ID)
    if current_site.domain == 'foo.com':
        # Do something
    else:
        # Do something else.

from django.contrib.sites.models import Site

def my_view(request):
    current_site = Site.objects.get_current()
    if current_site.domain == 'foo.com':
        # Do something
    else:
        # Do something else.

from django.contrib.sites.models import Site
from django.core.mail import send_mail

def register_for_newsletter(request):
    # Check form values, etc., and subscribe the user.
    # ...
    current_site = Site.objects.get_current()
    send_mail('Thanks for subscribing to %s alerts' % current_site.name,
        'Thanks for your subscription. We appreciate it.\n\n-The %s team.' % current_site.name,
        'editor@%s' % current_site.domain,
        [user_email])
    # ...

from django.core.mail import send_mail
from django.template import loader, Context

def register_for_newsletter(request):
    # Check form values, etc., and subscribe the user.
    # ...
    subject = loader.get_template('alerts/subject.txt').render(Context({}))
    message = loader.get_template('alerts/message.txt').render(Context({}))
    send_mail(subject, message, 'do-not-reply@example.com', [user_email])
    # ...

>>> from django.contrib.sites.models import Site
>>> obj = MyModel.objects.get(id=3)
>>> obj.get_absolute_url()
'/mymodel/objects/3/'
>>> Site.objects.get_current().domain
'example.com'
>>> 'http://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url())
'http://example.com/mymodel/objects/3/'

The CurrentSiteManager

If Sites play a key role in your application, consider using the helpful CurrentSiteManager in your model(s). It’s a model manager (see Chapter 5) that automatically filters its queries to include only objects associated with the current Site.

Use CurrentSiteManager by adding it to your model explicitly. For example:

from django.db import models
from django.contrib.sites.models import Site
from django.contrib.sites.managers import CurrentSiteManager

class Photo(models.Model):
    photo = models.FileField(upload_to='/home/photos')
    photographer_name = models.CharField(maxlength=100)
    pub_date = models.DateField()
    site = models.ForeignKey(Site)
    objects = models.Manager()
    on_site = CurrentSiteManager()

With this model, Photo.objects.all() will return all Photo objects in the database, but Photo.on_site.all() will return only the Photo objects associated with the current site, according to the SITE_ID setting.

In other words, these two statements are equivalent:

Photo.objects.filter(site=settings.SITE_ID)
Photo.on_site.all()

How did CurrentSiteManager know which field of Photo was the Site? It defaults to looking for a field called site. If your model has a ForeignKey or ManyToManyField called something other than site, you need to explicitly pass that as the parameter to CurrentSiteManager. The following model, which has a field called publish_on, demonstrates this:

from django.db import models
from django.contrib.sites.models import Site
from django.contrib.sites.managers import CurrentSiteManager

class Photo(models.Model):
    photo = models.FileField(upload_to='/home/photos')
    photographer_name = models.CharField(maxlength=100)
    pub_date = models.DateField()
    publish_on = models.ForeignKey(Site)
    objects = models.Manager()
    on_site = CurrentSiteManager('publish_on')

If you attempt to use CurrentSiteManager and pass a field name that doesn’t exist, Django will raise a ValueError.

Finally, note that you’ll probably want to keep a normal (non-site-specific) Manager on your model, even if you use CurrentSiteManager. As explained in Chapter 5, if you define a manager manually, then Django won’t create the automatic objects = models.Manager() manager for you. Also, note that certain parts of Django — namely, the Django admin site and generic views — use whichever manager is defined first in the model, so if you want your admin site to have access to all objects (not just site-specific ones), put objects = models.Manager() in your model, before you define CurrentSiteManager.

How Django uses the sites framework

Although it’s not required that you use the sites framework, it’s strongly encouraged, because Django takes advantage of it in a few places. Even if your Django installation is powering only a single site, you should take the two seconds to create the site object with your domain and name, and point to its ID in your SITE_ID setting.

Here’s how Django uses the sites framework:

• In the redirects framework (see “Redirects” below), each redirect object is associated with a particular site. When Django searches for a redirect, it takes into account the current SITE_ID.
• In the comments framework (see Chapter 13), each comment is associated with a particular site. When a comment is posted, its site is set to the current SITE_ID, and when comments are listed via the appropriate template tag, only the comments for the current site are displayed.
• In the flatpages framework (see “Flatpages” below), each flatpage is associated with a particular site. When a flatpage is created, you specify its site, and the flatpage middleware checks the current SITE_ID in retrieving flatpages to display.
• In the syndication framework (see “Syndication feeds” below), the templates for title and description automatically have access to a variable {{{ site }}}, which is the Site object representing the current site. Also, the hook for providing item URLs will use the domain from the current Site object if you don’t specify a fully-qualified domain.
• In the authentication framework (see Chapter 12), the django.contrib.auth.views.login view passes the current Site name to the template as {{{ site_name }}}.
• The shortcut view (see Chapter XX) uses the domain of the current Site object when calculating an object’s URL.

Using flatpages

To install the flatpages app, follow these steps:

1. Add 'django.contrib.flatpages' to your INSTALLED_APPS.
2. Add 'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware' to your MIDDLEWARE_CLASSES setting.
3. Run the command manage.py syncdb to install the two required tables into your database.

How it works

The flatpages app creates two tables in your database: django_flatpage and django_flatpage_sites. django_flatpage is a lookup table that simply maps a URL to a title and bunch of text content. django_flatpage_sites is a many-to-many table that associates a flatpage with one or more sites.

The app comes with a single FlatPage model, defined in django/contrib/flatpages/models.py. It looks like this:

from django.db import models
from django.contrib.sites.models import Site

class FlatPage(models.Model):
    url = models.CharField(maxlength=100)
    title = models.CharField(maxlength=200)
    content = models.TextField()
    enable_comments = models.BooleanField()
    template_name = models.CharField(maxlength=70, blank=True)
    registration_required = models.BooleanField()
    sites = models.ManyToManyField(Site)

Let’s cover these fields one at a time:

• url — The URL at which this flatpage lives, excluding the domain name but including the leading slash. Example: '/about/contact/.
• title — The title of the flatpage. The framework doesn’t do anything special with this. It’s your responsibility to display it in your template.
• content — The content of the flatpage, i.e., the HTML of the page. The framework doesn’t do anything special with this. It’s your responsibility to display it in the template.
• enable_comments — Whether to enable comments on this flatpage. The framework doesn’t do anything special with this. You can check this value in your template and display a comment form if needed.
• template_name — The name of the template to use for rendering this flatpage. This is optional. If it’s not given, the framework will use the template flatpages/default.html.
• registration_required — Whether registration is required for viewing this flatpage. This integrates with Django’s authentication/user framework, which was explained in Chapter 12.
• sites — The sites that this flatpage lives on. This integrates with Django’s sites framework, which was explained in the “Sites” section above.

You can create flatpages through either the Django admin interface or the Django database API. For more, see “How to add, change and delete flatpages” below.

Once you’ve created flatpages, the FlatpageFallbackMiddleware does all of the work. Each time any Django application raises a 404 error, this middleware checks the flatpages database for the requested URL as a last resort. Specifically, it checks for a flatpage with the given URL with a site ID that corresponds to the SITE_ID setting.

If it finds a match, it loads the flatpage’s template, or flatpages/default.html if the flatpage has not specified a custom template. It passes that template a single context variable, flatpage, which is the flatpage object. It uses RequestContext in rendering the template.

If it doesn’t find a match, the request continues to be processed as usual.

Note that this middleware only gets activated for 404s — not for 500s or responses of any other status code. Also note that the order of MIDDLEWARE_CLASSES matters. Generally, you can put FlatpageFallbackMiddleware at the end of the list, because it’s a last resort.

How to add, change and delete flatpages

>>> from django.contrib.flatpages.models import FlatPage
>>> from django.contrib.sites.models import Site
>>> fp = FlatPage(
...     url='/about/',
...     title='About',
...     content='<p>About this site...</p>',
...     enable_comments=False,
...     template_name='',
...     registration_required=False,
... )
>>> fp.save()
>>> fp.sites.add(Site.objects.get(id=1))
>>> FlatPage.objects.get(url='/about/')
<FlatPage: /about/ -- About>

Flatpage templates

By default, flatpages are rendered via the template flatpages/default.html, but you can override that for a particular flatpage.

Creating the flatpages/default.html template is your responsibility. In your template directory, just create a flatpages directory containing a file default.html.

Flatpage templates are passed a single context variable, flatpage, which is the flatpage object.

Here’s a sample flatpages/default.html template:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
    "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<title>{{ flatpage.title }}</title>
</head>
<body>
{{ flatpage.content }}
</body>
</html>

Using the redirects framework

To install the redirects app, follow these steps:

1. Add 'django.contrib.redirects' to your INSTALLED_APPS.
2. Add 'django.contrib.redirects.middleware.RedirectFallbackMiddleware' to your MIDDLEWARE_CLASSES setting.
3. Run the command manage.py syncdb to install the single required table into your database.

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.

You can create redirects through either the Django admin interface or the Django database API. For more, see “How to add, change and delete redirects” below.

Once you’ve created redirects, 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. (See “Sites” above for more on SITE_ID and the sites framework.) Then, it follows these steps:

• 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.

How to add, change and delete redirects

>>> from django.contrib.redirects.models import Redirect
>>> from django.contrib.sites.models import Site
>>> red = Redirect(
...     site=Site.objects.get(id=1),
...     old_path='/music/',
...     new_path='/sections/arts/music/',
... )
>>> red.save()
>>> Redirect.objects.get(old_path='/music/')
<Redirect: /music/ ---> /sections/arts/music/>

CSRF explained

CSRF, also known as “session riding,” is a Web-site security exploit. It happens when a malicious Web site tricks a user into unknowingly loading a URL from a site at which they’re already authenticated — hence, taking advantage of their authenticated status. This can be a bit tricky to understand at first, so we’ve included two examples here:

<input type="hidden" name="confirm" value="true" />

Using the CSRF middleware

The django.csrf package contains only one module: middleware.py. This module contains a Django middleware class, CsrfMiddleware, which implements the CSRF protection.

To use it, add 'django.contrib.csrf.middleware.CsrfMiddleware' to the MIDDLEWARE_CLASSES setting in your settings file. This middleware needs to process the response after SessionMiddleware, so CsrfMiddleware must appear before SessionMiddleware in the list. Also, it must process the response before the response gets compressed or otherwise mangled, so CsrfMiddleware must come after GZipMiddleware.

Once you’ve added that to your MIDDLEWARE_CLASSES setting, you’re done. That’s all you need to do.

How it works

In case you’re interested, here’s how CsrfMiddleware works. It does these two things:

1. It modifies outgoing requests by adding a hidden form field to all POST forms, with the name csrfmiddlewaretoken and a value that is a hash of the session ID plus a secret. The middleware does not modify the response if there’s no session ID set, so the performance penalty is negligible for requests that don’t use sessions.
2. On all incoming POST requests that have the session cookie set, it checks that the csrfmiddlewaretoken is present and correct. If it isn’t, the user will get a 403 HTTP error. The contents of the 403 error page are the message “Cross Site Request Forgery detected. Request aborted.”

This ensures that only forms originating from your Web site can be used to POST data back.

This middleware deliberately only targets HTTP POST requests (and the corresponding POST forms). As we explained above, GET requests ought never to have side effects; ensuring this is your own responsibility.

POST requests that are not accompanied by a session cookie are not protected, but they don’t need to be protected, because a malicious Web site could make these kind of requests anyway.

To avoid altering non-textual requests, the middleware checks the response’s Content-Type header before modifying it. Only pages that are served as text/html or application/xml+xhtml are modified.

Limitations

CsrfMiddleware requires Django’s session framework to work. (See Chapter 12 for more on sessions.) If you’ve using a custom session or authentication framework that manually manages session cookies, this middleware will not help you.

If your app creates HTML pages and forms in some unusual way — e.g., if it sends fragments of HTML in JavaScript document.write statements — you might bypass the filter that adds the hidden field to the form. In this case, the form submission would always fail. (This would happen because the CsrfMiddleware uses a regular expression to add the csrfmiddlewaretoken field to your HTML before the page is sent to the client, and the regular expression sometimes cannot handle wacky HTML.) If you suspect this might be happening, just view source in your Web browser to see whether the csrfmiddlewaretoken was inserted into your <form>.

For more CSRF information and examples, visit http://en.wikipedia.org/wiki/Csrf