Приложение flatpages

Django поставляется с необязательным приложением «flatpages». Оно позволяет хранить «плоское» HTML-содержимое в базе данных и управлять им через админскую панель Django и Python-API.

Flatpage — это объект с URL, заголовком и содержимым. Используйте его для одноразовых страниц со специальными случаями, таких как страницы «О нас» или «Политика конфиденциальности», которые вы хотите хранить в базе данных, но для которых не хотите разрабатывать собственное приложение Django.

Flatpage может использовать пользовательский шаблон или стандартный, системный шаблон flatpage. Он может быть связан с одним или несколькими сайтами.

Поле «содержимое» можно оставить пустым, если вы предпочитаете размещать содержимое в пользовательском шаблоне.

Установка

Чтобы установить приложение flatpages, выполните следующие действия:

1. Установите приложение sites framework, добавив 'django.contrib.sites' в настройку INSTALLED_APPS, если она там еще не указана.

   Также убедитесь, что вы правильно установили SITE_ID на ID сайта, который представляет файл настроек. Обычно это 1 (т.е. SITE_ID = 1, но если вы используете фреймворк сайтов для управления несколькими сайтами, это может быть ID другого сайта).

2. Добавьте 'django.contrib.flatpages' в настройку INSTALLED_APPS.

Затем выполните одно из следующих действий:

3. Добавьте запись в ваш файл URLconf. Например:

   urlpatterns = [
       path("pages/", include("django.contrib.flatpages.urls")),
   ]
   

или:

3. Добавьте 'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware' в настройку MIDDLEWARE.
4. Запустите команду manage.py migrate.

Как это работает

manage.py migrate создаёт две таблицы в вашей базе данных: django_flatpage и django_flatpage_sites. django_flatpage — это справочная таблица, которая сопоставляет URL с заголовком и текстовым содержимым. django_flatpage_sites связывает flatpage со сайтом.

Использование URLconf

Существует несколько способов включения страниц flatpages в ваш URLconf. Вы можете выделить конкретный путь для flatpages:

urlpatterns = [
    path("pages/", include("django.contrib.flatpages.urls")),
]

Вы также можете настроить его как «универсальный» шаблон. В этом случае важно разместить шаблон в конце других urlpatterns:

from django.contrib.flatpages import views

# Your other patterns here
urlpatterns += [
    re_path(r"^(?P<url>.*/)$", views.flatpage),
]

Другая распространённая настройка — использование flatpages для ограниченного набора известных страниц и жёсткое кодирование URL-адресов, чтобы вы могли ссылаться на них с помощью тега шаблона url:

from django.contrib.flatpages import views

urlpatterns += [
    path("about-us/", views.flatpage, {"url": "/about-us/"}, name="about"),
    path("license/", views.flatpage, {"url": "/license/"}, name="license"),
]

Использование middleware

Модуль FlatpageFallbackMiddleware может выполнить всю работу.

class FlatpageFallbackMiddleware

Каждый раз, когда какое-либо приложение Django генерирует ошибку 404, этот модуль проверяет базу данных flatpages на запрашиваемый URL в качестве последней меры. В частности, он ищет flatpage с указанным URL и идентификатором сайта, соответствующим настройке SITE_ID.

Если совпадение найдено, он выполняет следующие действия:

• Если у flatpage есть пользовательский шаблон, он загружает этот шаблон. В противном случае, он загружает шаблон flatpages/default.html.
• Он передает этому шаблону единственную переменную контекста flatpage, которая представляет собой объект flatpage. Он использует RequestContext для рендеринга шаблона.

Middleware добавит конечный слэш и перенаправит (проверив настройку APPEND_SLASH), если полученный URL соответствует действительной странице flatpage. Перенаправления являются постоянными (код состояния 301).

Если совпадение не найдено, обработка запроса продолжается в обычном режиме.

Middleware активируется только для ошибок 404 — а не для ошибок 500 или ответов с другим кодом состояния.

Обратите внимание на порядок расположения MIDDLEWARE. Обычно вы можете поместить FlatpageFallbackMiddleware в конец списка. Это означает, что он будет работать первым при обработке ответа и гарантирует, что любой другой middleware для обработки ответа увидит фактический ответ flatpage, а не ошибку 404.

Подробнее о middleware см. в документации по middleware.

Как добавлять, изменять и удалять flatpages

Через админскую панель

Если вы активировали автоматическую админскую панель Django, вы должны увидеть раздел «Flatpages» на главной странице администрирования. Редактируйте flatpages так же, как и любой другой объект в системе.

