…tgalopin)

This PR was merged into the 5.2-dev branch.

Discussion
----------

[Form] Implement Twig helpers to get field variables

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | -
| License       | MIT
| Doc PR        | symfony/symfony-docs#14308

Designing Symfony Forms has always been difficult, especially for developers not comfortable with Symfony or Twig. The reason behind this difficulty is that the current `form_*` helper functions, while providing a way to quickly render a form, are hiding the generated HTML behind a notation specific to Symfony.

HTML standards introduced many new attributes since the Form component was created, from new constraints to how should inputs be displayed, treated by screen readers, etc.

I propose to introduce a series of new Twig functions to help create more flexible forms without the hurdle of having to use `form_*` functions. I called these methods `field_*` because they aim at rendering only the tiny bits of strings necessary to map forms to the Symfony backend.

The functions introduced are:

* `field_name` returns the name of the given field
* `field_value` returns the current value of the given field
* `field_label` returns the label of the given field, translated if possible
* `field_help` returns the help of the given field, translated if possible
* `field_errors` returns an iterator of strings for each of the errors of the given field
* `field_choices` returns an iterator of choices (the structure depending on whether the field uses or doesn't use optgroup) with translated labels if possible as keys and values as values

A quick example of usage of these functions could be the following:

``` twig
<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>

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

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

{% for error in field_errors(form.country) %}
    <div class="text-danger mb-2">
        {{ error }}
    </div>
{% endfor %}
```

There are several advantages to using these functions instead of their `form_*` equivalents:

* they are much easier to use for developers not knowing Symfony: they rely on native HTML with bits of logic inside, instead of relying on specific tools needing to be configured to display proper HTML
* they allow for better integration with CSS frameworks or Javascript libraries as adding a new HTML attribute is trivial (no need to look at the documentation)
* they are easier to use in contexts where one would like to customize the rendering of a input in details: having the label as placeholder, displaying a select empty field, ...

The `form_*` functions are still usable of course, but I'd argue this technique is actually easier to read and understand.

Commits
-------

3941d70 [Form] Implement Twig helpers to get field variables

…tgalopin)

This PR was merged into the 5.2-dev branch.

Discussion
----------

[Form] Implement Twig helpers to get field variables

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | -
| License       | MIT
| Doc PR        | symfony/symfony-docs#14308

Designing Symfony Forms has always been difficult, especially for developers not comfortable with Symfony or Twig. The reason behind this difficulty is that the current `form_*` helper functions, while providing a way to quickly render a form, are hiding the generated HTML behind a notation specific to Symfony.

HTML standards introduced many new attributes since the Form component was created, from new constraints to how should inputs be displayed, treated by screen readers, etc.

I propose to introduce a series of new Twig functions to help create more flexible forms without the hurdle of having to use `form_*` functions. I called these methods `field_*` because they aim at rendering only the tiny bits of strings necessary to map forms to the Symfony backend.

The functions introduced are:

* `field_name` returns the name of the given field
* `field_value` returns the current value of the given field
* `field_label` returns the label of the given field, translated if possible
* `field_help` returns the help of the given field, translated if possible
* `field_errors` returns an iterator of strings for each of the errors of the given field
* `field_choices` returns an iterator of choices (the structure depending on whether the field uses or doesn't use optgroup) with translated labels if possible as keys and values as values

A quick example of usage of these functions could be the following:

``` twig
<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>

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

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

{% for error in field_errors(form.country) %}
    <div class="text-danger mb-2">
        {{ error }}
    </div>
{% endfor %}
```

There are several advantages to using these functions instead of their `form_*` equivalents:

* they are much easier to use for developers not knowing Symfony: they rely on native HTML with bits of logic inside, instead of relying on specific tools needing to be configured to display proper HTML
* they allow for better integration with CSS frameworks or Javascript libraries as adding a new HTML attribute is trivial (no need to look at the documentation)
* they are easier to use in contexts where one would like to customize the rendering of a input in details: having the label as placeholder, displaying a select empty field, ...

The `form_*` functions are still usable of course, but I'd argue this technique is actually easier to read and understand.

Commits
-------

3941d70928 [Form] Implement Twig helpers to get field variables

…jmsche)

This PR was squashed before being merged into the 5.4 branch.

Discussion
----------

[Form] Add some basic docs for Twig Form field helpers

Closes #14308

Refers to the feature added in symfony/symfony#38307

Hi,

So these Twig helpers have been added for a long time now (2+ years) but unfortunately it's still undocumented.

As a "quick fix", I took the liberty to "steal" the text + example from the [related blog post](https://symfony.com/blog/new-in-symfony-5-2-form-field-helpers) so they will at least be referenced in the docs.

Commits
-------

9e21175 [Form] Add some basic docs for Twig Form field helpers