#

## Django documentation

# The flatpages app

Django comes with an optional "flatpages" application. It lets you store simple "flat" HTML content in a database and handles the management for you.

A flatpage is a simple object with a URL, title and content. Use it for one-off, special-case pages, such as "About" or "Privacy Policy" pages, that you want to store in a database but for which you don't want to develop a custom Django application.

A flatpage can use a custom template or a default, systemwide flatpage template. It can be associated with one, or multiple, sites.

Here are some examples of flatpages on Django-powered sites:

> - http://www.chicagocrime.org/about/
> - http://www.lawrence.com/about/contact/

## Installation

To install the flatpages app, follow these two steps:

> 1. Add `"django.contrib.flatpages"` to your INSTALLED_APPS setting.
> 2. Add `"django.contrib.flatpages.middleware.FlatpageFallbackMiddleware"` to your MIDDLEWARE_CLASSES setting.
> 3. Run the command `django-admin.py install flatpages`.

## How it works

`django-admin.py install flatpages` creates two tables in your database: `django_flatpages` and `django_flatpages_sites`. `django_flatpages` is a simple lookup table that essentially maps a URL to a title and bunch of text content. `django_flatpages_sites` associates a flatpage with a site.

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 follows this algorithm:

> - If the flatpage has a custom template, it loads that template. Otherwise, it loads the template `flatpages/default`.
> - It passes that template a single context variable, `flatpage`, which is the flatpage object. It uses DjangoContext in rendering the template.

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 `FlatpageFallbackMiddleware` 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 flatpages

### 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 edit any other object in the system.

### Via the Python API

Flatpages are represented by a standard Django model, which lives in django/contrib/flatpages/models/flatpages.py. You can access flatpage objects via the Django database API.

## Flatpage templates

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

Creating the `flatpages/default` 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` 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>

## Comments

### Simon Willison November 11, 2005 at 12:28 a.m.

One useful thing you can do with flatpages is use a markup processing filter of some sort in your template, for example:

{% load markup %}
{{ flatpage.content|textile }}

You can now use textile formatting on your flatpage (or markdown or ReStructuredText).

### pbx November 11, 2005 at 8:40 a.m.

That's cool. You could even make it conditional -- a "process with Markdown" boolean field for example -- so that you could still use HTML in cases where you really needed to, but use your favored markup everywhere else.

### Lukas November 12, 2005 at 2:21 p.m.

Does this really render a complete 404-page and throws it away when finding that there is a flatpage for that particular url? Looks like a bit of overhead to me, although I have no idea what that really costs.

--
Lukas

### Simon Willison November 12, 2005 at 2:27 p.m.

Lukas: Not at all. The decision to serve a flat page is made before the 404 handler (and subsequent page rendering). The only overhead is an additional check for a possible flat page every time your site has a 404 error - and on well designed sites that shouldn't happen wery often at all anyway.

### Steve November 21, 2005 at 2:36 p.m.

How exactly does the "Enable comments" option work? I didn't see any added functionality just by enabling it, and can't find any documentation on it. Am I missing something obvious?

## Post a comment

Note: Please only use the comments for questions/critcisms/suggestions on the docs; if you experience errors please file a ticket, ask in the IRC channel, or post to the django-users list. Comments will be periodically reviewed, integrated into the documentation proper, and removed.

Your name:

Comment: