Написание шаблонов

Wagtail использует язык шаблонов Django. Для разработчиков, новых для Django, начните с документации шаблонов Django: Шаблоны

Программисты Python, новые для Django/Wagtail, могут предпочесть более техническую документацию: Язык шаблонов Django: для программистов Python

Вы должны быть знакомы с основами шаблонов Django, прежде чем продолжить работу с этой документацией.

Шаблоны

Каждый тип страницы или «тип контента» в Wagtail определяется как «модель» в файле, называемом models.py. Если у вашего сайта есть блог, у вас может быть BlogPage модель и еще одна, называемая BlogPageListing. Имена моделей зависят от разработчика Django.

Для каждой модели страницы в models.py, Wagtail предполагает наличие файла шаблона HTML с (почти) таким же именем. Разработчик фронтенда может потребоваться создать эти шаблоны самостоятельно, руководствуясь models.py, чтобы определить имена шаблонов по моделям, определенным в нём.

Для поиска подходящего шаблона Wagtail преобразует CamelCase в snake_case. Итак, для BlogPage, ожидается шаблон blog_page.html. Имя файла шаблона может быть переопределено для каждой модели, если это необходимо.

Файлы шаблонов предполагается разместить здесь:

name_of_project/
    name_of_app/
        templates/
            name_of_app/
                blog_page.html
        models.py

Дополнительную информацию см. в документации Django для загрузчика шаблонов каталогов приложения.

Содержание страницы

Доступ к данным/содержанию каждой страницы и вывод осуществляется через обозначение Django {{ double-brace }}. Каждый элемент из модели должен быть получен с префиксом page.. Например, заголовок страницы {{ page.title }} или другой элемент {{ page.author }}.

Имена пользовательских переменных можно настроить в модели страницы wagtail.models.Page.context_object_name. Если имя пользовательское, page всё ещё доступно для использования в общих шаблонах.

Кроме того, request. доступен и содержит объект запроса Django.

Статические ресурсы

Статические файлы (например, CSS, JS и изображения) обычно хранятся здесь:

name_of_project/
    name_of_app/
        static/
            name_of_app/
                css/
                js/
                images/
        models.py

(Имена «css», «js» и т. д. не важны, важна только их позиция в дереве.)

Любой файл в папке static должен быть вставлен в ваш HTML с помощью тега {% static %}. Подробнее об этом: Статические файлы (тег).

Изображения пользователей

Изображения, загруженные пользователями сайта Wagtail (в отличие от статических файлов разработчика, упомянутых выше), попадают в библиотеку изображений, а оттуда добавляются на страницы через интерфейс редактора страницы.

В отличие от других CMS, добавление изображений на страницу не включает выбор «версии» изображения для использования. В Wagtail нет предварительно определённых «форматов» или «размеров» изображений. Вместо этого разработчик шаблона определяет обработку изображений «на лету», когда изображение запрашивается, с помощью специального синтаксиса внутри шаблона.

Изображения из библиотеки должны запрашиваться с помощью этого синтаксиса, но статические изображения разработчика могут быть добавлены стандартными способами, например, с помощью тегов img . Только изображения из библиотеки могут обрабатываться на лету.

Подробнее о синтаксисе обработки изображений см. здесь: Как использовать изображения в шаблонах.

Теги и фильтры шаблонов

В дополнение к стандартным тегам и фильтрам Django Wagtail предоставляет некоторые свои собственные, которые могут быть load-ed точно так же, как и любые другие.

Изображения (тег)

Тег image вставляет XHTML-совместимый элемент img на страницу, устанавливая его src, width, height и alt. См. также Больше контроля над тегом img.

Синтаксис тега image таков:

{% image [image] [resize-rule] %}

Например:

{% load wagtailimages_tags %}
...

{% image page.photo width-400 %}

<!-- or a square thumbnail: -->
{% image page.photo fill-80x80 %}

См. Как использовать изображения в шаблонах для полной документации.

Форматированный текст (фильтр)

Этот фильтр принимает фрагмент HTML-контента и отображает его как безопасный HTML на странице. Важно, что он также расширяет внутренние сокращённые ссылки на встроенные изображения и ссылки, созданные в редакторе Wagtail, в полностью сформированный HTML, готовый к отображению.

Этот фильтр необходим только для полей, использующих RichTextField в шаблоне.

{% load wagtailcore_tags %}
...
{{ page.body|richtext }}

Реагирующие вставки

Поскольку Wagtail не накладывает собственной стилистики на шаблоны, изображения и встроенные медиа будут отображаться с фиксированной шириной, определяемой HTML. Изображения можно сделать масштабируемыми для подгонки к своему контейнеру с помощью правила CSS, например:

.body img {
    max-width: 100%;
    height: auto;
}

где body — это элемент контейнера в вашем шаблоне, окружающий изображения.