Модель FlatPage имеет поле enable_comments, которое не используется contrib.flatpages, но может быть полезно для вашего проекта или сторонних приложений. Оно не отображается в админской панели, но вы можете добавить его, зарегистрировав пользовательский ModelAdmin для FlatPage:

from django.contrib import admin
from django.contrib.flatpages.admin import FlatPageAdmin
from django.contrib.flatpages.models import FlatPage
from django.utils.translation import gettext_lazy as _


# Define a new FlatPageAdmin
class FlatPageAdmin(FlatPageAdmin):
    fieldsets = [
        (None, {"fields": ["url", "title", "content", "sites"]}),
        (
            _("Advanced options"),
            {
                "classes": ["collapse"],
                "fields": [
                    "enable_comments",
                    "registration_required",
                    "template_name",
                ],
            },
        ),
    ]


# Re-register FlatPageAdmin
admin.site.unregister(FlatPage)
admin.site.register(FlatPage, FlatPageAdmin)

Через Python-API

class FlatPage

Flatpages представлены стандартной моделью Django, которая находится в django/contrib/flatpages/models.py. Вы можете получить доступ к объектам flatpage через API базы данных Django.

Шаблоны flatpage

По умолчанию flatpages отображаются через шаблон flatpages/default.html, но вы можете переопределить его для конкретной flatpage: в админской панели в свёрнутом разделе «Дополнительные параметры» (нажатие откроет его) есть поле для указания имени шаблона. Если вы создаёте страницу flatpage через Python-API, вы можете установить имя шаблона в качестве поля template_name объекта FlatPage.

Вы сами должны создать шаблон flatpages/default.html; в вашей директории шаблонов создайте директорию flatpages, содержащую файл default.html.

Шаблонам flatpage передаётся одна переменная контекста flatpage, которая представляет собой объект flatpage.

Вот пример шаблона flatpages/default.html:

<!DOCTYPE html>
<html>
<head>
<title>{{ flatpage.title }}</title>
</head>
<body>
{{ flatpage.content }}
</body>
</html>

Поскольку вы уже вводите исходный HTML в админскую страницу для flatpage, оба поля flatpage.title и flatpage.content помечены как не требующие автоматической экранизации HTML в шаблоне.

Получение списка объектов FlatPage в ваших шаблонах

Приложение flatpages предоставляет тег шаблона, который позволяет итерировать по всем доступным flatpage на текущем сайте.

Как и все пользовательские теги шаблонов, вам необходимо загрузить его библиотеку пользовательских тегов, прежде чем вы сможете его использовать. После загрузки библиотеки вы можете получить все текущие статические страницы с помощью тега get_flatpages:

{% load flatpages %}
{% get_flatpages as flatpages %}
<ul>
    {% for page in flatpages %}
        <li><a href="{{ page.url }}">{{ page.title }}</a></li>
    {% endfor %}
</ul>

Отображение registration_required статических страниц

По умолчанию тег шаблона get_flatpages будет отображать только статические страницы, отмеченные registration_required = False. Если вы хотите отобразить защищённые от регистрации статические страницы, вам необходимо указать аутентифицированного пользователя с помощью for.

Например:

{% get_flatpages for someuser as about_pages %}

Если вы предоставите анонимного пользователя, get_flatpages будет вести себя так же, как если бы вы не предоставили пользователя — то есть, он отобразит только публичные статические страницы.

Ограничение статических страниц по базовому URL

Необязательный аргумент, starts_with, может быть использован для ограничения возвращаемых страниц теми, которые начинаются с определённого базового URL. Этот аргумент можно передать в виде строки или в виде переменной, подлежащей разрешению из контекста.

Например:

{% get_flatpages '/about/' as about_pages %}
{% get_flatpages about_prefix as about_pages %}
{% get_flatpages '/about/' for someuser as about_pages %}

Интеграция с django.contrib.sitemaps

class FlatPageSitemap

Класс sitemaps.FlatPageSitemap рассматривает все публично видимые flatpages, определённые для текущего SITE_ID (см. sites documentation) и создаёт запись в карте сайта. Эти записи включают только атрибут location — а не lastmod, changefreq или priority.

Пример

Вот пример URLconf, использующего FlatPageSitemap:

from django.contrib.flatpages.sitemaps import FlatPageSitemap
from django.contrib.sitemaps.views import sitemap
from django.urls import path

urlpatterns = [
    # ...
    # the sitemap
    path(
        "sitemap.xml",
        sitemap,
        {"sitemaps": {"flatpages": FlatPageSitemap}},
        name="django.contrib.sitemaps.views.sitemap",
    ),
]