docs/flatpages.txt

   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.
   7
   8 A flatpage is a simple object with a URL, title and content. Use it for
   9 one-off, special-case pages, such as "About" or "Privacy Policy" pages, that
  10 you want to store in a database but for which you don't want to develop a
  11 custom Django application.
  12
  13 A flatpage can use a custom template or a default, systemwide flatpage
  14 template. It can be associated with one, or multiple, sites.
  15
  16 Here are some examples of flatpages on Django-powered sites:
  17
  18     * http://www.chicagocrime.org/about/
  19     * http://www.lawrence.com/about/contact/
  20
  21 Installation
  22 ============
  23
  24 To install the flatpages app, follow these two steps:
  25
  26     1. Add ``"django.contrib.flatpages"`` to your INSTALLED_APPS_ setting.
  27     2. Add ``"django.contrib.flatpages.middleware.FlatpageFallbackMiddleware"``
  28        to your MIDDLEWARE_CLASSES_ setting.
  29     3. Run the command ``django-admin.py install flatpages``.
  30
  31 .. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps
  32 .. _MIDDLEWARE_CLASSES: http://www.djangoproject.com/documentation/settings/#middleware-classes
  33
  34 How it works
  35 ============
  36
  37 ``django-admin.py install flatpages`` creates two tables in your database:
  38 ``django_flatpages`` and ``django_flatpages_sites``. ``django_flatpages`` is a
  39 simple lookup table that essentially maps a URL to a title and bunch of text
  40 content. ``django_flatpages_sites`` associates a flatpage with a site.
  41
  42 The ``FlatpageFallbackMiddleware`` does all of the work. Each time any Django
  43 application raises a 404 error, this middleware checks the flatpages database
  44 for the requested URL as a last resort. Specifically, it checks for a flatpage
  45 with the given URL with a site ID that corresponds to the SITE_ID_ setting.
  46
  47 If it finds a match, it follows this algorithm:
  48
  49     * If the flatpage has a custom template, it loads that template. Otherwise,
  50       it loads the template ``flatpages/default``.
  51     * It passes that template a single context variable, ``flatpage``, which is
  52       the flatpage object. It uses DjangoContext_ in rendering the template.
  53
  54 If it doesn't find a match, the request continues to be processed as usual.
  55
  56 The middleware only gets activated for 404s -- not for 500s or responses of any
  57 other status code.
  58
  59 Note that the order of ``MIDDLEWARE_CLASSES`` matters. Generally, you can put
  60 ``FlatpageFallbackMiddleware`` at the end of the list, because it's a last
  61 resort.
  62
  63 For more on middleware, read the `middleware docs`_.
  64
  65 .. _SITE_ID: http://www.djangoproject.com/documentation/settings/#site-id
  66 .. _DjangoContext: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext
  67 .. _middleware docs: http://www.djangoproject.com/documentation/middleware/
  68
  69 How to add, change and delete flatpages
  70 =======================================
  71
  72 Via the admin interface
  73 -----------------------
  74
  75 If you've activated the automatic Django admin interface, you should see a
  76 "Flatpages" section on the admin index page. Edit flatpages as you edit any
  77 other object in the system.
  78
  79 Via the Python API
  80 ------------------
  81
  82 Flatpages are represented by a standard `Django model`_, which lives in
  83 `django/contrib/flatpages/models/flatpages.py`_. You can access flatpage
  84 objects via the `Django database API`_.
  85
  86 .. _Django model: http://www.djangoproject.com/documentation/model_api/
  87 .. _django/contrib/flatpages/models/flatpages.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models/flatpages.py
  88 .. _Django database API: http://www.djangoproject.com/documentation/db_api/
  89
  90 Flatpage templates
  91 ==================
  92
  93 By default, flatpages are rendered via the template ``flatpages/default``, but
  94 you can override that for a particular flatpage.
  95
  96 Creating the ``flatpages/default`` template is your responsibility; in your
  97 template directory, just create a ``flatpages`` directory containing a file
  98 ``default.html``.
  99
 100 Flatpage templates are passed a single context variable, ``flatpage``, which is
 101 the flatpage object.
 102
 103 Here's a sample ``flatpages/default`` template::
 104
 105     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
 106         "http://www.w3.org/TR/REC-html40/loose.dtd">
 107     <html>
 108     <head>
 109     <title>{{ flatpage.title }}</title>
 110     </head>
 111     <body>
 112     {{ flatpage.content }}
 113     </body>
 114     </html>