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

     2 The flatpages app

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

     4 

     5 .. module:: django.contrib.flatpages

     6    :synopsis: A framework for managing simple ?flat? HTML content in a database.

     7 

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

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

    10 Django's admin interface and a Python API.

    11 

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

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

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

    15 custom Django application.

    16 

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

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

    19 

    20 .. versionadded:: 1.0

    21 

    22 The content field may optionally be left blank if you prefer to put your 

    23 content in a custom template.

    24 

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

    26 

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

    28     * http://www2.ljworld.com/site/rules/

    29 

    30 Installation

    31 ============

    32 

    33 To install the flatpages app, follow these steps:

    34 

    35     1. Install the :mod:`sites framework <django.contrib.sites>` by adding

    36        ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting,

    37        if it's not already in there.

    38        

    39        Also make sure you've correctly set :setting:`SITE_ID` to the ID of the

    40        site the settings file represents. This will usually be ``1`` (i.e.

    41        ``SITE_ID = 1``, but if you're using the sites framework to manage

    42        multiple sites, it could be the ID of a different site.

    43        

    44     2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS`

    45        setting.

    46        

    47     3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``

    48        to your :setting:`MIDDLEWARE_CLASSES` setting.

    49        

    50     4. Run the command :djadmin:`manage.py syncdb <syncdb>`.

    51  

    52 How it works

    53 ============

    54 

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

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

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

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

    59 

    60 The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`

    61 does all of the work. Each time any Django application raises a 404 error, this

    62 middleware checks the flatpages database for the requested URL as a last resort.

    63 Specifically, it checks for a flatpage with the given URL with a site ID that

    64 corresponds to the :setting:`SITE_ID` setting.

    65 

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

    67 

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

    69       it loads the template :file:`flatpages/default.html`.

    70     

    71     * It passes that template a single context variable, :data:`flatpage`, which

    72       is the flatpage object. It uses

    73       :class:`~django.template.context.RequestContext` in rendering the

    74       template.

    75 

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

    77 

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

    79 other status code.

    80 

    81 .. admonition:: Flatpages will not apply view middleware

    82 

    83    Because the ``FlatpageFallbackMiddleware`` is applied only after

    84    URL resolution has failed and produced a 404, the response it

    85    returns will not apply any :ref:`view middleware <view-middleware>`

    86    methods. Only requests which are successfully routed to a view via

    87    normal URL resolution apply view middleware.

    88 

    89 Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can

    90 put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at

    91 the end of the list, because it's a last resort.

    92 

    93 For more on middleware, read the :doc:`middleware docs

    94 </topics/http/middleware>`.

    95 

    96 .. admonition:: Ensure that your 404 template works

    97     

    98     Note that the

    99     :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`

   100     only steps in once another view has successfully produced a 404 response.

   101     If another view or middleware class attempts to produce a 404 but ends up

   102     raising an exception instead (such as a ``TemplateDoesNotExist``

   103     exception if your site does not have an appropriate template to

   104     use for HTTP 404 responses), the response will become an HTTP 500

   105     ("Internal Server Error") and the

   106     :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`

   107     will not attempt to serve a flat page.

   108 

   109 How to add, change and delete flatpages

   110 =======================================

   111 

   112 Via the admin interface

   113 -----------------------

   114 

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

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

   117 other object in the system.

   118 

   119 Via the Python API

   120 ------------------

   121 

   122 .. class:: models.FlatPage

   123 

   124     Flatpages are represented by a standard

   125     :doc:`Django model </topics/db/models>`,

   126     which lives in `django/contrib/flatpages/models.py`_. You can access

   127     flatpage objects via the :doc:`Django database API </topics/db/queries>`.

   128 

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

   130 

   131 Flatpage templates

   132 ==================

   133 

   134 By default, flatpages are rendered via the template

   135 :file:`flatpages/default.html`, but you can override that for a

   136 particular flatpage: in the admin, a collapsed fieldset titled

   137 "Advanced options" (clicking will expand it) contains a field for

   138 specifying a template name. If you're creating a flat page via the

   139 Python API you can simply set the template name as the field

   140 ``template_name`` on the ``FlatPage`` object.

   141 

   142 Creating the :file:`flatpages/default.html` template is your responsibility;

   143 in your template directory, just create a :file:`flatpages` directory

   144 containing a file :file:`default.html`.

   145 

   146 Flatpage templates are passed a single context variable, :data:`flatpage`,

   147 which is the flatpage object.

   148 

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

   150 

   151 .. code-block:: html+django

   152 

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

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

   155     <html>

   156     <head>

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

   158     </head>

   159     <body>

   160     {{ flatpage.content }}

   161     </body>

   162     </html>

   163 

   164 Since you're already entering raw HTML into the admin page for a flatpage,

   165 both ``flatpage.title`` and ``flatpage.content`` are marked as **not**

   166 requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the

   167 template.