================= 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. 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 ` 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 `. .. currentmodule:: django.contrib.flatpages.middleware 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. .. class:: FlatpageFallbackMiddleware 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, ``flatpage``, which is the flatpage object. It uses :class:`~django.template.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 ` 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 `. .. 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. .. currentmodule:: django.contrib.flatpages.models 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:: FlatPage Flatpages are represented by a standard :doc:`Django model `, which lives in `django/contrib/flatpages/models.py`_. You can access flatpage objects via the :doc:`Django database API `. .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py .. currentmodule:: django.contrib.flatpages 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, ``flatpage``, which is the flatpage object. Here's a sample :file:`flatpages/default.html` template: .. code-block:: html+django {{ flatpage.title }} {{ flatpage.content }} 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 ` in the template. Getting a list of :class:`~django.contrib.flatpages.models.FlatPage` objects in your templates ============================================================================================== .. versionadded:: 1.3 The flatpages app provides a template tag that allows you to iterate over all of the available flatpages on the :ref:`current site `. Like all custom template tags, you'll need to :ref:`load its custom tag library ` before you can use it. After loading the library, you can retrieve all current flatpages via the :ttag:`get_flatpages` tag: .. code-block:: html+django {% load flatpages %} {% get_flatpages as flatpages %} .. templatetag:: get_flatpages Displaying ``registration_required`` flatpages ---------------------------------------------- By default, the :ttag:`get_flatpages` templatetag will only show flatpages that are marked ``registration_required = False``. If you want to display registration-protected flatpages, you need to specify an authenticated user using a``for`` clause. For example: .. code-block:: html+django {% get_flatpages for someuser as about_pages %} If you provide an anonymous user, :ttag:`get_flatpages` will behave the same as if you hadn't provided a user -- i.e., it will only show you public flatpages. Limiting flatpages by base URL ------------------------------ An optional argument, ``starts_with``, can be applied to limit the returned pages to those beginning with a particular base URL. This argument may be passed as a string, or as a variable to be resolved from the context. For example: .. code-block:: html+django {% get_flatpages '/about/' as about_pages %} {% get_flatpages about_prefix as about_pages %} {% get_flatpages '/about/' for someuser as about_pages %}