Справочник функций и переменных форм шаблонов Twig

При работе с формами в шаблоне, в вашем распоряжении существуют две мощные вещи:

  • Функции для отображения каждой части формы;
  • Переменные для получения любой информации о любом поле.

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

Функции отображения формы

Этот справочник охватывает все доступные функции Twig для отображения форм. Существует несколько разных доступных функций и каждая отвечает за отображение разных частей формы (например, ярлыки, ошибки, виджеты и т.д.).

form(view, variables)

Отображает HTML полной формы.

1
2
{# отобразить форму и изменить метод отправки #}
{{ form(form, {'method': 'GET'}) }}

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

1
2
3
4
5
6
7
8
{{ form_start(form) }}
    {{ form_errors(form) }}

    {{ form_row(form.name) }}
    {{ form_row(form.dueDate) }}

    {{ form_row(form.submit, { 'label': 'Submit me' }) }}
{{ form_end(form) }}

form_start(view, variables)

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

1
2
{# отобразить стартовый тег и изменить метод отправки #}
{{ form_start(form, {'method': 'GET'}) }}

form_end(view, variables)

Отображает конечный тег формы.

1
{{ form_end(form) }}

Этот помощник также выводит form_rest(), разве что вы не установите render_rest, как "false":

1
2
{# не отображать неотображённые поля #}
{{ form_end(form, {'render_rest': false}) }}

form_label(view, label, variables)

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

1
2
3
4
5
6
7
8
9
{{ form_label(form.name) }}

{# Два следующих синтаксиса эквивалентны #}
{{ form_label(form.name, 'Your Name', {'label_attr': {'class': 'foo'}}) }}

{{ form_label(form.name, null, {
    'label': 'Your name',
    'label_attr': {'class': 'foo'}
}) }}

См. "Form Variables Reference", чтобы узнать об аргументе variables.

form_errors(view)

Отображает любые ошибки для заданного поля.

1
2
3
4
{{ form_errors(form.name) }}

{# отобразить любые "глобальные" ошибки #}
{{ form_errors(form) }}

form_widget(view, variables)

Отображает HTML-виджет заданного поля. Если вы примените это ко всей форме или коллекции полей, то будет отображён каждый лежащий в основе ряд формы.

1
2
{# отобразить виджет, но добавить к нему класс "foo" #}
{{ form_widget(form.name, {'attr': {'class': 'foo'}}) }}

Второй аргумент form_widget() - это массив переменных. Наиболее распространённой переменной является attr, которая есть массивом HTML-атрибутов, применяемых к HTML- виджету. В некоторых случаях, определённые типы также имеют другие опции, связанные с шаблонами, которые можно передать. Они обсуждаются от типа к типу. attributes не применяеются к дочерним полям рекурсивно, если вы одновременно отображаете много полей (например, form_widget(form)).

См. "Form Variables Reference", чтобы узнать больше об аргументе variables.

form_row(view, variables)

Отображает "ряд" заданного поля, который является комбинацией ярлыка, ошибок и виджета поля.

1
2
{# отобразить ряд поля, но отобразить ярлык с текстом "foo" #}
{{ form_row(form.name, {'label': 'foo'}) }}

Второй аргумент form_row() - это массив переменных. Шаблоны, предоставленные в Symfony позволяют только переопределить ярлык так, как показано в примере выше.

См. "Form Variables Reference", чтобы узнать больше об аргументе variables.

form_rest(view, variables)

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

1
{{ form_rest(form) }}

Справочник тестов форм

Тесты могут быть выполнены с использованием оператора is в Twig, чтобы создать условие. Прочтите документацию Twig, чтобы узнать больше.

selectedchoice(selected_value)

Этот тест проверит, равняется ли текущий выбор selected_value, или является ли текущий выбор массивом (когда selected_value - массив).

1
<option {% if choice is selectedchoice(value) %} selected="selected"{% endif %} ...>

Больше о переменных форм

Tip

Чтобы увидеть полный список переменных, см.: Form Variables Reference.

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

1
2
{# отобразить виджет, но добавить к нему класс "foo" #}
{{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}

Цель этих переменных - что они делают и откуда они берутся - может быть ясна не сразу, но они очень мощные. Каждый раз, когда вы отображаете часть вашей формы, блок, отображающий её, использует несколько переменных. По умолчанию, эти блоки живут внутри form_div_layout.html.twig.

Рассмотрите form_label в качестве примера:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{% block form_label %}
    {% if not compound %}
        {% set label_attr = label_attr|merge({'for': id}) %}
    {% endif %}

    {% if required %}
        {% set label_attr = label_attr|merge({
            'class': (label_attr.class|default('') ~ ' required')|trim
        }) %}
    {% endif %}

    {% if label is empty %}
        {% set label = name|humanize %}
    {% endif %}

    <label
        {% for attrname, attrvalue in label_attr -%}
            {{ attrname }}="{{ attrvalue }}"
        {%- endfor %}
    >
        {{ label|trans({}, translation_domain) }}
    </label>
{% endblock form_label %}

Этот блок использует несколько переменных: compound, label_attr, required, label, name и translation_domain. Эти переменные были сделаны доступными системой отображения форм. Но, что важнее, это переменные, которые вы можете переопределить вызвав form_label() (так как в этом примере вы отображаете ярлык).

Точные переменные доступные для переопределения зависят от того, какую часть формы вы хотите отобразить (например, ярлык или виджет), и какое поле вы отображаете (например,виджет choice имеет дополнительную опцию expanded). Если вы ознакомитесь и привыкнете к form_div_layout.html.twig, вы всегда сможете увидеть, какие опции у вас есть.

Tip

За кулисами, эти переменные доступны объекту FormView вашей формы, когда компонент вызывает buildView() и finishView() в каждом "узле" вашего дерева формы. Чтобы увидеть, какие переменные "просмотра" имеет конкретное поле, найдите исходный код поля формы (и его родительских полей) и посмотрите на две вышеописанные функции.

Note

Если вы одномоментно отображаете форму целиком (или целую встроенную формы), то аргумент variables будет применён только к самой форме, но не к её дочерям. Другими словами, следующее не будет передать атрибут класса "foo" всем дочерним полям формы:

1
2
{# **не** работает - переменные не рекурсивны #}
{{ form_widget(form, { 'attr': {'class': 'foo'} }) }}

Справочник переменных формы

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

Предполагая, что у вас в шаблоне есть переменная form, и вы хотите сослаться на переменные в поле name, получение доступа к переменным проходит с использованием публичного свойства vars объекта FormView:

  • Twig
    1
    2
    3
    4
    <label for="{{ form.name.vars.id }}"
        class="{{ form.name.vars.required ? 'required' : '' }}">
        {{ form.name.vars.label }}
    </label>
    
  • PHP
    1
    2
    3
    4
    <label for="<?php echo $view['form']->get('name')->vars['id'] ?>"
        class="<?php echo $view['form']->get('name')->vars['required'] ? 'required' : '' ?>">
        <?php echo $view['form']->get('name')->vars['label'] ?>
    </label>
    
Переменная Использование
form Текущий экземпляр FormView.
id HTML-атрибут id для отображения.
name Имя поля (например, title) - но не name HTML-атрибута, которое является full_name.
full_name name HTML-атрибута для отображения.
errors Массив любых ошибок, присоединённый к этому конкретному полю (например, form.title.errors). Заметьте, что вы не можете использовать form.errors, чтобы определить валидность формы, так как возвращаются только "глобальные" ошибки: некоторые индивидуальные поля могут иметь ошибки. Вместо этого используйте опцию valid.
submitted Возвращает true или false в зависимости от того, отправлена ли форма целиком
valid Возвращает true или false в зависимости от того, валидна ли форма целиком.
value Значение, которое будет использовано при отображении (чаще всего HTML-атрибут value).
disabled Если true, disabled="disabled" добавляется к полю.
required Если true, атрибут required добавляется к полю, чтобы активировать валидацию HTML5. Кроме того, к ярлыку добавляется класс required.
label Строка ярлыка, которая будет отображена.
multipart Если true, form_enctype отобразит enctype="multipart/form-data". Применяется только к корневому элементу формы.
attr Массив ключей-значений, который будет отображён как HTML-атрибуты поля.
label_attr Массив ключей-значений, который будет отображён как HTML-атрибуты ярлыка.
compound Является ли поле носителем группы дочерних полей (например, поля choice, которое насамом деле является группой чекбоксов.
block_prefixes Массив всех имён родительских типов.
translation_domain Домен переводов для этой формы.
cache_key Уникальный ключ, используемый для кеширования.
data Нормализованные данные типа.
method Метод текущей формы (POST, GET, и т.д.).
action Действие текущей формы.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.