Дата обновления перевода: 2021-05-31

Как настроить отображение формы

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

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

Одного вызова функции Twig form() достаточно для того, чтобы отобразить целую форму, включая все ее поля и сообщения об ошибках:

1
2
3
{# форма - это переменная, которая передается из контроллера и создается
  путем вызова метода $form->createView() #}
{{ form(form) }}

Следующий шаг - использовать функции Twig form_start(), form_end(), form_errors() и form_row() для отображения разных частей формы, чтобы вы могли настроить их, добавляя HTML элементы и атрибуты:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{{ form_start(form) }}
    <div class="my-custom-class-for-errors">
        {{ form_errors(form) }}
    </div>

    <div class="row">
        <div class="col">
            {{ form_row(form.task) }}
        </div>
        <div class="col" id="some-custom-id">
            {{ form_row(form.dueDate) }}
        </div>
    </div>
{{ form_end(form) }}

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

Функции Twig form_label(), form_widget(), form_help() и form_errors() дают вам полный контроль над тем, как отображается каждое поле формы, поэтому вы можете полностью их настроить:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<div class="form-control">
    <i class="fa fa-calendar"></i> {{ form_label(form.dueDate) }}
    {{ form_widget(form.dueDate) }}

    <small>{{ form_help(form.dueDate) }}</small>

    <div class="form-error">
        {{ form_errors(form.dueDate) }}
    </div>
</div>

Note

Позже в этой статье вы можете найти полный справочник этих функций Twig c примерами использования.

Переменные отображения формы

Некоторые из функций Twig, упомянутые в предыдущем разделе, позволяют передавать переменные для конфигурации их поведения. К примеру, функция form_label() позволяет вам определять пользовательский ярлык для переопределения того, который определен в форме:

1
{{ form_label(form.task, 'My Custom Task Label') }}

Некоторые типы полей форм имеют дополнительные опции отображения, которые можно передать виджету. Эти опции задокументированы для каждого типа, но одной общей опцией является attr, которая позволяет вам изменять атрибуты HTML в элементе формы. Следующее добавит CSS-класс task_field к отображенному полю ввода текста:

1
{{ form_widget(form.task, {'attr': {'class': 'task_field'}}) }}

Note

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

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

Если вам нужно отобразить поля формы “вручную”, вы можете получить доступ к отдельным значениям полей (например, id, name и label), используя ее свойство using vars. Например, чтобы получить id:

1
{{ form.task.vars.id }}

Note

Позже в этой статье вы можете найти полный справочник этих функций Twig c примерами использования.

Темы формы

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

Если вы хотите настроить все формы одинаково (например, чтобы адаптировать сгенерированный HTML-код к CSS-фреймворку, используемому в вашем приложении), вы должны создать тему формы.

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

Функции

form(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(form_view, variables)

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

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

form_end(form_view, variables)

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

1
{{ form_end(form) }}

Этот помощний также выводит form_rest() (что объясняется позже в этой статье), кроме случаев, когда вы устанавливаете render_rest как false:

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

form_label(form_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_help(form_view)

Отображает текст помощи для заданного поля.

1
{{ form_help(form.name) }}

form_errors(form_view)

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

1
2
3
4
5
{# отобразить только сообщения об ошибках, cвязанных с этим полем #}
{{ form_errors(form.name) }}

{# отобразить любые "глобальные" ошибки, н связанные ни с каким полем формы #}
{{ form_errors(form) }}

Caution

В теме формы Bootstrap 4, form_errors() уже включен в form_label(), см. “reference-forms-bootstrap-error-messages

form_widget(form_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(form_view, variables)

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

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

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

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

form_rest(form_view, variables)

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

1
{{ form_rest(form) }}

form_parent(form_view)

Возвращает просмотр родительской формы или null, если просмотр формы уже является начальной формой. Исползование этой функции должно быть в приоритете над доступом к родительской форме с использованием form.parent. Последнее будет производить разные результаты, если дочерняя форма называется parent.

Тесты

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

selectedchoice(selected_value)

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

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

rootform

Этот тест проверит, имеет ли текущий form родительский просмотр формы.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
 {# НЕ ДЕЛАЙТЕ ТАК: эта простая проверка не видит различий между формой,
    имеющей родительский просмотр формы, и формой, определяющей встроенное
    поле формы под названием 'parent' #}

 {% if form.parent is null %}
     {{ form_errors(form) }}
 {% endif %}

{# ДЕЛАЙТЕ ТАК: на эту проверку всегда можно положиться, даже если форма определяет
   поле под названием 'parent' #}

 {% if form is rootform %}
     {{ form_errors(form) }}
 {% endif %}

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

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

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

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

Tip

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

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