add form_attr option doc

symfony · wouterj · Apr 8, 2021 · Mar 16, 2021 · Apr 8, 2021 · c8deb3d013d486e99016d0918cd125180dcac555
commit c8deb3d013d486e99016d0918cd125180dcac555
diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst
@@ -19,6 +19,7 @@ on all types for which ``FormType`` is the parent.
 |                           | - `error_bubbling`_                                                |
 |                           | - `error_mapping`_                                                 |
 |                           | - `extra_fields_message`_                                          |
+|                           | - `form_attr`_                                                     |
 |                           | - `help`_                                                          |
 |                           | - `help_attr`_                                                     |
 |                           | - `help_html`_                                                     |
@@ -116,6 +117,8 @@ The actual default value of this option depends on other field options:

 .. include:: /reference/forms/types/options/extra_fields_message.rst.inc

+.. include:: /reference/forms/types/options/form_attr.rst.inc
+
 .. include:: /reference/forms/types/options/help.rst.inc

 .. include:: /reference/forms/types/options/help_attr.rst.inc

diff --git a/reference/forms/types/options/form_attr.rst.inc b/reference/forms/types/options/form_attr.rst.inc
@@ -0,0 +1,20 @@
+``form_attr``
+~~~~~~~~~~~~~
+
+**type**: ``boolean`` or ``string`` **default**: ``false``
+
+When ``true`` and used on a form element, it adds a `"form" attribute`_ to its HTML field representation with
+its HTML form id. By doing this, a form element can be rendered outside the HTML form while still working as expected::
+
+    $builder->add('body', TextareaType::class, [
+        'form_attr' => true,
+    ]);
+
+This can be useful when you need to solve nested form problems.
+You can also set this to ``true`` on a root form to automatically set the "form" attribute on all its children.
+
+.. note::
+
+    When the root form has no ID, ``form_attr`` is required to be a string identifier to be used as the form ID.
+
+.. _`"form" attribute`: https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fae-form