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

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 и 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`

Принимает объект 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 соответствующей страницы Page. Если существует несколько страниц с одинаковым slug, выбранная страница неопределена.

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

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

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

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

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

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

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

`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.