Twig для разработчиков шаблонов

 

 

Краткий обзор

 

Шаблон - это просто текстовый файл. Он может генерировать любой текстовый формат (HTML, XML, CSV, Latex, и т.д.). Он не обязан иметь особого расширения, .html, или .xml расширения подойдут.

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

 

 

Интеграция со средами разработки

 

Многие среды разработки поддерживают подсветку синтаксиса и автодополнение для TWIG

 

 

 

 

Переменные

 

Приложение передает переменные, с которыми вы можете работать в шаблоне. Переменные могут иметь атрибуты или элементы, к которым вы можете иметь доступ. Как выглядит переменная определяется приложением, которое ее предоставило. Вы можете использовать точку (.) чтобы получить доступ к аттрибутам переменной (методы или свойства PHP-объекта или элементы PHP-массива), или так называемый индекс ([]):

 

{{ foo.bar }}
{{ foo['bar'] }}

 

 

Когда атрибут содержит специальные символы, используйте функцию attribute вместо доступа к атрибуту переменной

{# equivalent to the non-working foo.data-foo #}
{{ attribute(foo, 'data-foo') }}

 

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

 

Если переменная или атрибут не существует, вы получите значение null , когда опция strict_variables установлена false, в обратном случае Twig выбросит ошибку.

 

Реализация

Для удобства foo.bar делает следующие вещи на уровне PHP:

  • проверяет является ли foo массивом и bar верным выражением;
  • если нет, и foo является объектом, проверяется что bar является допустимым свойством
  • если нет, и foo является объектом, проверяется что bar является допустимым методом (даже если bar является конструктором - используйте use __construct() вместо этого)
  • если нет, и foo является объектом, проверяется что getBar является допустимым методом
  • если нет, и foo является объектом, проверяется что isBar является допустимым методом
  • если нет, то возвращает значение null

С другой стороны, foo['bar'] работает только с массивами PHP:

  • проверяется, является ли foo массивом и bar допустимым элементом
  • если нет , то возвращает значение null
Если вы хотите получить динамический атрибут для переменной, используйте функцию attribute вместо этого.

 

 

Глобальные переменные

 

Следующие переменные всегда доступны в шаблонах:

  • _self: ссылается на текущий шаблон;
  • _context: ссылается на текущий контекст;
  • _charset: ссылается на текущую кодировку.

 

 

Присвоение переменных

 

Вы можете придать значения переменных внутри блоков кода. Присвоения используют тег set :

 

{% set foo = 'foo' %}
{% set foo = [1, 2] %}
{% set foo = {'foo': 'bar'} %}

 

 

Фильтры

 

Переменные могут быть изменены с помощью фильтров filters. Фильтры отделяются от переменных с помощью pipe-символа (|) и могут иметь дополнительные аргументы в скобках. Можно объединять несколько фильтров. Выход одного фильтра направляется в следующий.

 

Следующий пример удаляет все HTML-теги и title из name:

 

{{ name|striptags|title }}

 

 

Фильтры, которые принимают аргументы,имеют круглые скобки вокруг аргументов. Этот пример присоединит список, разделенный запятой

 

{{ list|join(', ') }}

 

 

Чтобы применить фильтр для секции в коде, оберните его с тегом filter:

 

{% filter upper %}
    This text becomes uppercase
{% endfilter %}

 

Чтобы узнать больше о встроенных фильтрах зайдите на страницу Фильтры.

 

 

Функции

 

Можно вызывать функции чтобы генерировать контент. Функции могут быть вызваны по имени со скобками после него и могут иметь аргументы.

Например, функция range возвращает список, содержащий арифметическую прогрессию целых чисел:

 

{% for i in range(0, 3) %}
    {{ i }},
{% endfor %}

 

Чтобы узнать больше о встроенных функциях зайдите на страницу Функции.

 

 

Именованные аргументы

 

Поддержка для именованных аргументов была добавлена в Twig 1.12.

 

{% for i in range(low=1, high=10, step=2) %}
    {{ i }},
{% endfor %}

 

Использование именованных аргументов помогает понять значение переменных, которые вы передаете как аргументы.

 

{{ data|convert_encoding('UTF-8', 'iso-2022-jp') }}

{# versus #}

{{ data|convert_encoding(from='iso-2022-jp', to='UTF-8') }}

 

 

Именованные аргументы также позволяют пропустить некоторые аргументы, для которых вы не хотите изменять значение по умолчанию:

 

{# the first argument is the date format, which defaults to the global date format if null is passed #}
{{ "now"|date(null, "Europe/Paris") }}

{# or skip the format value by using a named argument for the timezone #}
{{ "now"|date(timezone="Europe/Paris") }}

 

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

 

{{ "now"|date("d/m/Y H:i", timezone="Europe/Paris") }}
Каждая страница документации по функциям и фильтрам имеет раздел, где имена всех аргументов выписаны, если они поддерживаются.

 

 

Управляющая структура

Управляющая структура относится к тем вещам, которые управляют программой - условия (i.e. if/elseif/else), for-циклы и блоки. Управляющая структура появляется внутри блоков {% ... %}.

Например, чтобы показать список всех пользователей, которые записаны в переменной users , используйте тег for:

{% for user in users %}
{{ user.username|e }}
{% endfor %}

 

Тег if можно использовать чтобы проверить выражение:

 

{% if users|length > 0 %}
{% for user in users %}
{{ user.username|e }}
{% endfor %}
{% endif %}

 

Чтобы узнать больше о встроенных тегах зайдите на страницу Теги.

 

 

Комментарии

 

Чтобы закомментировать часть строки шаблона, используйте комментарий {# ... #}. Это полезно для отладки или для добавления информации для других разработчиков или для себя:

 

{# пометка: шаблон отключен потому что более не используется
    {% for user in users %}
        ...
    {% endfor %}
#}

 

 

Включение других шаблонов

 

Тэг include используется для включения шаблона и включению использованного контента к текущему:

 

{% include 'sidebar.html' %}

 

 

По умолчанию, включенные шаблоны передаются в текущий контекст.

Контекст, который передается во включенный шаблон включает переменные, определенные в шаблоне:

 

{% for box in boxes %}
    {% include "render_box.html" %}
{% endfor %}

 

Включенный шаблон render_box.html может получить доступ к box.

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

 

{% include "sections/articles/sidebar.html" %}

 

Это поведение зависит от приложения, в которое встраивается Twig.

 

 

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

 

Наиболее мощное средство Twig это наследование шаблонов. Оно позволяет вам построить базовый “скелет” шаблона,который содержит все общие элементы вашего сайта и определяет блоки, которые дочерние шаблоны могут замещать.

Звучит сложно, но на самом деле все очень просто. Это легко понять с помощью следующего примера.

Давайте определим базовый шаблон, base.html, который определяет простой HTML скелетный документ, который вы можете использовать для простой страницы с двумя колонками:

 

;
{% block head %}{% block title %}{% endblock %} - My Webpage {% endblock %}

{% block content %}{% endblock %}

{% block footer %} © Copyright 2017{% endblock %}

 

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

Шаблон-ребенок может выглядеть так:

 

{% extends "base.html" %}

{% block title %}Index{% endblock %}
{% block head %}
    {{ parent() }}
{% endblock %}
{% block content %}
    

 

 

Экранирование HTML

 

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

Twig поддерживает оба, автоматическое сохранение включено по умолчанию.

 

Автоматическое сохранение поддерживается только если расширение escaper включено (что так и есть по умолчанию).

 

 

Работа с экранированием вручную

 

Если сохранение вручную включено, это ваша обязанность сохранить все переменные если это нужно. Что нужно сохранить? Все переменные, которым вы не доверяете.

Сохранение работает , если пропустить переменную через escape или фильтр:

 

{{ user.username|e }}

 

По умолчанию, фильтр escape использует html метод, но в зависимости от сохраняемого контекста, вы возможно захотите использовать другие методы:

 

{{ user.username|e('js') }}
{{ user.username|e('css') }}
{{ user.username|e('url') }}
{{ user.username|e('html_attr') }}

 

 

 

Автоматическое экранирование

 

Вне зависимости от того, включено ли автоматическое сохранение или нет, вы можете выделить секцию шаблона, которую нужно или не нужно сохранить, используя тег 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 игнорировать те части, которые в противном случае он воспримет как переменные или как блоки.

Например, если синтаксис по умолчанию используется, и вы хотите использовать {{ качестве исходной строки в шаблоне, а не начинать переменную ,вы должны использовать трюк.

Самым простым способом для вывода переменной разделитель ({{) является использование выражения:

 

{{ '{{' }}

 

 

Макросы

 

поддержка значений аргументов была добавлена по умолчанию в Twig 1.12.

 

Макросы сравнимы с функциями в обычных языках программирования. Они полезны для повторного использования часто используемых HTML - фрагментов, чтобы не повторять себя. Макрос определяется через macro теги. Вот небольшой пример (впоследствии называемый forms.html) макроса, который представлен в виде элемента формы:

 

{% macro input(name, value, type, size) %}
    
{% endmacro %}

 

 

Макрос может быть определен в любом шаблоне, и должен быть "импортирован" через тег import до использования:

 

{% import "forms.html" as forms %}
{{ forms.input('username') }}

 

 

Кроме того, вы можете импортировать отдельные имена макросов из шаблона в текущее пространство имен, с помощью тега from или дать им имя:

 

{% from 'forms.html' import input as input_field %}
Username
{{ input_field('username') }}
Password
{{ input_field('password', '', 'password') }}

 

 

По умолчанию, значение также может быть определено для макро аргументов прямо в вызове макроса:

 

{% macro input(name, value = "", type = "text", size = 20) %}
    
{% endmacro %}

 

 

Макросы

 

Приоритет операторов выглядит следующим образом, начиная с самых низко-приоритетных операторов:b-and, b-xor, b-or, or, and, ==,!=, <, >, >=, <=, in, matches, starts with, ends with, .., +, -, ~, *, /, //, %, is, **, |, [], and .:
{% set greeting = 'Hello' %}
{% set name = 'Fabien' %}

{{ greeting ~ name|lower }}   {# Hello fabien #}

{# use parenthesis to change precedence #}
{{ (greeting ~ name)|lower }} {# hello fabien #}

 

 

Литеры

 

Самой простой формой выражений являются литералы. Литералы представлены для таких типов PHP, как строки, числа и массивы. Существуют следующие литералы:

 

  • "Hello World" : Все между двумя двойными или одинарными кавычками является строкой. Они полезны, когда вам нужна строка в шаблоне (например, как аргументы функций, фильтры или для того чтобы просто расширить или включить шаблон). Строка может содержать разделитель, если ему предшествует обратный слеш () -- как в 'It's good'
  • 42 / 42,23: Целые числа и числа с плавающей точкой создаются написанием чисел . Если точка есть в числе то это float, в противном случае integer.
  • ["foo", "bar"]: Массивы определяются последовательностью выражений, разделенных запятыми (,) и окруженных квадратными скобками ([]).
  • {"foo": "bar"}: Хэши определяется списком ключей и значений, разделенных запятыми (,) и взятых в фигурные скобки ({}):

     

    {# keys as string #}
    { 'foo': 'foo', 'bar': 'bar' }
    
    {# keys as names (equivalent to the previous hash) -- as of Twig 1.5 #}
    { foo: 'foo', bar: 'bar' }
    
    {# keys as integer #}
    { 2: 'foo', 4: 'bar' }
    
    {# keys as expressions (the expression must be enclosed into parentheses) -- as of Twig 1.5 #}
    { (1 + 1): 'foo', (a ~ 'b'): 'bar' }	

     

  • true/false: true представляет истинное значение, false представляет ложное значение.
  • null: null не представляет никакого определенного значения. Это значение возвращается, когда переменной не существует. none является синонимом null.

 

Массивы и хэши могут быть вложенными:

 

{% set foo = [1, {"foo": "bar"}] %}

 

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

 

 

Вычисления

 

Twig позволяет оперировать значениями. Это редко используется в шаблонах, но существует ради полноты. Поддерживаются следующие операторы:

 

  • +: Добавляет два объекта вместе (операнды преобразованы в числа). {{1 + 1}} равно 2.
  • -: Вычитает второе число из первого. {{3 - 2}} равно 1.
  • /: Деление двух чисел. Возвращенное значение будет числом с плавающей точкой. {{1/2}} есть {{0,5}}.
  • %: Вычисляет остаток от целочисленного деления. {{11% 7}} есть 4.
  • / /: Деление двух чисел и возвращает (в виде дроби) целый результат. {{20 / / 7}} = 2, {{-20 / / 7}} является `` -3 ``
  • *: Умножает левый операнд на правый. {{2 * 2}} возвратится 4.
  • **: Генерирует левый операнд в степень правого операнда. {{2 ** 3}} возвратится 8.

 

 

Логика

 

Вы можете объединить несколько выражений со следующими операторами:

 

  • and: Возвращает истину, если левый и правый операнды оба истинны.
  • or: Возвращает истину, если левый или правый операнд истинны.
  • not: Отрицает выражение.
  • (expr): Свертывает выражение.
Twig также поддерживает побитовые операторы (b-and, b-xor, and b-or).

 

 

Сравнения

 

Следующие операторы сравнения поддерживаются в любом выражении: ==, !=, <,>,> = и <=.

Вы также можете проверить, если строка начинается или заканчивается другой строкой:

 

{% if 'Fabien' starts with 'F' %}
{% endif %}

{% if 'Fabien' ends with 'n' %}
{% endif %}

 

Для сложных сравнений строк, оператор matches позволяет вам использовать обычные выражения:
{% if phone matches '{^[d.]+$}' %}
{% endif %}

 

 

Оператор содержания

 

Оператор in осуществляет проверку содержания.

Он возвращает true если левый операнд содержится в правом:

 

{# returns true #}

{{ 1 in [1, 2, 3] }}

{{ 'cd' in 'abcde' }}

 

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

 

Чтобы выполнить проверку на то, что левый операнд не содержится в правом, нужно использовать not in оператор

 

{% if 1 not in [1, 2, 3] %}

{# is equivalent to #}
{% if not (1 in [1, 2, 3]) %}

 

 

 

Операторы проверки

 

Оператор is выполняет тесты. Тесты могут быть использованы для тестирования переменной в отношении общего выражения. Правый операнд является именем теста:

 

{# 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')) %}

 

 

 

Другие операторы

 

Поддержка расширенного тройного оператора была добавлена в Twig 1.12.0.

 

Следующие операторы очень полезны, но не вписываются ни в какую из категорий:

  • ..: Создает последовательность, основанную на операнде до и после оператора.
  • |: Применяет фильтр.
  • ~: Преобразует все операнды в строки и объединяет их. Hello ! вернется (при условии, имя является «John») Hello John!.
  • ., []: Получает атрибут объекта.
  • ? :: Тройной оператор:

 

 

Строка интерполяции

 

Строка интерполяции была добавлена в Twig 1.5.

 

Строка интерполяция (#{expression}) позволяет любому допустимому выражению появляться в двойных кавычках. Результатом вычисления является то что вставляется в строку:

 

{{ "foo #{bar} baz" }}
{{ "foo #{1 + 2} baz" }}

 

 

Управление пробелами

 

Контроль пробелов уровней тегов был добавлен в Twig 1.1.

 

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

Используйте теги spaceless чтобы удалить пробелы между HTML-тегами:

{% spaceless %}
foo bar
{% endspaceless %} {# output will be
foo bar#}
    

 

 

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

 

{% set value = 'no spaces' %}
{#- No leading/trailing whitespace -#}
{%- if true -%}
    {{- value -}}
{%- endif -%}
{# output 'no spaces' #}

 

 

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

 

{% set value = 'no spaces' %}
{{- value }}
{# outputs ' no spaces' #}	

подписаться на рассылку

Я согласен на обработку моих данных

© Компания “Edgestile” 2004-2018 г.

Политика конфинденциальности