/docs/ref/contrib/flatpages.txt

  1=================
  2The flatpages app
  3=================
  4
  5.. module:: django.contrib.flatpages
  6   :synopsis: A framework for managing simple ?flat? HTML content in a database.
  7
  8Django 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
 10Django's admin interface and a Python API.
 11
 12A flatpage is a simple object with a URL, title and content. Use it for
 13one-off, special-case pages, such as "About" or "Privacy Policy" pages, that
 14you want to store in a database but for which you don't want to develop a
 15custom Django application.
 16
 17A flatpage can use a custom template or a default, systemwide flatpage
 18template. It can be associated with one, or multiple, sites.
 19
 20The content field may optionally be left blank if you prefer to put your
 21content in a custom template.
 22
 23Here are some examples of flatpages on Django-powered sites:
 24
 25    * http://www.lawrence.com/about/contact/
 26    * http://www2.ljworld.com/site/rules/
 27
 28Installation
 29============
 30
 31To install the flatpages app, follow these steps:
 32
 33    1. Install the :mod:`sites framework <django.contrib.sites>` by adding
 34       ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting,
 35       if it's not already in there.
 36
 37       Also make sure you've correctly set :setting:`SITE_ID` to the ID of the
 38       site the settings file represents. This will usually be ``1`` (i.e.
 39       ``SITE_ID = 1``, but if you're using the sites framework to manage
 40       multiple sites, it could be the ID of a different site.
 41
 42    2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS`
 43       setting.
 44
 45    3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
 46       to your :setting:`MIDDLEWARE_CLASSES` setting.
 47
 48    4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
 49
 50.. currentmodule:: django.contrib.flatpages.middleware
 51
 52How it works
 53============
 54
 55``manage.py syncdb`` creates two tables in your database: ``django_flatpage``
 56and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table
 57that simply maps a URL to a title and bunch of text content.
 58``django_flatpage_sites`` associates a flatpage with a site.
 59
 60The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
 61does all of the work.
 62
 63.. class:: FlatpageFallbackMiddleware
 64
 65    Each time any Django application raises a 404 error, this middleware
 66    checks the flatpages database for the requested URL as a last resort.
 67    Specifically, it checks for a flatpage with the given URL with a site ID
 68    that corresponds to the :setting:`SITE_ID` setting.
 69
 70    If it finds a match, it follows this algorithm:
 71
 72        * If the flatpage has a custom template, it loads that template.
 73          Otherwise, it loads the template :file:`flatpages/default.html`.
 74
 75        * It passes that template a single context variable, ``flatpage``,
 76          which is the flatpage object. It uses
 77          :class:`~django.template.RequestContext` in rendering the
 78          template.
 79
 80    If it doesn't find a match, the request continues to be processed as usual.
 81
 82    The middleware only gets activated for 404s -- not for 500s or responses
 83    of any other status code.
 84
 85.. admonition:: Flatpages will not apply view middleware
 86
 87   Because the ``FlatpageFallbackMiddleware`` is applied only after
 88   URL resolution has failed and produced a 404, the response it
 89   returns will not apply any :ref:`view middleware <view-middleware>`
 90   methods. Only requests which are successfully routed to a view via
 91   normal URL resolution apply view middleware.
 92
 93Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can
 94put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at
 95the end of the list, because it's a last resort.
 96
 97For more on middleware, read the :doc:`middleware docs
 98</topics/http/middleware>`.
 99
100.. admonition:: Ensure that your 404 template works
101
102    Note that the
103    :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
104    only steps in once another view has successfully produced a 404 response.
105    If another view or middleware class attempts to produce a 404 but ends up
106    raising an exception instead (such as a ``TemplateDoesNotExist``
107    exception if your site does not have an appropriate template to
108    use for HTTP 404 responses), the response will become an HTTP 500
109    ("Internal Server Error") and the
110    :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
111    will not attempt to serve a flat page.
112
113.. currentmodule:: django.contrib.flatpages.models
114
115How to add, change and delete flatpages
116=======================================
117
118Via the admin interface
119-----------------------
120
121If you've activated the automatic Django admin interface, you should see a
122"Flatpages" section on the admin index page. Edit flatpages as you edit any
123other object in the system.
124
125Via the Python API
126------------------
127
128.. class:: FlatPage
129
130    Flatpages are represented by a standard
131    :doc:`Django model </topics/db/models>`,
132    which lives in `django/contrib/flatpages/models.py`_. You can access
133    flatpage objects via the :doc:`Django database API </topics/db/queries>`.
134
135.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
136
137.. currentmodule:: django.contrib.flatpages
138
139Flatpage templates
140==================
141
142By default, flatpages are rendered via the template
143:file:`flatpages/default.html`, but you can override that for a
144particular flatpage: in the admin, a collapsed fieldset titled
145"Advanced options" (clicking will expand it) contains a field for
146specifying a template name. If you're creating a flat page via the
147Python API you can simply set the template name as the field
148``template_name`` on the ``FlatPage`` object.
149
150Creating the :file:`flatpages/default.html` template is your responsibility;
151in your template directory, just create a :file:`flatpages` directory
152containing a file :file:`default.html`.
153
154Flatpage templates are passed a single context variable, ``flatpage``,
155which is the flatpage object.
156
157Here's a sample :file:`flatpages/default.html` template:
158
159.. code-block:: html+django
160
161    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
162        "http://www.w3.org/TR/REC-html40/loose.dtd">
163    <html>
164    <head>
165    <title>{{ flatpage.title }}</title>
166    </head>
167    <body>
168    {{ flatpage.content }}
169    </body>
170    </html>
171
172Since you're already entering raw HTML into the admin page for a flatpage,
173both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
174requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the
175template.
176
177Getting a list of :class:`~django.contrib.flatpages.models.FlatPage` objects in your templates
178==============================================================================================
179
180.. versionadded:: 1.3
181
182The flatpages app provides a template tag that allows you to iterate
183over all of the available flatpages on the :ref:`current site
184<hooking-into-current-site-from-views>`.
185
186Like all custom template tags, you'll need to :ref:`load its custom
187tag library <loading-custom-template-libraries>` before you can use
188it. After loading the library, you can retrieve all current flatpages
189via the :ttag:`get_flatpages` tag:
190
191.. code-block:: html+django
192
193    {% load flatpages %}
194    {% get_flatpages as flatpages %}
195    <ul>
196        {% for page in flatpages %}
197            <li><a href="{{ page.url }}">{{ page.title }}</a></li>
198        {% endfor %}
199    </ul>
200
201.. templatetag:: get_flatpages
202
203Displaying ``registration_required`` flatpages
204----------------------------------------------
205
206By default, the :ttag:`get_flatpages` templatetag will only show
207flatpages that are marked ``registration_required = False``. If you
208want to display registration-protected flatpages, you need to specify
209an authenticated user using a``for`` clause.
210
211For example:
212
213.. code-block:: html+django
214
215    {% get_flatpages for someuser as about_pages %}
216
217If you provide an anonymous user, :ttag:`get_flatpages` will behave
218the same as if you hadn't provided a user -- i.e., it will only show you
219public flatpages.
220
221Limiting flatpages by base URL
222------------------------------
223
224An optional argument, ``starts_with``, can be applied to limit the
225returned pages to those beginning with a particular base URL. This
226argument may be passed as a string, or as a variable to be resolved
227from the context.
228
229For example:
230
231.. code-block:: html+django
232
233    {% get_flatpages '/about/' as about_pages %}
234    {% get_flatpages about_prefix as about_pages %}
235    {% get_flatpages '/about/' for someuser as about_pages %}
236