Flatpages

Often you’ll have a database-driven Web application up and running, but you’ll need to add a couple of one-off static pages, such as an About page or a Privacy Policy page. It would be possible to use a standard Web server such as Apache to serve these files as flat HTML files, but that introduces an extra level of complexity into your application, because then you have to worry about configuring Apache, you have to set up access for your team to edit those files, and you can’t take advantage of Django’s template system to style the pages.

The solution to this problem is Django’s flatpages application, which lives in the package django.contrib.flatpages. This application lets you manage such one-off pages via Django’s admin site, and it lets you specify templates for them using Django’s template system. It uses Django models behind the scenes, which means it stores the pages in a database, just like the rest of your data, and you can access flatpages with the standard Django database API. Flatpages are keyed by their URL and site. When you create a flatpage, you specify which URL it’s associated with, along with which site(s) it’s on.

Using Flatpages – To install the flatpages application, follow these steps:

• Add ‘django.contrib.flatpages’ to your INSTALLED_APPS. django.contrib.flatpages depends on django.contrib.sites, so make sure the both packages are in INSTALLED_APPS.
• Add ‘django.contrib.flatpages.middleware.FlatpageFallbackMiddleware’ to your MIDDLEWARE_CLASSES setting.
• Run the command manage.py syncdb to install the two required tables into your database.

The flatpages application creates two tables in your database: django_flatpage and django_flatpage_sites. django_flatpage 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 application 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 examine these fields one at a time:

•  url: The URL at which this flatpage lives, excluding the domain name but including the leading slash (e.g., /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 or if this template doesn’t exist, the framework will fall back to the template flatpages/default.html.
• registration_required: Whether registration is required for viewing this flatpage. This integrates with Django’s authentication/user framework.
• sites: The sites that this flatpage lives on. This integrates with Django’s sites framework, which is explained in the “Sites” section of this chapter.

You can create flatpages through either the Django admin interface or the Django database API. Once you’ve created flatpages, 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 FlatpageFallbackMiddleware doesn’t find a match, the request continues to be processed as usual.

Note – This middleware only gets activated for 404 (page not found) errors — not for 500 (server error) or other error responses. Also note that the order of MIDDLEWARE_CLASSES matters. Generally, you can put FlatpageFallbackMiddleware at or near the end of the list, because it’s a last resort.

Adding, Changing, and Deleting Flatpages – You can add, change and delete flatpages in two ways:

Via the Admin Interface – If you’ve activated the automatic Django admin interface, you should see a “Flatpages” section on the admin index page. Edit flatpages as you would edit any other object in the system.

Via the Python API – As described previously, flatpages are represented by a standard Django model that lives in django/contrib/flatpages/models.py. Hence, you can access flatpage objects via the Django database API, for example:

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

Using Flatpage Templates – By default, flatpages are rendered via the template flatpages/default.html, but you can override that for a particular flatpage with the template_name field on the FlatPage object. Creating the flatpages/default.html template is your responsibility. In your template directory, just create a flatpages directory containing a default.html file. 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>

Back to Tutorial