2008-08-24 06:25:40 +08:00
|
|
|
.. _ref-contrib-flatpages:
|
|
|
|
|
2005-11-11 12:45:05 +08:00
|
|
|
=================
|
|
|
|
The flatpages app
|
|
|
|
=================
|
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
.. module:: django.contrib.flatpages
|
|
|
|
:synopsis: A framework for managing simple ?flat? HTML content in a database.
|
|
|
|
|
2005-11-11 12:45:05 +08:00
|
|
|
Django comes with an optional "flatpages" application. It lets you store simple
|
2006-05-02 09:31:56 +08:00
|
|
|
"flat" HTML content in a database and handles the management for you via
|
|
|
|
Django's admin interface and a Python API.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2008-09-02 11:40:42 +08:00
|
|
|
.. versionadded:: 1.0
|
2008-06-30 21:05:47 +08:00
|
|
|
|
|
|
|
The content field may optionally be left blank if you prefer to put your
|
|
|
|
content in a custom template.
|
|
|
|
|
2005-11-11 12:45:05 +08:00
|
|
|
Here are some examples of flatpages on Django-powered sites:
|
|
|
|
|
|
|
|
* http://www.lawrence.com/about/contact/
|
2010-01-11 01:58:41 +08:00
|
|
|
* http://www2.ljworld.com/site/rules/
|
2005-11-11 12:45:05 +08:00
|
|
|
|
|
|
|
Installation
|
|
|
|
============
|
|
|
|
|
2006-03-16 10:57:30 +08:00
|
|
|
To install the flatpages app, follow these steps:
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
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.
|
|
|
|
|
Fixed a whole bunch of small docs typos, errors, and ommissions.
Fixes #8358, #8396, #8724, #9043, #9128, #9247, #9267, #9267, #9375, #9409, #9414, #9416, #9446, #9454, #9464, #9503, #9518, #9533, #9657, #9658, #9683, #9733, #9771, #9835, #9836, #9837, #9897, #9906, #9912, #9945, #9986, #9992, #10055, #10084, #10091, #10145, #10245, #10257, #10309, #10358, #10359, #10424, #10426, #10508, #10531, #10551, #10635, #10637, #10656, #10658, #10690, #10699, #19528.
Thanks to all the respective authors of those tickets.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@10371 bcc190cf-cafb-0310-a4f2-bffc1f526a37
2009-04-04 02:30:54 +08:00
|
|
|
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.
|
2010-01-11 00:45:31 +08:00
|
|
|
``SITE_ID = 1``, but if you're using the sites framework to manage
|
Fixed a whole bunch of small docs typos, errors, and ommissions.
Fixes #8358, #8396, #8724, #9043, #9128, #9247, #9267, #9267, #9375, #9409, #9414, #9416, #9446, #9454, #9464, #9503, #9518, #9533, #9657, #9658, #9683, #9733, #9771, #9835, #9836, #9837, #9897, #9906, #9912, #9945, #9986, #9992, #10055, #10084, #10091, #10145, #10245, #10257, #10309, #10358, #10359, #10424, #10426, #10508, #10531, #10551, #10635, #10637, #10656, #10658, #10690, #10699, #19528.
Thanks to all the respective authors of those tickets.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@10371 bcc190cf-cafb-0310-a4f2-bffc1f526a37
2009-04-04 02:30:54 +08:00
|
|
|
multiple sites, it could be the ID of a different site.
|
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS`
|
|
|
|
setting.
|
|
|
|
|
2008-03-10 05:59:09 +08:00
|
|
|
3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
|
2008-08-24 06:25:40 +08:00
|
|
|
to your :setting:`MIDDLEWARE_CLASSES` setting.
|
|
|
|
|
|
|
|
4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
|
|
|
|
|
2005-11-11 12:45:05 +08:00
|
|
|
How it works
|
|
|
|
============
|
|
|
|
|
2006-05-02 09:31:56 +08:00
|
|
|
``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.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
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.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
|
|
|
If it finds a match, it follows this algorithm:
|
|
|
|
|
|
|
|
* If the flatpage has a custom template, it loads that template. Otherwise,
|
2008-08-24 06:25:40 +08:00
|
|
|
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.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
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.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
For more on middleware, read the :ref:`middleware docs
|
|
|
|
<topics-http-middleware>`.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2008-05-29 04:31:03 +08:00
|
|
|
.. admonition:: Ensure that your 404 template works
|
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
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
|
2008-05-29 04:31:03 +08:00
|
|
|
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
|
2008-08-24 06:25:40 +08:00
|
|
|
("Internal Server Error") and the
|
|
|
|
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
|
2008-05-29 04:31:03 +08:00
|
|
|
will not attempt to serve a flat page.
|
|
|
|
|
2005-11-11 12:45:05 +08:00
|
|
|
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
|
|
|
|
------------------
|
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
.. class:: models.FlatPage
|
|
|
|
|
|
|
|
Flatpages are represented by a standard
|
|
|
|
:ref:`Django model <topics-db-models>`,
|
|
|
|
which lives in `django/contrib/flatpages/models.py`_. You can access
|
|
|
|
flatpage objects via the :ref:`Django database API <topics-db-queries>`.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2006-05-02 10:01:19 +08:00
|
|
|
.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
|
2005-11-11 12:45:05 +08:00
|
|
|
|
|
|
|
Flatpage templates
|
|
|
|
==================
|
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
By default, flatpages are rendered via the template
|
|
|
|
:file:`flatpages/default.html`, but you can override that for a particular
|
|
|
|
flatpage.
|
|
|
|
|
|
|
|
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`.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
Flatpage templates are passed a single context variable, :data:`flatpage`,
|
|
|
|
which is the flatpage object.
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
Here's a sample :file:`flatpages/default.html` template:
|
2005-11-11 12:45:05 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
.. code-block:: html+django
|
2005-11-11 12:45:05 +08:00
|
|
|
|
|
|
|
<!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>
|
2007-11-15 05:30:18 +08:00
|
|
|
|
|
|
|
Since you're already entering raw HTML into the admin page for a flatpage,
|
|
|
|
both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
|
2008-08-24 06:25:40 +08:00
|
|
|
requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the
|
|
|
|
template.
|