+
−=================
+
−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.
+
−
+
−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 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 ``manage.py syncdb``.
+
−
+
−.. _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``.
+
−    * 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`_.
+
−
+
−.. _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>