Twig шаблоны. Установка и начало работы с Twig. Именование файлов шаблонов и функций
- "компилирующий обработчик шаблонов с открытым исходным кодом, написанный на языке программирования PHP. Armin Ronacher написал Twig в 2008 году для платформы блогов Chyrp. Он больше не возвращался к разработке и в большей степени занимался разработкой на Python. Синтаксис языка шаблонов Twig берёт начало от движков шаблонов Jinja и Django, первый из которых также создан Ронакером. Идею данного шаблонизатора развивает и поддерживает Fabien Potencier, ведущий разработчик и идеолог фреймворка Symfony, в котором Twig используется по умолчанию." (https://ru.wikipedia.org/wiki/Twig).
Все Twig шаблоны в Drupal 8 компилируются в php файлы и хранятся в каталоге sites/default/files/php/twig/. Файлы шаблонов при этом кешируются для повторного использования и хранятся в файловой системе для улучшения производительности, перекомпилируются только при очистке Twig кеша.
Все шаблоны в модулях и темах должны находиться в каталоге /templates
.
Почему Twig? Во-первых, он более безопасный. В шаблонах Drupal 7 часто выводились неочищенные данные и это в принципе понятно, так как верстальщик не должен следить за работой программиста, который банально мог забыть пропустить данные из форм через check_plain(). В шаблонах же Drupal 8 переменные будут по-умолчанию экранироваться. Кроме этого многие наверняка в шаблонах наблюдали Sql запросы и прочие изыски логики приложения, но в Twig шаблонах это будет исключено.
Во-вторых, в Twig есть очень интересная особенность - наследование шаблонов. Теперь достаточно создать базовый родительский шаблон и затем при создании дочернего шаблона в теге extends указать родительский шаблон. К примеру чтобы создать дочерний шаблон ноды нужно в нем прописать:
{% extends "node.html.twig" %}
Рассмотрим наследование на примере шаблонов для блока. Базовый родительский шаблон для блока block.html.twig содержит примерно такой код
При этом содержимое тега block можно в дочернем шаблоне переписать. Рассмотрим код шаблона для блока с формой поиска block--search-form-block.html.twig
Большинство theme_ функций сейчас вынесено в шаблоны (огромный плюс)
PHPTemplate функция: theme_node_links()
Twig файл шаблона: node-links.html.twig
Docblock и комментарии
Docblock в PHPTemplate:
{#
/**
* @file
* File description
*/
#}
Комментарии вместо стандартных php комментариев теперь выглядят так:
{# Twig комментарий #}
Работа с переменными
Вывод переменных:
{{ content }}
Вывод свойств объектов и элементов массивов:
body; ?>
{{ content.body }}
Вывод элементов массива с хешем в имени ключа
{{ item["#item"].alt }}
Запись в переменную:
field_image; ?>
{% set image = content.field_image %}
Запись в переменную массива:
{% set classes = ["class1", "class2", "class3"] %}
Условия
comments): endif; ?>
{% if content.comments %} {% endif %}
comments)): endif; ?>
{% if content.comments is not empty %} {% endif %}
comments)): endif; ?>
{% if content.comments is defined %} {% endif %}
0): endif; ?>
{% if count > 0 %} {% endif %}
Циклы
{% for user in users %} {% endfor %}
Управление пробелами
Twig позволяет убирать пробелы из вывода с помощью символа -
в начале и/или конце структуры {{ }}
для вывода переменных.
И в начале, и в конце:
{{- block.content -}}
{#
Результат:
контент
#}
Только в начале:
{{- block.content }}
{#
Результат:
контент
#}
Только в конце:
{{ block.content -}}
{# Результат:
контент
#}
Официальная документация по Twig в Drupal 8
Twig 2 - Twig for Template Designers
Twig для дизайнеров шаблонов
Этот документ описывает синтаксис и семантику механизма шаблона и будет наиболее полезен в качестве ссылки на те, которые создают шаблоны Twig.
конспект
Шаблон - это просто текстовый файл. Он может генерировать любой текстовый формат (HTML, XML, CSV, LaTeX и т. Д.). У него нет определенного расширения, .html или.xml просто отлично.
Шаблон содержит переменные
или выражения
, которые заменяются значениями при оценке шаблона и тегами
, которые управляют логикой шаблона.
Ниже приведен минимальный шаблон, который иллюстрирует несколько основ. Ниже мы расскажем о следующих деталях:
My Webpage
{% for item in navigation %}
{{ item.caption }}
{% endfor %}
My Webpage
{{ a_variable }}
Существует два типа разделителей: {% ... %} и {{ ... }} . Первый используется для выполнения таких операторов, как for-loops, последний печатает результат выражения в шаблоне.
Интеграция с IDE
Многие IDE поддерживают подсветку синтаксиса и автозаполнение для Twig:
Textmate
через пакет Twig
Vim
через плагин синтаксиса Jinja или плагин vim-twig
Netbeans
через плагин синтаксиса Twig (до 7.1, родной по 7.2)
PhpStorm
(родной от 2.1)
Eclipse
через плагин Twig
Возвышенный текст
через пакет Twig
GtkSourceView
через определение языка Twig (используется gedit и другими проектами)
Coda
и SubEthaEdit
через синтаксический режим Twig
Coda 2
через другой синтаксический режим Twig
Комодо
и Комодо Редактировать
через режим Twid подсветки / синтаксиса
Блокнот ++
через Notepad ++ Twig Highlighter
Emacs
через web-mode.el
Atom
через PHP-ветку для атома
Код Visual Studio
через пакет Twig
Реализация
Для удобства foo.bar выполняет следующие действия на уровне PHP:
если нет, и если foo является объектом, проверьте, что bar является допустимым свойством;
если нет, и если foo является объектом, проверьте, что bar является допустимым методом (даже если bar является конструктором - вместо этого используйте __construct());
если нет, и если foo является объектом, проверьте, что getBar является допустимым методом;
если нет, и если foo является объектом, проверьте, что isBar является допустимым методом;
если нет, и если foo является объектом, проверьте, что hasBar является допустимым методом;
foo["bar"] с другой стороны, работает только с массивами PHP:
проверьте, является ли foo массивом и bar действительный элемент;
если нет, верните null значение.
Глобальные переменные
В шаблонах всегда доступны следующие переменные:
_self: ссылается на текущее имя шаблона;
_context: ссылается на текущий контекст;
_charset: ссылается на текущую кодировку.
Установка переменных
Вы можете назначать значения для переменных внутри кодовых блоков. В назначениях используется тег set
:
{% set foo = "foo" %}
{% set foo = %}
{% set foo = {"foo": "bar"} %}
фильтры
Переменные могут быть изменены фильтрами
. Фильтры отделяются от переменной символом (|) и могут иметь необязательные аргументы в круглых скобках. Несколько фильтров могут быть скованы цепью. Выход одного фильтра применяется к следующему.
В следующем примере удаляются все теги HTML из name и заголовков:
{{ name|striptags|title }}
Фильтры, которые принимают аргументы, имеют круглые скобки вокруг аргументов. Этот пример присоединяется к списку через запятую:
{{ list|join(", ") }}
Чтобы применить фильтр к разделу кода, оберните его в тег filter :
{% filter upper %}
This text becomes uppercase
{% endfilter %}
Members
{% for user in users %}
{{ user.username|e }}
{% endfor %}
{{ user.username|e }}
По умолчанию фильтр-победитель использует html стратегию, но в зависимости от контекста экранирования вы можете явно использовать любые другие доступные стратегии:
Независимо от того, включено ли автоматическое экранирование или нет, вы можете пометить раздел шаблона, который должен быть экранирован или нет, используя тег autoescape
:
{% autoescape %}
Everything will be automatically escaped in this block (using the HTML strategy)
{% endautoescape %}
По умолчанию автоматическое экранирование использует стратегию экранирования html . Если вы выводите переменные в других контекстах, вам необходимо явно избежать их с помощью соответствующей стратегии экранирования:
{% autoescape "js" %}
Everything will be automatically escaped in this block (using the JS strategy)
{% endautoescape %}
Спасаясь
Иногда желательно или даже необходимо, чтобы Twig игнорировали части, которые иначе обрабатывались бы как переменные или блоки. Например, если используется синтаксис по умолчанию, и вы хотите использовать {{ качестве исходной строки в шаблоне и не запускать переменную, вам нужно использовать трюк.
Самый простой способ - вывести разделитель переменных ({{), используя переменное выражение:
{{ "{{" }}
Для больших разделов имеет смысл отметить блок verbatim .
макрос
Макросы сопоставимы с функциями на обычных языках программирования. Они полезны для повторного использования часто используемых фрагментов HTML, чтобы не повторять себя.
{% if phone matches "/^[\\d\\.]+$/" %}
{% endif %}
Оператор сдерживания
Оператор in выполняет тест на герметичность.
Он возвращает true если левый операнд содержится справа:
{# returns true #}
{{ 1 in }}
{{ "cd" in "abcde" }}
Наконечник
Вы можете использовать этот фильтр для выполнения теста сдерживания на строках, массивах или объектах, реализующих интерфейс Traversable .
Чтобы выполнить отрицательный тест, используйте оператор not in операторе:
{% if 1 not in %}
{# is equivalent to #}
{% if not (1 in ) %}
Оператор тестирования
Оператор выполняет тесты. Тесты могут быть использованы для проверки переменной на общее выражение. Правильный операнд - это имя теста:
{# find out if a variable is odd #}
{{ name is odd }}
Тесты также могут принимать аргументы:
{% if post.status is constant("Post::PUBLISHED") %}
Тесты могут быть сведены на нет с помощью оператора is not:
{% if post.status is not constant("Post::PUBLISHED") %}
{# is equivalent to #}
{% if not (post.status is constant("Post::PUBLISHED")) %}
Изучая фреймворк Symfony, рано или поздно вы столкнетесь с таким понятием как шаблонизатор. Давайте сейчас будем разбираться с тем, что такое шаблонизатор и зачем он нужен.
В Symfony используется такой шаблонизатор, который называется Twig. На самом деле Twig - это не единственный шаблонизатор, который мы с вами можем использовать. Вы можете использовать любой другой шаблонизатор.
Но, по умолчанию, в Symfony используется именно шаблонизатор Twig.
Давайте будем разбираться, зачем нам нужен шаблонизатор и для каких целей он используется.
Если мы с вами вспомним модель MVC (модель - вид - контроллер), о которой мы с вами говорили несколько ранее, то шаблонизатор - это то, что относится к части "Вида".
Как вы помните, задача вида у нас представить данные, которые будут выданы по запросу пользователя. Точно также шаблонизатор. Его основная задача представить данные для отображения пользователю.
Файл шаблонизатора - это обычный текстовый файл. Для Twig этот файл имеет 2 расширения.
Это означает то, что этот файл у нас содержит HTML-разметку и во вторых этот файл является служебным файлом шаблонизатора Twig.
По сути, в этом файле у нас содержаться 2 части: обычный html-код с простыми html-тэгами, встроенные стили CSS, встроенный Javascript-код и.т.д.
В отличии от обычной html-страницы, дополнительно к разметке документа там также выводятся определенные данные, которые могли быть переданы в него из контроллера. С помощью специальных конструкций, эти данные встраиваются в исходный twig-файл.
Данные на сервере могут меняться и автоматически они также меняются в twig файле. Т.е. мы получили html-страницу, которая содержит какие-то данные с веб-сервера.
Кроме данных в twig файле могут находиться какие-то служебные функции, которые упрощают представление этих данных.
Т.е. шаблонизатор - это что-то вроде некого шаблона и в этот шаблон мы можем передавать некие переменные, которые зависят от состояния нашего сервера.
Поэтому, шаблонизатор и происходит от слова "шаблон". Там содержится какая-то шаблонная страница, шаблонный html-код и в него вставляются переменные данные.
Т.е. шаблонизатор - это что-то вроде службы, которая подготавливает html-страницу со всеми необходимыми данными, которые отражают состояние нашего веб-сервера и возвращают эти данные контроллеру.
А контроллер уже возвращает готовый html-код тому посетителю сайта. который его запросил.
Таким образом это работает. Надеюсь, что стало понятнее что такое шаблонизатор и для чего он нужен и теперь можно приступить к рассмотрению конкретных примеров по работе с этим инструментом.
Как правило, все шаблонизаторы похожи друг на друга и различаются только какими-то специфическими особенностями и деталями. Главная задача шаблонизаторов - разделить бизнес логику приложения и вывод данных на страницу, таким образом, позволив разработчикам и дизайнерам работать одновременно, не капая друг другу на мозги.
Многие PHP фрэймворки, включая: Zend Frameworkd, Agavi, CackPHP и CodeIgniter, по-своему реализуют разделение бизнес логики и вывод данных. Однако, если вы не любите фрэймворки или ваш проект слишком мал для их использования, то вы можете воспользоваться какой-то отдельной системой построения шаблонов. К счастью, нам есть из чего выбирать. Smartym Savant, Dwoo... этот список можно продолжать и продолжать, однако в этой статье я покажу вам, как работать с шаблонизатором Twig.
Установка
Существует множество способов установки Twig-a. Самый простой и быстрый - это скачивание компонента с GitHub , после чего архив необходимо распаковать, и перекинуть каталог lib в папку с нашим проектом.
Основы
Прежде чем приступить непосредственно к делу, давайте разберёмся с принципом работы шаблонизаторов. Обычное PHP приложение состоит из целого набора страниц, которые включают в себя как статический HTML код (меню, списки, изображения и т.д.), так и динамический контент (вывод данных из БД, xml файла, сервисы, …). С помощью Twig мы можем разделить данные процессы, создавая шаблоны со специальными маркерами, вместо которых в последствии будет вставляться динамический контент.
Значения для данных маркеров формируются в основном PHP скрипте; там же происходит общение с базой данных, xml парсинг и другие всевозможные операции. Таким образом, ваша страница будет строиться на основе 2х источников: шаблона с специальными вставками и PHP скриптов, где мы храним основной функционал. Это даёт возможность PHP разработчикам и дизайнерам одновременно работать над одними и теми же страницами.
Приступаем к делу
Для того чтобы посмотреть, как работает Twig, предлагаю рассмотреть простой пример:
Account successfully created!
Hello {{ name }}
Thank you for registering with us. Your account details are as follows:
Username: {{ username }}
Password: {{ password }}
You"ve already been logged in, so go on in and have some fun!
Сохраните данный файл templates/thanks.tmpl. Обратите внимание на то, что все маркеры, представляющие собой переменные, помещены в двойные фигурные скобки. Подобная запись подскажет Twig-у, где и как осуществлять вставку данных.
Затем, нам необходимо создать основной скрипт, где будет происходить формирование переменных и данных:
loadTemplate("thanks.tmpl");
// передаём в шаблон переменные и значения
// выводим сформированное содержание
echo $template->render(array("name" => "Clark Kent",
"username" => "ckent",
"password" => "krypt0n1te",));
} catch (Exception $e) {
die ("ERROR: " . $e->getMessage());
}
?>
В результате, если вы откроете данную страницу в браузере, то увидите следующее:
Для использования Twig-а, вам нужно пройти следующие шаги:
Инициализировать авто-загрузчик Twig-а, для того чтобы классы шаблонизатора подгружались автоматически.
Инициализировать загрузчик шаблонов. В нашем случае эт Twig_Loader_FileSystem. В качестве аргумента передаём путь к каталогу с шаблонами.
Создать объект самого Twig и передать ему уже сконфигурированные настройки.
Подгрузить нужный нам шаблон с помощью метода loadTemplate, передав в него название используемого шаблона. В качестве результата метод вернёт экземпляр шаблона.
Сформировать массив вида "ключ-значение", где ключи - это названия переменных, а значения - данные, выводимые в шаблоне. Затем этот массив нужно передать в метод render(), который совместит шаблон с переданными данными и вернёт сгенерированный результат.
Условия
Twig также предоставляет нам возможность создавать условные выражения ‘if-else-endif’. Пример:
Odd or Even
{% if div == 0 %}
{{ num }} is even.
{% else %}
{{ num }} is odd.
{% endif %}
В зависимости от числа, которое генерируется в основном PHP скрипте, шаблон отобразит одно из двух сообщений. Вот и скрипт, где генерируется число от 0 до 30 и проверяется на чётность:
loadTemplate("numbers.tmpl");
// генерируем случайное число
// и проверяем его на чётность
$num = rand (0,30);
$div = ($num % 2);
echo $template->render(array ("num" => $num,
"div" => $div));
} catch (Exception $e) {
die ("ERROR: " . $e->getMessage());
}
?>
а вот и результат:
Также мы можем сделать многоуровневые проверки ‘if-elseif-else-endif’. Пример:
Seasons
{% if month > 0 and month <= 3 %}
Spring is here, watch the flowers bloom!
{% elseif month > 3 and month <= 6 %}
Summer is here, time to hit the beach!
{% elseif month > 6 and month <= 9 %}
Autumn is here, watch the leaves slowly fall!
{% elseif month > 9 and month <= 12 %}
Winter is here, time to hit the slopes!
{% endif %}
А вот и скрипт, где мы генерируем номер месяца и передаём его в шаблон:
loadTemplate("seasons.tmpl");
// получаем номер месяца
$month = date("m", mktime());
echo $template->render(array ("month" => $month));
} catch (Exception $e) {
die ("ERROR: " . $e->getMessage());
}
?>
А вот и вывод:
Циклы
Twig также поддерживает цикл ‘for’. Он очень удобен, если нам необходимо пройтись по массиву. Пример:
Shopping list
{% for item in items %}
{{ item }}
{% endfor %}
В данном примере у нас простой не ассоциативный массив. На каждой итерации мы будем получать по одному элементу и выводить его в элементе списка. Вот и скрипт:
Для того чтобы пройтись по ассоциативному массиву, мы можем обращаться к ключам через “точку”. Пример:
"Harry Potter and the Deathly Hallows",
"author" => "J. K. Rowling",
"publisher" => "Scholastic",
"category" => "Children\"s fiction",
"pages" => "784");
include "Twig/Autoloader.php";
Twig_Autoloader::register();
try {
$loader = new Twig_Loader_Filesystem("templates");
$twig = new Twig_Environment($loader);
$template = $twig->loadTemplate("book.tmpl");
echo $template->render(array ("book" => $book));
} catch (Exception $e) {
die ("ERROR: " . $e->getMessage());
}
?>
Для того чтобы достучаться до значений массива в шаблоне, сначала пишем имя переменной, в которой хранится сам массив. Затем ставим точку и пишем название ключа, по которому достаём данные:
Book details
Title
{{ book.title }}
Author
{{ book.author }}
Publisher
{{ book.publisher }}
Pages
{{ book.pages }}
Category
{{ book.category }}
Результат:
Такой же подход может быть применён для работы с объектами.
Дамп данных
Безусловно циклы вам пригодиться при выводе данных из БД. Пример:
Countries and capitals
Country
Region
Population
Capital
Language
{% for d in data %}
{{ d.name|escape }}
{{ d.region|escape }}
{{ d.population|escape }}
{{ d.capital|escape }}
{{ d.language|escape }}
{% endfor %}
В следующем фрагменте кода я использую PDO подключение к MySQL базе данных ‘world’. Если вы хотите попробовать данный пример, то вам нужно сформировать базу самим:
getMessage();
}
// установка error режима
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
// выполняем запрос
try {
// формируем SELECT запрос
// в результате каждая строка таблицы будет объектом
$sql = "SELECT country.Code AS code, country.Name AS name, country.Region AS region, country.Population AS population, countrylanguage.Language AS language, city.Name AS capital FROM country, city, countrylanguage WHERE country.Code = city.CountryCode AND country.Capital = city.ID AND country.Code = countrylanguage.CountryCode AND countrylanguage.IsOfficial = "T" ORDER BY population DESC LIMIT 0,20";
$sth = $dbh->query($sql);
while ($row = $sth->fetchObject()) {
$data = $row;
}
// закрываем соединение
unset($dbh);
$loader = new Twig_Loader_Filesystem("templates");
$twig = new Twig_Environment($loader);
$template = $twig->loadTemplate("countries2.tmpl");
echo $template->render(array ("data" => $data));
} catch (Exception $e) {
die ("ERROR: " . $e->getMessage());
}
?>
Тут стоит отметить несколько вещей:
Мы используем метод getchObject(), который вернёт нам строки из таблицы в виде объектов. Названия полей будут соответствовать названиям колонок. Затем эти объекты мы помещаем в массив и передаём его в шаблон. В шаблоне, используем цикл и выводим данные.
В данном примере также используется встроенный в Twig фильтр `escape`. По умолчанию данный фильтр пользуется функцией htmlspecialchars() для фильтровки данных. Это неплохая защита от XSS атак.
Подгрузка шаблонов
Также в Twig-е есть ещё одна команда - `include`, которая позволяет подключать содержание других шаблонов. Это может пригодиться, когда вы захотите прикрепить к вашим файлам меню, заголовок или подвал.
Для демонстрации представьте, что данный код - это главный шаблон:
{% include "primary.tmpl" %}
{% include "secondary.tmpl" %}
This is the main page content. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Все секции данной страницы находятся в отдельных файлах и подключаются сюда с помощью команды `include`. Давайте посмотрим, как выглядят подключаемые файлы:
{% for item in nav.primary %}
{{ item.name|upper }}
{% endfor %}
{% for item in nav.secondary %}
{{ item.name }}
{% endfor %}
This page licensed under a Creative Commons License. Last updated on: {{ updated }}.
Обратите внимание, что нам не нужно загружать все шаблоны функцией loadTemplate. Главное подключить основной шаблон. Каждый мелкий под-шаблон загрузится автоматом. Переменные и значения, переданные в главный шаблон, будут доступны во всех подключаемых шаблонах.
Результат:
Фильтрация данных
В данной статье мы уже затронули тему фильтров. Давайте посмотрим, какие ещё возможности в данной сфере предоставляет нам Twig.
Давайте рассмотрим, к примеру, фильтр ‘date’. Данный фильтр даёт нам возможность формировать дату и время, используя нативные для PHP маркеры. Пример:
{{ "now"|date("d M Y h:i") }}
{{ "now"|date("d/m/y") }}
Результат:
Также вы можете воспользоваться фильтрами `upper`, `lower`, `capitalize`, `title` для контроля заглавных и прописных букв:
{{ "the cow jumped over the moon"|upper }}
{{ "the cow jumped over the moon"|capitalize }}
{{ "the cow jumped over the moon"|title }}
{{ "The Cow jumped over the Moon"|lower }}
Результат:
Фильтр `striptags` уберёт из текста все HTML и XML элементы:
{{ "
I said \"Go away!\"
"|striptags }}
Результат:
Фильтр `replace` позволяет быстро и просто заменять какие-то значения в строке на нужные нам. Пример:
{{ "I want a red boat"|replace({"red" : "yellow", "boat" : "sports car"}) }}
Результат:
Вы уже видели фильтр `escape` в действии. В Twig также есть фильтр, который делает абсолютно противоположное действие - `raw`. Его следует использовать только для html кода, который вы считаете 100% безопасным.
Escaped output: {{ html|escape }}
Raw output: {{ html|raw }}
Если же вам нужно применить `escape` к большому блоку кода, то вы можете воспользоваться синтаксисом `autoescape`, передав булево значение true/false для активации и дезактивации фильтрации `escape`. Пример:
{% autoescape true %}
Escaped output: {{ html }}
{% endautoescape %}
{% autoescape false %}
Raw output: {{ html }}
{% endautoescape %}
Теперь вы уже больше знаете о Twig-e и можете использовать условия, циклы и фильтры.
