/docs/ref/contrib/flatpages.txt
Plain Text | 236 lines | 169 code | 67 blank | 0 comment | 0 complexity | 9ace50888bb86ed38366ca1d9a60d108 MD5 | raw file
Possible License(s): BSD-3-Clause
1================= 2The flatpages app 3================= 4 5.. module:: django.contrib.flatpages 6 :synopsis: A framework for managing simple ?flat? HTML content in a database. 7 8Django comes with an optional "flatpages" application. It lets you store simple 9"flat" HTML content in a database and handles the management for you via 10Django's admin interface and a Python API. 11 12A flatpage is a simple object with a URL, title and content. Use it for 13one-off, special-case pages, such as "About" or "Privacy Policy" pages, that 14you want to store in a database but for which you don't want to develop a 15custom Django application. 16 17A flatpage can use a custom template or a default, systemwide flatpage 18template. It can be associated with one, or multiple, sites. 19 20The content field may optionally be left blank if you prefer to put your 21content in a custom template. 22 23Here are some examples of flatpages on Django-powered sites: 24 25 * http://www.lawrence.com/about/contact/ 26 * http://www2.ljworld.com/site/rules/ 27 28Installation 29============ 30 31To install the flatpages app, follow these steps: 32 33 1. Install the :mod:`sites framework <django.contrib.sites>` by adding 34 ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting, 35 if it's not already in there. 36 37 Also make sure you've correctly set :setting:`SITE_ID` to the ID of the 38 site the settings file represents. This will usually be ``1`` (i.e. 39 ``SITE_ID = 1``, but if you're using the sites framework to manage 40 multiple sites, it could be the ID of a different site. 41 42 2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS` 43 setting. 44 45 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` 46 to your :setting:`MIDDLEWARE_CLASSES` setting. 47 48 4. Run the command :djadmin:`manage.py syncdb <syncdb>`. 49 50.. currentmodule:: django.contrib.flatpages.middleware 51 52How it works 53============ 54 55``manage.py syncdb`` creates two tables in your database: ``django_flatpage`` 56and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table 57that simply maps a URL to a title and bunch of text content. 58``django_flatpage_sites`` associates a flatpage with a site. 59 60The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` 61does all of the work. 62 63.. class:: FlatpageFallbackMiddleware 64 65 Each time any Django application raises a 404 error, this middleware 66 checks the flatpages database for the requested URL as a last resort. 67 Specifically, it checks for a flatpage with the given URL with a site ID 68 that corresponds to the :setting:`SITE_ID` setting. 69 70 If it finds a match, it follows this algorithm: 71 72 * If the flatpage has a custom template, it loads that template. 73 Otherwise, it loads the template :file:`flatpages/default.html`. 74 75 * It passes that template a single context variable, ``flatpage``, 76 which is the flatpage object. It uses 77 :class:`~django.template.RequestContext` in rendering the 78 template. 79 80 If it doesn't find a match, the request continues to be processed as usual. 81 82 The middleware only gets activated for 404s -- not for 500s or responses 83 of any other status code. 84 85.. admonition:: Flatpages will not apply view middleware 86 87 Because the ``FlatpageFallbackMiddleware`` is applied only after 88 URL resolution has failed and produced a 404, the response it 89 returns will not apply any :ref:`view middleware <view-middleware>` 90 methods. Only requests which are successfully routed to a view via 91 normal URL resolution apply view middleware. 92 93Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can 94put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at 95the end of the list, because it's a last resort. 96 97For more on middleware, read the :doc:`middleware docs 98</topics/http/middleware>`. 99 100.. admonition:: Ensure that your 404 template works 101 102 Note that the 103 :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` 104 only steps in once another view has successfully produced a 404 response. 105 If another view or middleware class attempts to produce a 404 but ends up 106 raising an exception instead (such as a ``TemplateDoesNotExist`` 107 exception if your site does not have an appropriate template to 108 use for HTTP 404 responses), the response will become an HTTP 500 109 ("Internal Server Error") and the 110 :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` 111 will not attempt to serve a flat page. 112 113.. currentmodule:: django.contrib.flatpages.models 114 115How to add, change and delete flatpages 116======================================= 117 118Via the admin interface 119----------------------- 120 121If you've activated the automatic Django admin interface, you should see a 122"Flatpages" section on the admin index page. Edit flatpages as you edit any 123other object in the system. 124 125Via the Python API 126------------------ 127 128.. class:: FlatPage 129 130 Flatpages are represented by a standard 131 :doc:`Django model </topics/db/models>`, 132 which lives in `django/contrib/flatpages/models.py`_. You can access 133 flatpage objects via the :doc:`Django database API </topics/db/queries>`. 134 135.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py 136 137.. currentmodule:: django.contrib.flatpages 138 139Flatpage templates 140================== 141 142By default, flatpages are rendered via the template 143:file:`flatpages/default.html`, but you can override that for a 144particular flatpage: in the admin, a collapsed fieldset titled 145"Advanced options" (clicking will expand it) contains a field for 146specifying a template name. If you're creating a flat page via the 147Python API you can simply set the template name as the field 148``template_name`` on the ``FlatPage`` object. 149 150Creating the :file:`flatpages/default.html` template is your responsibility; 151in your template directory, just create a :file:`flatpages` directory 152containing a file :file:`default.html`. 153 154Flatpage templates are passed a single context variable, ``flatpage``, 155which is the flatpage object. 156 157Here's a sample :file:`flatpages/default.html` template: 158 159.. code-block:: html+django 160 161 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" 162 "http://www.w3.org/TR/REC-html40/loose.dtd"> 163 <html> 164 <head> 165 <title>{{ flatpage.title }}</title> 166 </head> 167 <body> 168 {{ flatpage.content }} 169 </body> 170 </html> 171 172Since you're already entering raw HTML into the admin page for a flatpage, 173both ``flatpage.title`` and ``flatpage.content`` are marked as **not** 174requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the 175template. 176 177Getting a list of :class:`~django.contrib.flatpages.models.FlatPage` objects in your templates 178============================================================================================== 179 180.. versionadded:: 1.3 181 182The flatpages app provides a template tag that allows you to iterate 183over all of the available flatpages on the :ref:`current site 184<hooking-into-current-site-from-views>`. 185 186Like all custom template tags, you'll need to :ref:`load its custom 187tag library <loading-custom-template-libraries>` before you can use 188it. After loading the library, you can retrieve all current flatpages 189via the :ttag:`get_flatpages` tag: 190 191.. code-block:: html+django 192 193 {% load flatpages %} 194 {% get_flatpages as flatpages %} 195 <ul> 196 {% for page in flatpages %} 197 <li><a href="{{ page.url }}">{{ page.title }}</a></li> 198 {% endfor %} 199 </ul> 200 201.. templatetag:: get_flatpages 202 203Displaying ``registration_required`` flatpages 204---------------------------------------------- 205 206By default, the :ttag:`get_flatpages` templatetag will only show 207flatpages that are marked ``registration_required = False``. If you 208want to display registration-protected flatpages, you need to specify 209an authenticated user using a``for`` clause. 210 211For example: 212 213.. code-block:: html+django 214 215 {% get_flatpages for someuser as about_pages %} 216 217If you provide an anonymous user, :ttag:`get_flatpages` will behave 218the same as if you hadn't provided a user -- i.e., it will only show you 219public flatpages. 220 221Limiting flatpages by base URL 222------------------------------ 223 224An optional argument, ``starts_with``, can be applied to limit the 225returned pages to those beginning with a particular base URL. This 226argument may be passed as a string, or as a variable to be resolved 227from the context. 228 229For example: 230 231.. code-block:: html+django 232 233 {% get_flatpages '/about/' as about_pages %} 234 {% get_flatpages about_prefix as about_pages %} 235 {% get_flatpages '/about/' for someuser as about_pages %} 236