8000 minor #18191 [Form] Add some basic docs for Twig Form field helpers (… · symfony/symfony-docs@f47dced · GitHub
[go: up one dir, main page]
Skip to content

Commit f47dced

Browse files
javiereguiluzjaviereguiluz
committed
minor #18191 [Form] Add some basic docs for Twig Form field helpers (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
2 parents 1331fbb + 9e21175 commit f47dced

File tree

2 files changed

+49
-0
lines changed

2 files changed

+49
-0
lines changed

‎form/form_customization.rst

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,49 @@ control over how each form field is rendered, so you can fully customize them:
8787
Later in this article you can find the full reference of these Twig
8888
functions with more usage examples.
8989

90+
.. _reference-forms-twig-field-helpers:
91+
92+
Form Field Helpers
93+
------------------
94+
95+
The ``form_*()`` helpers render each part of the form field, including all its needed HTML elements. Most developers
96+
like this behavior, but some designers struggle with it, because it hides all the HTML in form themes which are not
97+
easy to manage by them.
98+
99+
That's why some Twig form helpers are available to render the value of each form field part without adding any
100+
HTML around it:
101+
102+
* ``field_name``
103+
* ``field_value``
104+
* ``field_label``
105+
* ``field_help``
106+
* ``field_errors``
107+
* ``field_choices`` (an iterator of the field choices; e.g. for ``<select>``)
108+
109+
When using these helpers, you must write all the HTML contents for all form fields, which some people prefer to better
110+
control the generated HTML without having to deal with form themes:
111+
112+
.. code-block:: html+twig
113+
114+
<input
115+
name="{{ field_name(form.username) }}"
116+
value="{{ field_value(form.username) }}"
117+
placeholder="{{ field_label(form.username) }}"
118+
class="form-control"
119+
/>
120+
121+
<select name="{{ field_name(form.country) }}" class="form-control">
122+
<option value="">{{ field_label(form.country) }}</option>
123+
124+
{% for label, value in field_choices(form.country) %}
125+
<option value="{{ value }}">{{ label }}</option>
126+
{% endfor %}
127+
</select>
128+
129+
.. versionadded:: 5.2
130+
131+
The ``field_*()`` helpers were introduced in Symfony 5.2.
132+
90133
Form Rendering Variables
91134
------------------------
92135

‎reference/twig_reference.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,12 @@ explained in the article about :doc:`customizing form rendering </form/form_cust
365365
* :ref:`form_help() <reference-forms-twig-help>`
366366
* :ref:`form_row() <reference-forms-twig-row>`
367367
* :ref:`form_rest() <reference-forms-twig-rest>`
368+
* :ref:`field_name() <reference-forms-twig-field-helpers>`
369+
* :ref:`field_value() <reference-forms-twig-field-helpers>`
370+
* :ref:`field_label() <reference-forms-twig-field-helpers>`
371+
* :ref:`field_help() <reference-forms-twig-field-helpers>`
372+
* :ref:`field_errors() <reference-forms-twig-field-helpers>`
373+
* :ref:`field_choices() <reference-forms-twig-field-helpers>`
368374

369375
.. _reference-twig-filters:
370376

0 commit comments

Comments
 (0)
0