Разработка тем оформления для Drupal 8. Часть 5: Шаблоны Twig

В этой статье мы рассмотрим механизм работы с шаблонами. Это очень мощный, и в тоже время, простой способ работы с разметкой в Drupal.

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

• использование шаблонов разметки;
• использование функций в темах оформления (модулях).

Организация Шаблонов

Шаблоны — это файлы содержащие разметку и специальные директивы, которые будут заменены в процессе рендера на значения для отображаемого элемента. В Drupal 8 используется обработчик шаблонов Twig. Twig — это современный, мощный и гибкий инструмент, и его появление в Drupal 8 существенно упрощает работу с шаблонами и открывает новые возможности.

Файлы шаблонов должны иметь расширение *.html.twig и располагаться в папке templates или вложенных папках. Существуют определенные правила именования файлов шаблонов, и именно по ним Drupal определяет необходимость использования шаблона. То есть, чтобы переопределить какой-либо системный шаблон достаточно просто наличия файла с соответствующем названием в папке templates вашей темы. Аналогичным способом добавляются шаблоны специфичные для определенных элементов.

Системных шаблонов довольно много, их названия и содержимое можно посмотреть в теме Stable, здесь же я приведу некоторые основные:

• html.html.twig — шаблон базовой разметки страницы;
• page.html.twig — шаблон расположения регионов страницы;
• node.html.twig — шаблон страницы контента;
• block.html.twig — шаблон блока.

Примеры названий шаблонов специфичных для определенных элементов:

• page--node.html.twig — шаблон расположения регионов страницы контента;
• node--TYPE.html.twig — шаблон страницы контента типа TYPE;
• node--VIEWMODE.html.twig — шаблон страницы контента в режиме отображения VIEWMODE;
• node--TYPE--VIEWMODE.html.twig — шаблон страницы контента типа TYPE в режиме отображения VIEWMODE.

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

parameters:
  twig.config:
    debug: true

Файл services.yml должен располагаться в папке сайта, там же где файл settings.php, но по умолчанию он отсутствует. Его можно создать на основе файла default.services.yml. После сброса кеша, в комментариях к коду страницы будет выводиться информация о шаблонах.

Пример шаблона

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

Шаблон page.html.twig темы Stable:

<div class="layout-container">

  <header role="banner">
    {{ page.header }}
  </header>

  {{ page.primary_menu }}
  {{ page.secondary_menu }}
  {{ page.breadcrumb }}
  {{ page.highlighted }}
  {{ page.help }}

  <main role="main">
    <a id="main-content" tabindex="-1"></a>{# link is in html.html.twig #}

    <div class="layout-content">
      {{ page.content }}
    </div>{# /.layout-content #}

    {% if page.sidebar_first %}
      <aside class="layout-sidebar-first" role="complementary">
        {{ page.sidebar_first }}
      </aside>
    {% endif %}

    {% if page.sidebar_second %}
      <aside class="layout-sidebar-second" role="complementary">
        {{ page.sidebar_second }}
      </aside>
    {% endif %}
  </main>

  {% if page.footer %}
    <footer role="contentinfo">
      {{ page.footer }}
    </footer>
  {% endif %}

</div>{# /.layout-container #}

В файлах Twig может присутствовать HTML разметка и директивы следующих типов:

• {{ variable }} — переменная;
• {% function %} — функция;
• {# comment #} — комментарий.

В примере нам часто встречаются директивы типа {{ page.header }} — это переменные, которые в данном случае будут заменены на отрендеренное содержимое региона. В регионы мы можем помещать блоки через административный интерфейс. Для некоторых регионов, например для footer, предусмотрена дополнительная обертка, и чтобы она не выводилась, когда регион не имеет содержимого, для всей конструкции добавлено условие {% if page.footer %}, проверяющее наличие содержимого.

При необходимости, можно создавать собственные регионы. Для этого сначала необходимо добавить информацию о них в файл THEMENAME.info.yml, после чего можно будет использовать их в шаблонах. В теме Stable используются только регионы "по умолчанию", поэтому информация о них отсутствует. Названия регионов "по умолчанию" и сопутствующую информацию можно посмотреть в документации. Добавление даже одного нового региона полностью переопределяет информацию о них, унаследованную от базовой темы. В этом случае, в файле конфигурации нужно будет перечислить все регионы, которые вы собираетесь использовать в своей теме, включая регионы "по умолчанию".

Возможности Twig

Возможности и особенности Twig:

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

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

Пример создания массива классов в шаблоне node.html.twig темы Classy:

{%
  set classes = [
    'node',
    'node--type-' ~ node.bundle|clean_class,
    node.isPromoted() ? 'node--promoted',
    node.isSticky() ? 'node--sticky',
    not node.isPublished() ? 'node--unpublished',
    view_mode ? 'node--view-mode-' ~ view_mode|clean_class,
  ]
%}

<article{{ attributes.addClass(classes) }}>

В этом примере массив classes заполняется значениями, в зависимости от значений переменных в массиве node, который содержит информацию о текущей странице. Оператор ? означает, что если выражение слева истинно, то значение справа будет добавлено в массив. В последнем условии значение формируется с помощью объединения строк (оператор ~), а также применяется фильтр clean_class нормализующий значение для использования в качестве класса. Фильтры применяются к выражению с помощью символа |. Полученный массив с помощью функции addClass() добавляется к массиву атрибутов attributes определенному в рендер-массиве.

Вывод массива атрибутов элемента

Некоторые функции и фильтры в примере являются расширениями встроенных возможностей Twig и присутствуют только в Drupal. Ознакомиться с ними подробнее можно в документации.

В следующей статье мы рассмотрим использование функций в темах оформления.