Merge branch '4.2'

* 4.2:
  Added a note about PHP extension and Symfony Form types extension
  Update choice_label docs to match given examples
  Improved the Fragment Naming for Collections section
  [Form] Mention that form_theme _self only works with template inheritance
  Improved the explanation of the block_name form option
  [Diversity] Add Voting Logic Examples

Author: javiereguiluz

contributing/diversity/governance.rst

@@ -72,6 +72,23 @@ For an actionable item to pass, approval from greater than 50% of the voting
 guidance team members is required. Use or management of finances/donations
 require at least a two-thirds majority to pass.
 
+For transparency and ease-of-understanding, this means only the following
+combinations of votes will result in an actionable item passing:
+
++-----+---------+---------+
+| For | Against | Abstain |
++=====+=========+=========+
+| 5   | 0       | 0       |
++-----+---------+---------+
+| 4   | 1       | 0       |
++-----+---------+---------+
+| 3   | 2       | 0       |
++-----+---------+---------+
+| 4   | 0       | 1       |
++-----+---------+---------+
+| 3   | 1       | 1       |
++-----+---------+---------+
+
 Guidance Principles
 -------------------
 

form/create_custom_field_type.rst

@@ -16,8 +16,11 @@ Defining the Field Type
 In order to create the custom field type, first you have to create the class
 representing the field. In this situation the class holding the field type
 will be called ``ShippingType`` and the file will be stored in the default location
-for form fields, which is ``App\Form\Type``. Make sure the field extends
-:class:`Symfony\\Component\\Form\\AbstractType`::
+for form fields, which is ``App\Form\Type``.
+
+All field types must implement the :class:`Symfony\\Component\\Form\\FormTypeInterface`,
+but you should instead extend from :class:`Symfony\\Component\\Form\\AbstractType`,
+which already implements that interface and provides some utilities::
 
     // src/Form/Type/ShippingType.php
     namespace App\Form\Type;
@@ -53,8 +56,17 @@ for form fields, which is ``App\Form\Type``. Make sure the field extends
 Here, the return value of the ``getParent()`` function indicates that you're
 extending the ``ChoiceType`` field. This means that, by default, you inherit
 all of the logic and rendering of that field type. To see some of the logic,
-check out the `ChoiceType`_ class. There are three methods that are particularly
-important:
+check out the `ChoiceType`_ class.
+
+.. note::
+
+    The PHP class extension mechanism and the Symfony form field extension
+    mechanism are not the same. The parent type returned in ``getParent()`` is
+    what Symfony uses to build and manage the field type. Making the PHP class
+    extend from ``AbstractType`` is only a convenience way of implementing the
+    required ``FormTypeInterface``.
+
+There are three methods that are particularly important:
 
 .. _form-type-methods-explanation:
 

form/form_themes.rst

@@ -307,10 +307,66 @@ Fragment Naming for Collections
 ...............................
 
 When using a :doc:`collection of forms </form/form_collections>`, the fragment
-of each collection item follows the pattern ``_field-name_entry_part``. For
-example, if your form field is named ``tasks``, the fragment for each task will
-be named ``_tasks_entry`` (``_tasks_entry_row``, ``_tasks_entry_label``,
-``_tasks_entry_widget``, ``_tasks_entry_error``)
+of each collection item follows a predefined pattern. For example, consider the
+following complex example where a ``TaskManagerType`` has a collection of
+``TaskListType`` which in turn has a collection of ``TaskType``::
+
+    class TaskManagerType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options = array())
+        {
+            // ...
+            $builder->add('taskLists', CollectionType::class, array(
+                'entry_type' => TaskListType::class,
+                'block_name' => 'task_lists',
+            ));
+        }
+    }
+
+    class TaskListType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options = array())
+        {
+            // ...
+            $builder->add('tasks', CollectionType::class, array(
+                'entry_type' => TaskType::class,
+            ));
+        }
+    }
+
+    class TaskType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options = array())
+        {
+            $builder->add('name');
+            // ...
+        }
+    }
+
+Then you get all the following customizable blocks (where ``*`` can be replaced
+by ``row``, ``widget``, ``label``, or ``help``):
+
+.. code-block:: twig
+
+    {% block _task_manager_task_lists_* %}
+        {# the collection field of TaskManager #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_* %}
+        {# the inner TaskListType #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_tasks_* %}
+        {# the collection field of TaskListType #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_tasks_entry_* %}
+        {# the inner TaskType #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_tasks_entry_name_* %}
+        {# the field of TaskType #}
+    {% endblock %}
 
 Template Fragment Inheritance
 .............................
@@ -341,6 +397,8 @@ for any overridden form blocks:
 
 .. code-block:: html+twig
 
+    {% extends 'base.html.twig' %}
+
     {% form_theme form _self %}
 
     {# this overrides the widget of any field of type integer, but only in the
@@ -359,12 +417,16 @@ for any overridden form blocks:
         </div>
     {% endblock %}
 
-
     {# ... render the form ... #}
 
-The disadvantage of this method is that the customized form blocks can't be
-reused when rendering other forms in other templates. If that's what you need,
-create a form theme in a separate template as explained in the next section.
+The main disadvantage of this method is that it only works if your template
+extends another (``'base.html.twig'`` in the previous example). If your template
+does not, you must point ``form_theme`` to a separate template, as explained in
+the next section.
+
+Another disadvantage is that the customized form blocks can't be reused when
+rendering other forms in other templates. If that's what you need, create a form
+theme in a separate template as explained in the next section.
 
 Creating a Form Theme in a Separate Template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

reference/forms/types/options/block_name.rst.inc

@@ -4,6 +4,11 @@ block_name
 **type**: ``string`` **default**: the form's name (see :ref:`Knowing which
 block to customize <form-customization-sidebar>`)
 
-Allows you to 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 the forms individually.
+Allows you to add a custom block name to the ones used by default 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 the forms individually.
+
+If you set for example this option to ``my_custom_name`` and the field is of
+type ``text``, Symfony will use the following names (and in this order) to find
+the block used to render the widget of the field: ``_my_custom_name_widget``,
+``text_widget`` and ``form_widget``.

reference/forms/types/options/choice_label.rst.inc

@@ -16,8 +16,8 @@ more control::
             'no' => false,
             'maybe' => null,
         ],
-        'choice_label' => function ($choiceValue, $key, $value) {
-            if ($value == $choiceValue) {
+        'choice_label' => function ($value, $key, $choiceValue) {
+            if (true === $value) {
                 return 'Definitely!';
             }
 
@@ -28,9 +28,9 @@ more control::
         },
     ]);
 
-This method is called for *each* choice, passing you the choice ``$value`` and the
-``$key`` from the choices array (``$index`` is related to `choice_value`_). This
-will give you:
+This method is called for *each* choice, passing you the ``$value`` and 
+``$key`` from the choices array (additional ``$choiceValue`` is related to `choice_value`_). 
+This will give you:
 
 .. image:: /_images/reference/form/choice-example2.png
    :align: center