1 files changed, 167 insertions, 0 deletions
diff --git a/parts/django/docs/ref/contrib/flatpages.txt b/parts/django/docs/ref/contrib/flatpages.txt
new file mode 100644
index 0000000..46b28dc
--- /dev/null
+++ b/parts/django/docs/ref/contrib/flatpages.txt
@@ -0,0 +1,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.