Documenting the block_prefix option

yceruto · yceruto · commit 417885e5cf2d · 2019-01-03T10:05:16.000-05:00
diff --git a/form/create_custom_field_type.rst b/form/create_custom_field_type.rst
@@ -87,6 +87,12 @@ The goal of this field was to extend the choice type to enable selection of the
 shipping type. This is achieved by fixing the ``choices`` to a list of available
 shipping options.
 
+.. tip::
+
+    If the purpose of this new form type was to customize the rendering of some
+    fields only, skip this step and use ``block_name`` or ``block_prefix`` option
+    instead. For more information, see :ref:`form-customization-form-themes`.
+
 Creating a Template for the Field
 ---------------------------------
 
diff --git a/form/form_customization.rst b/form/form_customization.rst
@@ -735,6 +735,35 @@ class to the ``div`` element around each row:
         </div>
     {% endblock form_row %}
 
+.. tip::
+
+    If you want to customize some instances of the same form only (without
+    the need to create a new form type) you can set the ``block_prefix``
+    option in your form type::
+
+        use Symfony\Component\Form\Extension\Core\Type\TextType;
+        use Symfony\Component\Form\FormBuilderInterface;
+
+        public function buildForm(FormBuilderInterface $builder, array $options)
+        {
+            $builder->add('name', TextType::class, array(
+                'block_prefix' => 'wrapped_text',
+            ));
+        }
+
+    .. versionadded:: 4.3
+        The ``block_prefix`` option was introduced in Symfony 4.3.
+
+    Then the block name will be ``wrapped_text_row``.
+
+    .. code-block:: html+twig
+
+        {% block wrapped_text_row %}
+            <div class="wrapped">
+                {{ form_row(form) }}
+            </div>
+        {% endblock wrapped_text_row %}
+
 .. tip::
 
     See :ref:`form-theming-methods` for how to apply this customization.
diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst
@@ -37,6 +37,7 @@ on all types for which ``FormType`` is the parent.
 | Inherited | - `attr`_                                                          |
 | options   | - `auto_initialize`_                                               |
 |           | - `block_name`_                                                    |
+|           | - `block_prefix`_                                                  |
 |           | - `disabled`_                                                      |
 |           | - `label`_                                                         |
 |           | - `translation_domain`_                                            |
@@ -154,6 +155,8 @@ of the form type tree (i.e. it cannot be used as a form type on its own).
 
 .. include:: /reference/forms/types/options/block_name.rst.inc
 
+.. include:: /reference/forms/types/options/block_prefix.rst.inc
+
 .. include:: /reference/forms/types/options/disabled.rst.inc
 
 .. include:: /reference/forms/types/options/label.rst.inc
diff --git a/reference/forms/types/options/block_prefix.rst.inc b/reference/forms/types/options/block_prefix.rst.inc
@@ -0,0 +1,13 @@
+block_prefix
+~~~~~~~~~~~~
+
+**type**: ``string`` or ``null`` **default**: ``null`` (see :ref:`Knowing which
+block to customize <form-customization-sidebar>`)
+
+.. versionadded:: 4.3
+    The ``block_prefix`` option was introduced in Symfony 4.3.
+
+Allows you to add a custom block prefix and override the block name
+used to render the form type. Useful for example if you have multiple
+instances of the same form and you need to personalize the rendering
+of all of them without the need to create a new form type.
