Создание шаблонов

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

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

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

Шаблоны

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

Для каждой модели страницы в models.py, Wagtail предполагает, что существует файл HTML-шаблона с (практически) тем же именем. Разработчику Front End может потребоваться создать эти шаблоны самостоятельно, обратившись к 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 }}.

Можно задать пользовательское имя переменной configured on the page model. Если определено пользовательское имя, 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-ить как и любые другие.

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

Тег 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 %}

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

Форматирование Rich Text (фильтр)

Этот фильтр принимает фрагмент 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 и строковый 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`

Принимает объект Page и возвращает относительный 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"/>

Обратите внимание, что полное имя файла не требуется, а вводимый фрагмент пути должен начинаться с имени родительского приложения.

Поддержка нескольких сайтов

`wagtail_site`

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

{% load wagtailcore_tags %}

{% wagtail_site as current_site %}

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

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

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

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

{% 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 можно использовать для определения конкретного режима предварительного просмотра, если страница поддерживает multiple preview modes.