Merge branch '5.4' into 6.0

* 5.4:
  [Form][Form Choice] customize choice entry

Author: javiereguiluz

reference/forms/types/choice.rst

@@ -309,5 +309,41 @@ Field Variables
 
 .. tip::
 
-    It's significantly faster to use the :ref:`selectedchoice <form-twig-selectedchoice>`
-    test instead when using Twig.
+    In Twig template, instead of using ``is_selected()``, it's significantly
+    faster to use the :ref:`selectedchoice <form-twig-selectedchoice>` test.
+
+Accessing Form Choice Data
+...........................
+
+The ``form.vars`` variable of each choice entry holds data such as whether the
+choice is selected or not. If you need to get the full list of choices data and
+values, use the ``choices`` variable from the parent form of the choice entry
+(which is the ``ChoiceType`` itself) with ``form.parent.vars.choices``::
+
+.. code-block:: html+twig
+
+    {# `true` or `false`, whether the current choice is selected as radio or checkbox #}
+    {{ form.vars.data }}
+
+    {# the current choice value (i.e a category name when `'choice_value' => 'name'` #}
+    {{ form.vars.value }}
+
+    {# a map of `ChoiceView` or `ChoiceGroupView` instances indexed by choice values or group names #}
+    {{ form.parent.vars.choices }}
+
+Following the same advanced example as above (where choices values are entities),
+the ``Category`` object is inside ``form.parent.vars.choices[key].data``::
+
+.. code-block:: html+twig
+
+    {% block _form_categories_entry_widget %}
+        {% set entity = form.parent.vars.choices[form.vars.value].data %}
+
+        <tr>
+            <td>{{ form_widget(form) }}</td>
+            <td>{{ form.vars.label }}</td>
+            <td>
+                {{ entity.name }} | {{ entity.group }}
+            </td>
+        </tr>
+    {% endblock %}