← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal

« back to all changes in this revision

Viewing changes to docs/flatpages.txt

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant, Eddy Mulyono
  • Date: 2008-09-16 12:18:47 UTC
  • mfrom: (1.1.5 upstream) (4.1.1 lenny)
  • Revision ID: james.westby@ubuntu.com-20080916121847-mg225rg5mnsdqzr0
Tags: 1.0-1ubuntu1
https://launchpad.net/bugs/264191
* Merge from Debian (LP: #264191), remaining changes:
  - Run test suite on build.

[Eddy Mulyono]
* Update patch to workaround network test case failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
 
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>