Як налаштувати відображення форми

Дата оновлення перекладу 2024-05-27

Як налаштувати відображення форми

Symfony надає вам широкий вибір способів налаштування відображення форми. У цьому керівництві ви дізнаєтеся, як налаштувати одне або декілька полів ваших форм. Якщо вам необхідно однаково налаштувати всі ваші форми, краще створіть тему форми або використайте будь-яку вбудовану тему, на кшталт теми Bootstrap для форм Symfony

Функції відображення форми

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

1
2
3
4
{# форма - це змінна, яка передається з контролера та створюється
  $this->render('...', ['form' => $form])
  або $this->render('...', ['form' => $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>

Caution

Якщо ви відображаєте кожне поле вручну, переконайтеся, що ви не забули поле _token, яке автоматично додається для CSRF-захисту.

Ви також можете використовувати {{ form_rest(form) }} (рекомендовано) для відображення будь-яких полів, які не відображуються вручну. Див. документацію form_rest() нижче, щоб дізнатися більше.

Note

Пізніше в цій статті ви можете знайти повний довідник цих функцій Twig з прикладами використання.

Помічники полів форми

Помічники form_*(), показані у попередньому розділі, відображають різні частини поля форми, включно з усіма його HTML-елементами. Деякі розробники та дизайнери борються з такою поведінкою, тому що вона приховує всі HTML-елементи у темах форми, які не є простими для налаштування.

Ось чому Symfony надає інші помічники для форм Twig, які відображають значення кожної частини поля форми без додавання будь-якого HTML навколо нього:

  • field_name()
  • field_value()
  • field_label()
  • field_help()
  • field_errors()
  • field_choices() (ітератор для полів вибору; наприклад, для <select>)

При використанні цих помічників ви повинні написати весь HTML-зміст для всіх полів порми, щоб вам більше не треба було розбиратися з темами форми:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<input
    name="{{ field_name(form.username) }}"
    value="{{ field_value(form.username) }}"
    placeholder="{{ field_label(form.username) }}"
    class="form-control"
>

<select name="{{ field_name(form.country) }}" class="form-control">
    <option value="">{{ field_label(form.country) }}</option>

    {% for label, value in field_choices(form.country) %}
        <option value="{{ value }}">{{ label }}</option>
    {% endfor %}
</select>

Змінні відображення форми

Деякі з функцій 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), використовуючи властивість vars. Наприклад, щоб отримати id:

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

Note

Пізніше у цій статті ви можете знайти повний довідник цих функцій Twig з прикладами використання.

Теми форми

Функції та змінні 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'}
}) }}

Див. "Довідник функцій та змінних форм шаблонів Twig", щоб дізнатися про аргумент variables.

form_help(form_view)

Відображає текст допомоги для заданого поля.

1
{{ form_help(form.name) }}

form_errors(form_view)

Відображає будь-які помилки для заданого поля.

1
2
3
4
5
{# відобразити лише повідомлення про помилки, пов'язані з цим полем #}
{{ form_errors(form.name) }}

{# відобразити будь-які "глобальні" помилки, не пов'язані ні з яким полем форми #}
{{ form_errors(form) }}

Caution

У темі форми Bootstrap 4, form_errors() вже включено у form_label(). Прочитайте більше про це у документації теми Bootstrap 4 .

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)).

Див. "Довідник функцій та змінних форм шаблонів Twig", щоб дізнатися більше про аргумент variables.

form_row(form_view, variables)

Відображає "рядок" заданого поля, який є комбінацією ярлику, помилок, допомоги та віджету поля.

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

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

Див. "Довідник функцій та змінних форм шаблонів Twig", щоб дізнатися про аргумент 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 ????? ????-???? ???????, ???'?????? ? ??? ?????????? ????? (?????????, 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 вашої форми, коли компонент Form викликає buildView() та finishView() на кожному "вузлі" вашого дерева форми. Щоб побачити, які змінні "перегляду" має конкретне поле, знайдіть початковий код поля форми (та його батьківські поля), та пошукайте дві функції, написані вище.