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 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 **New in Django development version**
  18
  19 The content field may optionally be left blank if you prefer to put your
  20 content in a custom template.
  21
  22 Here are some examples of flatpages on Django-powered sites:
  23
  24     * http://www.everyblock.com/about/
  25     * http://www.lawrence.com/about/contact/
  26
  27 Installation
  28 ============
  29
  30 To install the flatpages app, follow these steps:
  31
  32     1. Install the `sites framework`_ by adding ``'django.contrib.sites'`` to
  33        your INSTALLED_APPS_ setting, if it's not already in there.
  34     2. Add ``'django.contrib.flatpages'`` to your INSTALLED_APPS_ setting.
  35     3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
  36        to your MIDDLEWARE_CLASSES_ setting.
  37     4. Run the command ``manage.py syncdb``.
  38
  39 .. _sites framework: ../sites/
  40 .. _INSTALLED_APPS: ../settings/#installed-apps
  41 .. _MIDDLEWARE_CLASSES: ../settings/#middleware-classes
  42
  43 How it works
  44 ============
  45
  46 ``manage.py syncdb`` creates two tables in your database: ``django_flatpage``
  47 and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table
  48 that simply maps a URL to a title and bunch of text content.
  49 ``django_flatpage_sites`` associates a flatpage with a site.
  50
  51 The ``FlatpageFallbackMiddleware`` does all of the work. Each time any Django
  52 application raises a 404 error, this middleware checks the flatpages database
  53 for the requested URL as a last resort. Specifically, it checks for a flatpage
  54 with the given URL with a site ID that corresponds to the SITE_ID_ setting.
  55
  56 If it finds a match, it follows this algorithm:
  57
  58     * If the flatpage has a custom template, it loads that template. Otherwise,
  59       it loads the template ``flatpages/default.html``.
  60     * It passes that template a single context variable, ``flatpage``, which is
  61       the flatpage object. It uses RequestContext_ in rendering the template.
  62
  63 If it doesn't find a match, the request continues to be processed as usual.
  64
  65 The middleware only gets activated for 404s -- not for 500s or responses of any
  66 other status code.
  67
  68 Note that the order of ``MIDDLEWARE_CLASSES`` matters. Generally, you can put
  69 ``FlatpageFallbackMiddleware`` at the end of the list, because it's a last
  70 resort.
  71
  72 For more on middleware, read the `middleware docs`_.
  73
  74 .. admonition:: Ensure that your 404 template works
  75
  76     Note that the ``FlatpageFallbackMiddleware`` only steps in once
  77     another view has successfully produced a 404 response. If another
  78     view or middleware class attempts to produce a 404 but ends up
  79     raising an exception instead (such as a ``TemplateDoesNotExist``
  80     exception if your site does not have an appropriate template to
  81     use for HTTP 404 responses), the response will become an HTTP 500
  82     ("Internal Server Error") and the ``FlatpageFallbackMiddleware``
  83     will not attempt to serve a flat page.
  84
  85 .. _SITE_ID: ../settings/#site-id
  86 .. _RequestContext: ../templates_python/#subclassing-context-djangocontext
  87 .. _middleware docs: ../middleware/
  88
  89 How to add, change and delete flatpages
  90 =======================================
  91
  92 Via the admin interface
  93 -----------------------
  94
  95 If you've activated the automatic Django admin interface, you should see a
  96 "Flatpages" section on the admin index page. Edit flatpages as you edit any
  97 other object in the system.
  98
  99 Via the Python API
 100 ------------------
 101
 102 Flatpages are represented by a standard `Django model`_, which lives in
 103 `django/contrib/flatpages/models.py`_. You can access flatpage objects via the
 104 `Django database API`_.
 105
 106 .. _Django model: ../model-api/
 107 .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
 108 .. _Django database API: ../db-api/
 109
 110 Flatpage templates
 111 ==================
 112
 113 By default, flatpages are rendered via the template ``flatpages/default.html``,
 114 but you can override that for a particular flatpage.
 115
 116 Creating the ``flatpages/default.html`` template is your responsibility; in
 117 your template directory, just create a ``flatpages`` directory containing a
 118 file ``default.html``.
 119
 120 Flatpage templates are passed a single context variable, ``flatpage``, which is
 121 the flatpage object.
 122
 123 Here's a sample ``flatpages/default.html`` template::
 124
 125     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
 126         "http://www.w3.org/TR/REC-html40/loose.dtd">
 127     <html>
 128     <head>
 129     <title>{{ flatpage.title }}</title>
 130     </head>
 131     <body>
 132     {{ flatpage.content }}
 133     </body>
 134     </html>
 135
 136 Since you're already entering raw HTML into the admin page for a flatpage,
 137 both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
 138 requiring `automatic HTML escaping`_  in the template.
 139
 140 .. _automatic HTML escaping: ../templates/#automatic-html-escaping
 141