minor #18191 [Form] Add some basic docs for Twig Form field helpers (jmsche)

javiereguiluz · javiereguiluz · commit f47dcedb3ecd · 2023-05-04T15:28:49.000+02:00
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
diff --git a/form/form_customization.rst b/form/form_customization.rst
@@ -87,6 +87,49 @@ control over how each form field is rendered, so you can fully customize them:
     Later in this article you can find the full reference of these Twig
     functions with more usage examples.
 
+.. _reference-forms-twig-field-helpers:
+
+Form Field Helpers
+------------------
+
+The ``form_*()`` helpers render each part of the form field, including all its needed HTML elements. Most developers
+like this behavior, but some designers struggle with it, because it hides all the HTML in form themes which are not
+easy to manage by them.
+
+That's why some Twig form helpers are available to render the value of each form field part without adding any
+HTML around it:
+
+* ``field_name``
+* ``field_value``
+* ``field_label``
+* ``field_help``
+* ``field_errors``
+* ``field_choices`` (an iterator of the field choices; e.g. for ``<select>``)
+
+When using these helpers, you must write all the HTML contents for all form fields, which some people prefer to better
+control the generated HTML without having to deal with form themes:
+
+.. code-block:: html+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>
+
+.. versionadded:: 5.2
+
+    The ``field_*()`` helpers were introduced in Symfony 5.2.
+
 Form Rendering Variables
 ------------------------
 
diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst
@@ -365,6 +365,12 @@ explained in the article about :doc:`customizing form rendering </form/form_cust
 * :ref:`form_help() <reference-forms-twig-help>`
 * :ref:`form_row() <reference-forms-twig-row>`
 * :ref:`form_rest() <reference-forms-twig-rest>`
+* :ref:`field_name() <reference-forms-twig-field-helpers>`
+* :ref:`field_value() <reference-forms-twig-field-helpers>`
+* :ref:`field_label() <reference-forms-twig-field-helpers>`
+* :ref:`field_help() <reference-forms-twig-field-helpers>`
+* :ref:`field_errors() <reference-forms-twig-field-helpers>`
+* :ref:`field_choices() <reference-forms-twig-field-helpers>`
 
 .. _reference-twig-filters:
 
