1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
=================
The flatpages app
=================
.. module:: django.contrib.flatpages
:synopsis: A framework for managing simple ?flat? HTML content in a database.
Django comes with an optional "flatpages" application. It lets you store simple
"flat" HTML content in a database and handles the management for you via
Django's admin interface and a Python API.
A flatpage is a simple object with a URL, title and content. Use it for
one-off, special-case pages, such as "About" or "Privacy Policy" pages, that
you want to store in a database but for which you don't want to develop a
custom Django application.
A flatpage can use a custom template or a default, systemwide flatpage
template. It can be associated with one, or multiple, sites.
.. versionadded:: 1.0
The content field may optionally be left blank if you prefer to put your
content in a custom template.
Here are some examples of flatpages on Django-powered sites:
* http://www.lawrence.com/about/contact/
* http://www2.ljworld.com/site/rules/
Installation
============
To install the flatpages app, follow these steps:
1. Install the :mod:`sites framework <django.contrib.sites>` by adding
``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting,
if it's not already in there.
Also make sure you've correctly set :setting:`SITE_ID` to the ID of the
site the settings file represents. This will usually be ``1`` (i.e.
``SITE_ID = 1``, but if you're using the sites framework to manage
multiple sites, it could be the ID of a different site.
2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS`
setting.
3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
to your :setting:`MIDDLEWARE_CLASSES` setting.
4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
How it works
============
``manage.py syncdb`` creates two tables in your database: ``django_flatpage``
and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table
that simply maps a URL to a title and bunch of text content.
``django_flatpage_sites`` associates a flatpage with a site.
The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
does all of the work. Each time any Django application raises a 404 error, this
middleware checks the flatpages database for the requested URL as a last resort.
Specifically, it checks for a flatpage with the given URL with a site ID that
corresponds to the :setting:`SITE_ID` setting.
If it finds a match, it follows this algorithm:
* If the flatpage has a custom template, it loads that template. Otherwise,
it loads the template :file:`flatpages/default.html`.
* It passes that template a single context variable, :data:`flatpage`, which
is the flatpage object. It uses
:class:`~django.template.context.RequestContext` in rendering the
template.
If it doesn't find a match, the request continues to be processed as usual.
The middleware only gets activated for 404s -- not for 500s or responses of any
other status code.
.. admonition:: Flatpages will not apply view middleware
Because the ``FlatpageFallbackMiddleware`` is applied only after
URL resolution has failed and produced a 404, the response it
returns will not apply any :ref:`view middleware <view-middleware>`
methods. Only requests which are successfully routed to a view via
normal URL resolution apply view middleware.
Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can
put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at
the end of the list, because it's a last resort.
For more on middleware, read the :doc:`middleware docs
</topics/http/middleware>`.
.. admonition:: Ensure that your 404 template works
Note that the
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
only steps in once another view has successfully produced a 404 response.
If another view or middleware class attempts to produce a 404 but ends up
raising an exception instead (such as a ``TemplateDoesNotExist``
exception if your site does not have an appropriate template to
use for HTTP 404 responses), the response will become an HTTP 500
("Internal Server Error") and the
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
will not attempt to serve a flat page.
How to add, change and delete flatpages
=======================================
Via the admin interface
-----------------------
If you've activated the automatic Django admin interface, you should see a
"Flatpages" section on the admin index page. Edit flatpages as you edit any
other object in the system.
Via the Python API
------------------
.. class:: models.FlatPage
Flatpages are represented by a standard
:doc:`Django model </topics/db/models>`,
which lives in `django/contrib/flatpages/models.py`_. You can access
flatpage objects via the :doc:`Django database API </topics/db/queries>`.
.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
Flatpage templates
==================
By default, flatpages are rendered via the template
:file:`flatpages/default.html`, but you can override that for a
particular flatpage: in the admin, a collapsed fieldset titled
"Advanced options" (clicking will expand it) contains a field for
specifying a template name. If you're creating a flat page via the
Python API you can simply set the template name as the field
``template_name`` on the ``FlatPage`` object.
Creating the :file:`flatpages/default.html` template is your responsibility;
in your template directory, just create a :file:`flatpages` directory
containing a file :file:`default.html`.
Flatpage templates are passed a single context variable, :data:`flatpage`,
which is the flatpage object.
Here's a sample :file:`flatpages/default.html` template:
.. code-block:: html+django
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<title>{{ flatpage.title }}</title>
</head>
<body>
{{ flatpage.content }}
</body>
</html>
Since you're already entering raw HTML into the admin page for a flatpage,
both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the
template.
|