Также возможно сделать встроенные медиа масштабируемыми, но обычно это требует пользовательских правил стиля, соответствующих соотношению сторон медиа. Для помощи в этом Wagtail предоставляет встроенную поддержку реагирующих вставок, которую можно включить, установив WAGTAILEMBEDS_RESPONSIVE_HTML = True в настройках вашего проекта. Это добавляет CSS-класс responsive-object и inline padding-bottom стиль к вставке, которые следует использовать вместе со следующим CSS:

.responsive-object {
    position: relative;
}

.responsive-object iframe,
.responsive-object object,
.responsive-object embed {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
}

Внутренние ссылки (тег)

`pageurl`

Принимает объект страницы и возвращает относительный URL (/foo/bar/) если он находится в том же сайте, что и текущая страница, или абсолютный (http://example.com/foo/bar/) если нет.

{% load wagtailcore_tags %}
...
<a href="{% pageurl page.get_parent %}">Back to index</a>

Можно передать ключевое слово fallback, которое может быть строкой URL, именем маршрута URL, который может быть разрешен без параметров, или объектом с методом get_absolute_url, и он будет использоваться как альтернативный URL, когда переданная страница None.

{% load wagtailcore_tags %}

{% for publication in page.related_publications.all %}
    <li>
        <a href="{% pageurl publication.detail_page fallback='coming_soon' %}">
            {{ publication.title }}
        </a>
    </li>
{% endfor %}

`slugurl`

Принимает любой slug (как определено на вкладке «Продвигать» страницы) и возвращает URL для соответствующей страницы. Если существует несколько страниц с одинаковым slug, выбор страницы не определён.

Как и pageurl, это попытается предоставить относительную ссылку, если это возможно, но по умолчанию использует абсолютную ссылку, если страница находится на другом сайте. Это наиболее полезно при создании общего контента страницы, например, верхнего уровня навигации или ссылок по всему сайту.

{% load wagtailcore_tags %}
...
<a href="{% slugurl 'news' %}">News index</a>

Статические файлы (тег)

Используется для загрузки любого файла из вашего каталога статических файлов. Использование этого тега предотвращает переписывание всех статических путей при изменении хостинга, так как они могут отличаться между средами разработки и публикации.

{% load static %}
...
<img src="{% static "name_of_app/myimage.jpg" %}" alt="My image"/>

Обратите внимание, что полный путь не требуется — путь, указанный здесь, является относительным к каталогу static приложения. Чтобы избежать конфликтов со статическими файлами других приложений (включая сам Wagtail), рекомендуется размещать статические файлы в подкаталоге static с тем же именем, что и приложение.

Поддержка множества сайтов

`wagtail_site`

Возвращает объект сайта, соответствующий текущему запросу.

{% load wagtailcore_tags %}

{% wagtail_site as current_site %}

Панель пользователя Wagtail

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

Этот тег можно использовать на стандартных представлениях Django без объекта страницы. Панель пользователя будет содержать один элемент, ведущий в админку.

Рекомендуется разместить тег в верхней части элемента <body> для удобства пользователей с клавиатурой. Вы должны поместить тег после любых ссылок для быстрого перехода skip links, но перед навигацией и основным содержимым страницы.

{% load wagtailuserbar %}
...
<body>
    <a id="#content">Skip to content</a>
    {% wagtailuserbar %} {# This is a good place for the userbar #}
    <nav>
    ...
    </nav>
    <main id="content">
    ...
    </main>
</body>

По умолчанию панель пользователя отображается в правом нижнем углу окна браузера, отступом от края. Если это конфликтует с вашим дизайном, вы можете переместить её, передав параметр в тег шаблона. Эти примеры показывают, как расположить панель пользователя в каждом углу экрана:

...
{% wagtailuserbar 'top-left' %}
{% wagtailuserbar 'top-right' %}
{% wagtailuserbar 'bottom-left' %}
{% wagtailuserbar 'bottom-right' %}
...

Панель пользователя можно разместить там, где это лучше всего подходит для вашего дизайна. Кроме того, вы можете разместить её с помощью правила CSS в ваших собственных CSS-файлах, например:

.wagtail-userbar {
    top: 200px !important;
    left: 10px !important;
}

Изменение вывода между предварительным просмотром и опубликованной версией

Иногда вам может потребоваться изменить вывод шаблона в зависимости от того, просматривается ли страница в режиме предварительного просмотра или в режиме публикации. Например, если у вас есть код отслеживания посетителей, например, Google Analytics, на вашем сайте, лучше отключить его во время предварительного просмотра, чтобы действия редактора не появлялись в ваших отчётах об аналитике. Wagtail предоставляет переменную request.is_preview для различения предварительного просмотра и публикации:

{% if not request.is_preview %}
    <script>
        (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
        ...
    </script>
{% endif %}

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