| 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> |
|---|
