The flatpages app

    A flatpage is a 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 tostore in a database but for which you don’t want to develop a custom Djangoapplication.

    A flatpage can use a custom template or a default, systemwide flatpagetemplate. It can be associated with one, or multiple, sites.

    The content field may optionally be left blank if you prefer to put yourcontent in a custom template.

    To install the flatpages app, follow these steps:

    • Install the by adding'django.contrib.sites' to your setting,if it’s not already in there.

    Also make sure you’ve correctly set SITE_ID to the ID of thesite the settings file represents. This will usually be 1 (i.e.SITE_ID = 1, but if you’re using the sites framework to managemultiple sites, it could be the ID of a different site.

    • Add 'django.contrib.flatpages' to your setting.

    Then either:

    • Add an entry in your URLconf. For example:

    or:

    • Add 'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'to your MIDDLEWARE setting.
    • Run the command .

    How it works

    manage.py migrate creates two tables in your database: django_flatpageand django_flatpage_sites. django_flatpage is a lookup table that mapsa URL to a title and bunch of text content. django_flatpage_sitesassociates a flatpage with a site.

    There are several ways to include the flat pages in your URLconf. You candedicate a particular path to flat pages:

    1. urlpatterns = [
    2.     path('pages/', include('django.contrib.flatpages.urls')),
    3. ]

    You can also set it up as a “catchall” pattern. In this case, it is importantto place the pattern at the end of the other urlpatterns:

    1. from django.contrib.flatpages import views
    2. # Your other patterns here
    3. urlpatterns += [
    4.     path('<path:url>', views.flatpage),
    5. ]

    Warning

    If you set to False, you must remove the slashin the catchall pattern or flatpages without a trailing slash will not bematched.

    Using the middleware

    The can do all of the work.

    • class FlatpageFallbackMiddleware
    • Each time any Django application raises a 404 error, this middlewarechecks the flatpages database for the requested URL as a last resort.Specifically, it checks for a flatpage with the given URL with a site IDthat corresponds to the 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 flatpages/default.html.
    • It passes that template a single context variable, flatpage,which is the flatpage object. It usesRequestContext in rendering thetemplate.The middleware will only add a trailing slash and redirect (by lookingat the setting) if the resulting URL refers toa valid flatpage. Redirects are permanent (301 status code).

    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 responsesof any other status code.

    Flatpages will not apply view middleware

    Because the FlatpageFallbackMiddleware is applied only afterURL resolution has failed and produced a 404, the response itreturns will not apply any view middlewaremethods. Only requests which are successfully routed to a view vianormal URL resolution apply view middleware.

    Note that the order of matters. Generally, you can putFlatpageFallbackMiddleware at theend of the list. This means it will run first when processing the response, andensures that any other response-processing middleware see the real flatpageresponse rather than the 404.

    For more on middleware, read the .

    Ensure that your 404 template works

    Note that theFlatpageFallbackMiddlewareonly steps in once another view has successfully produced a 404 response.If another view or middleware class attempts to produce a 404 but ends upraising an exception instead, the response will become an HTTP 500(“Internal Server Error”) and thewill not attempt to serve a flat page.

    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 anyother object in the system.

    The FlatPage model has an enable_comments field that isn’t used bycontrib.flatpages, but that could be useful for your project or third-partyapps. It doesn’t appear in the admin interface, but you can add it byregistering a custom ModelAdmin for FlatPage:

    1. from django.contrib import admin
    2. from django.contrib.flatpages.admin import FlatPageAdmin
    3. from django.contrib.flatpages.models import FlatPage
    4. from django.utils.translation import gettext_lazy as _
    5.  
    6. # Define a new FlatPageAdmin
    7. class FlatPageAdmin(FlatPageAdmin):
    8.     fieldsets = (
    9.         (None, {'fields': ('url', 'title', 'content', 'sites')}),
    10.         (_('Advanced options'), {
    11.             'classes': ('collapse',),
    12.             'fields': (
    13.                 'enable_comments',
    14.                 'registration_required',
    15.             ),
    16.         }),
    17.     )
    18.  
    19. # Re-register FlatPageAdmin
    20. admin.site.unregister(FlatPage)
    21. admin.site.register(FlatPage, FlatPageAdmin)

    Via the Python API

    If you add or modify flatpages via your own code, you will likely want tocheck for duplicate flatpage URLs within the same site. The flatpage formused in the admin performs this validation check, and can be imported fromdjango.contrib.flatpages.forms.FlatpageForm and used in your ownviews.

    Flatpage templates

    By default, flatpages are rendered via the templateflatpages/default.html, but you can override that for aparticular flatpage: in the admin, a collapsed fieldset titled“Advanced options” (clicking will expand it) contains a field forspecifying a template name. If you’re creating a flat page via thePython API you can set the template name as the field template_name on theFlatPage object.

    Creating the flatpages/default.html template is your responsibility;in your template directory, create a directory containing afile default.html.

    Flatpage templates are passed a single context variable, flatpage,which is the flatpage object.

    Here’s a sample flatpages/default.html template:

    1. <!DOCTYPE html>
    2. <html>
    3. <head>
    4. <title>{{ flatpage.title }}</title>
    5. </head>
    6. <body>
    7. {{ flatpage.content }}
    8. </body>
    9. </html>

    Since you’re already entering raw HTML into the admin page for a flatpage,both flatpage.title and flatpage.content are marked as notrequiring automatic HTML escaping in thetemplate.

    The flatpages app provides a template tag that allows you to iterateover all of the available flatpages on the .

    Like all custom template tags, you’ll need to load its customtag library before you can useit. After loading the library, you can retrieve all current flatpagesvia the tag:

    By default, the get_flatpages template tag will only showflatpages that are marked registration_required = False. If youwant to display registration-protected flatpages, you need to specifyan authenticated user using a for clause.

    For example:

    1. {% get_flatpages for someuser as about_pages %}

    If you provide an anonymous user, will behavethe same as if you hadn’t provided a user – i.e., it will only show youpublic flatpages.

    Limiting flatpages by base URL

    An optional argument, starts_with, can be applied to limit thereturned pages to those beginning with a particular base URL. Thisargument may be passed as a string, or as a variable to be resolvedfrom the context.

    1. {% get_flatpages '/about/' as about_pages %}
    2. {% get_flatpages about_prefix as about_pages %}
    3. {% get_flatpages '/about/' for someuser as about_pages %}

    Integrating with django.contrib.sitemaps

    Here’s an example of a URLconf using :