1 =================

     2 The flatpages app

     3 =================

     4 

     5 Django comes with an optional "flatpages" application. It lets you store simple

     6 "flat" HTML content in a database and handles the management for you via

     7 Django's admin interface and a Python API.

     8 

     9 A flatpage is a simple object with a URL, title and content. Use it for

    10 one-off, special-case pages, such as "About" or "Privacy Policy" pages, that

    11 you want to store in a database but for which you don't want to develop a

    12 custom Django application.

    13 

    14 A flatpage can use a custom template or a default, systemwide flatpage

    15 template. It can be associated with one, or multiple, sites.

    16 

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

    18 

    19     * http://www.chicagocrime.org/about/

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

    21 

    22 Installation

    23 ============

    24 

    25 To install the flatpages app, follow these steps:

    26 

    27     1. Add ``'django.contrib.flatpages'`` to your INSTALLED_APPS_ setting.

    28     2. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``

    29        to your MIDDLEWARE_CLASSES_ setting.

    30     3. Run the command ``manage.py syncdb``.

    31 

    32 .. _INSTALLED_APPS: ../settings/#installed-apps

    33 .. _MIDDLEWARE_CLASSES: ../settings/#middleware-classes

    34 

    35 How it works

    36 ============

    37 

    38 ``manage.py syncdb`` creates two tables in your database: ``django_flatpage``

    39 and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table

    40 that simply maps a URL to a title and bunch of text content.

    41 ``django_flatpage_sites`` associates a flatpage with a site.

    42 

    43 The ``FlatpageFallbackMiddleware`` does all of the work. Each time any Django

    44 application raises a 404 error, this middleware checks the flatpages database

    45 for the requested URL as a last resort. Specifically, it checks for a flatpage

    46 with the given URL with a site ID that corresponds to the SITE_ID_ setting.

    47 

    48 If it finds a match, it follows this algorithm:

    49 

    50     * If the flatpage has a custom template, it loads that template. Otherwise,

    51       it loads the template ``flatpages/default``.

    52     * It passes that template a single context variable, ``flatpage``, which is

    53       the flatpage object. It uses RequestContext_ in rendering the template.

    54 

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

    56 

    57 The middleware only gets activated for 404s -- not for 500s or responses of any

    58 other status code.

    59 

    60 Note that the order of ``MIDDLEWARE_CLASSES`` matters. Generally, you can put

    61 ``FlatpageFallbackMiddleware`` at the end of the list, because it's a last

    62 resort.

    63 

    64 For more on middleware, read the `middleware docs`_.

    65 

    66 .. _SITE_ID: ../settings/#site-id

    67 .. _RequestContext: ../templates_python/#subclassing-context-djangocontext

    68 .. _middleware docs: ../middleware/

    69 

    70 How to add, change and delete flatpages

    71 =======================================

    72 

    73 Via the admin interface

    74 -----------------------

    75 

    76 If you've activated the automatic Django admin interface, you should see a

    77 "Flatpages" section on the admin index page. Edit flatpages as you edit any

    78 other object in the system.

    79 

    80 Via the Python API

    81 ------------------

    82 

    83 Flatpages are represented by a standard `Django model`_, which lives in

    84 `django/contrib/flatpages/models.py`_. You can access flatpage objects via the

    85 `Django database API`_.

    86 

    87 .. _Django model: ../model_api/

    88 .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py

    89 .. _Django database API: ../db_api/

    90 

    91 Flatpage templates

    92 ==================

    93 

    94 By default, flatpages are rendered via the template ``flatpages/default.html``,

    95 but you can override that for a particular flatpage.

    96 

    97 Creating the ``flatpages/default.html`` template is your responsibility; in

    98 your template directory, just create a ``flatpages`` directory containing a

    99 file ``default.html``.

   100 

   101 Flatpage templates are passed a single context variable, ``flatpage``, which is

   102 the flatpage object.

   103 

   104 Here's a sample ``flatpages/default.html`` template::

   105 

   106     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

   107         "http://www.w3.org/TR/REC-html40/loose.dtd">

   108     <html>

   109     <head>

   110     <title>{{ flatpage.title }}</title>

   111     </head>

   112     <body>

   113     {{ flatpage.content }}

   114     </body>

   115     </html>