root/django/branches/gis/docs/flatpages.txt

=================
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 via
Django's admin interface and a Python API.

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.

**New in Django development version**

The content field may optionally be left blank if you prefer to put your 
content in a custom template.

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

    * http://www.everyblock.com/about/
    * http://www.lawrence.com/about/contact/

Installation
============

To install the flatpages app, follow these steps:

    1. Install the `sites framework`_ by adding ``'django.contrib.sites'`` to
       your INSTALLED_APPS_ setting, if it's not already in there.
    2. Add ``'django.contrib.flatpages'`` to your INSTALLED_APPS_ setting.
    3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
       to your MIDDLEWARE_CLASSES_ setting.
    4. Run the command ``manage.py syncdb``.

.. _sites framework: ../sites/
.. _INSTALLED_APPS: ../settings/#installed-apps
.. _MIDDLEWARE_CLASSES: ../settings/#middleware-classes

How it works
============

``manage.py syncdb`` creates two tables in your database: ``django_flatpage``
and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table
that simply maps a URL to a title and bunch of text content.
``django_flatpage_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.html``.
    * 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.

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`_.

.. admonition:: Ensure that your 404 template works
    
    Note that the ``FlatpageFallbackMiddleware`` only steps in once
    another view has successfully produced a 404 response. If another
    view or middleware class attempts to produce a 404 but ends up
    raising an exception instead (such as a ``TemplateDoesNotExist``
    exception if your site does not have an appropriate template to
    use for HTTP 404 responses), the response will become an HTTP 500
    ("Internal Server Error") and the ``FlatpageFallbackMiddleware``
    will not attempt to serve a flat page.

.. _SITE_ID: ../settings/#site-id
.. _RequestContext: ../templates_python/#subclassing-context-djangocontext
.. _middleware docs: ../middleware/

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.py`_. You can access flatpage objects via the
`Django database API`_.

.. _Django model: ../model-api/
.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
.. _Django database API: ../db-api/

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>

Since you're already entering raw HTML into the admin page for a flatpage,
both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
requiring `automatic HTML escaping`_  in the template.

.. _automatic HTML escaping: ../templates/#automatic-html-escaping