[WIP] Update form choice type reference (refs #5179)

reference/forms/types/choice.rst

@@ -15,10 +15,17 @@ option.
 +-------------+------------------------------------------------------------------------------+
 | Options     | - `choices`_                                                                 |
 |             | - `choice_list`_                                                             |
+|             | - `choice_loader`_                                                           |
+|             | - `choice_label`_                                                            |
+|             | - `choice_name`_                                                             |
+|             | - `choice_value`_                                                            |
+|             | - `choice_attr`_                                                             |
+|             | - `choices_as_values`_                                                       |
 |             | - `placeholder`_                                                             |
 |             | - `expanded`_                                                                |
 |             | - `multiple`_                                                                |
 |             | - `preferred_choices`_                                                       |
+|             | - `group_by`_                                                                |
 +-------------+------------------------------------------------------------------------------+
 | Overridden  | - `compound`_                                                                |
 | options     | - `empty_data`_                                                              |
@@ -51,7 +58,8 @@ user sees on the form (e.g. ``Male``).
 .. code-block:: php
 
     $builder->add('gender', 'choice', array(
-        'choices'  => array('m' => 'Male', 'f' => 'Female'),
+        'choices'  => array('Male' => 'm', 'Female' => 'f'),
+        'choices_as_values' => true,
         'required' => false,
     ));
 
@@ -61,15 +69,33 @@ of checkboxes depending on the ``expanded`` option::
 
     $builder->add('availability', 'choice', array(
         'choices' => array(
-            'morning'   => 'Morning',
-            'afternoon' => 'Afternoon',
-            'evening'   => 'Evening',
+            'Morning'   => 'morning',
+            'Afternoon' => 'afternoon',
+            'Evening'   => 'evening',
+        ),
+        'choices_as_values' => true,
+        'multiple' => true,
+    ));
+
+If you rely on your option value attribute (e.g. for JavaScript) you need to
+set ``choice_value``, otherwise the option values will be mapped to integer
+values::
+
+    $builder->add('availability', 'choice', array(
+        'choices' => array(
+            'Morning'   => 'morning',
+            'Afternoon' => 'afternoon',
+            'Evening'   => 'evening',
         ),
+        'choices_as_values' => true,
+        'choice_value' => function ($choice) {
+             return $choice;
+        },
         'multiple' => true,
     ));
 
-You can also use the ``choice_list`` option, which takes an object that
-can specify the choices for your widget.
+You can also use the ``choice_loader`` option, which can be used to load the
+list only partially in cases where a fully-loaded list is not necessary.
 
 .. _forms-reference-choice-tags:
 
@@ -85,19 +111,57 @@ choices
 
 This is the most basic way to specify the choices that should be used
 by this field. The ``choices`` option is an array, where the array key
-is the item value and the array value is the item's label::
+is the item's label and the array value is the item's value::
 
     $builder->add('gender', 'choice', array(
-        'choices' => array('m' => 'Male', 'f' => 'Female'),
+        'choices' => array('Male' => 'm', 'Female' => 'f'),
+        'choices_as_values' => true,
     ));
 
-.. tip::
+.. versionadded:: 2.7
+    Symfony 2.7 introduced the option to flip the ``choices`` array to be
+    able to use values that are not integers or strings (but e.g. floats
+    or booleans).
+
+choices_as_values
+~~~~~~~~~~~~~~~~~
 
-    When the values to choose from are not integers or strings (but e.g.
-    floats or booleans), you should use the `choice_list`_ option instead.
-    With this option you are able to keep the original data format which
-    is important to ensure that the user input is validated properly and
-    useless database updates caused by a data type mismatch are avoided.
+**type**: ``boolean`` **default**: false
+
+.. versionadded:: 2.7
+
+    The ``choices_as_values`` option of ChoiceType was introduced in Symfony 2.7.
+
+The ``choices_as_values`` option was introduced to ensure backward compatibility with the
+modified handling of the ``choices`` optio. Being set to ``false`` the choices array
+will be read as values mapping the keys. Setting the option to ``true`` will enable the new
+handling of the choices mapping keys to values.
+
+* Before 2.7::
+
+    $builder->add('gender', 'choice', array(
+        'choices'  => array('m' => 'Male', 'f' => 'Female'),
+        'choices_as_values' => false,
+    ));
+
+* Optional since 2.7::
+
+    $builder->add('gender', 'choice', array(
+        'choices' => array('Male' => 'm', 'Female' => 'f'),
+        'choices_as_values' => true,
+    ));
+
+* Default for 3.0::
+
+    $builder->add('gender', 'choice', array(
+        'choices' => array('Male' => 'm', 'Female' => 'f'),
+    ));
+
+.. caution::
+
+    The ``choices_as_values`` option will be removed in Symfony 3.0, where
+    the choices will be passed in the values of the ``choices`` option by
+    default.
 
 choice_list
 ~~~~~~~~~~~
@@ -141,6 +205,18 @@ But don't be confused! If ``Full`` is selected (value ``0`` in HTML), ``1``
 will be returned in your form. If ``Almost empty`` is selected (value ``2``
 in HTML), ``0.1`` will be returned.
 
+choice_loader
+~~~~~~~~~~~~~
+
+.. versionadded:: 2.7
+
+    The ``choice_loader`` option of ChoiceType was introduced in Symfony 2.7.
+
+The choice loader can be used to load the list only partially in cases where a
+fully-loaded list is not necessary.
+
+**type**: :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\ChoiceLoaderInterface`
+
 .. include:: /reference/forms/types/options/placeholder.rst.inc
 
 .. include:: /reference/forms/types/options/expanded.rst.inc
@@ -149,6 +225,16 @@ in HTML), ``0.1`` will be returned.
 
 .. include:: /reference/forms/types/options/preferred_choices.rst.inc
 
+.. include:: /reference/forms/types/options/choice_label.rst.inc
+
+.. include:: /reference/forms/types/options/choice_name.rst.inc
+
+.. include:: /reference/forms/types/options/choice_value.rst.inc
+
+.. include:: /reference/forms/types/options/choice_attr.rst.inc
+
+.. include:: /reference/forms/types/options/group_by.rst.inc
+
 Overridden Options
 ------------------
 

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

@@ -0,0 +1,24 @@
+choice_attr
+~~~~~~~~~~~
+
+.. versionadded:: 2.7
+    The ``choice_attr`` option was introduced in Symfony 2.7.
+
+**type**: ``array``, ``callable`` or ``string`` **default**: ``array()``
+
+Returns the additional HTML attributes for choices. Can be an array, a callable
+(like for ``choice_label``) or a property path.
+
+If an array, the keys of the ``choices`` array must be used as keys::
+
+    $builder->add('attending', 'choice', array(
+        'choices' => array(
+            'Yes' => true,
+            'No' => false,
+            'Maybe' => null,
+        ),
+        'choices_as_values' => true,
+        'choice_attr' => array(
+            'Maybe' => array('class' => 'greyed-out'),
+        ),
+    ));

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

@@ -0,0 +1,39 @@
+choice_label
+~~~~~~~~~~~~
+
+.. versionadded:: 2.7
+    The ``choice_label`` option was introduced in Symfony 2.7.
+
+**type**: ``callable`` or ``string`` **default**: ``null``
+
+Returns the label for each choice. Can be a callable (which receives the choice
+as first and the key of the ``choices`` array as second argument) or a property
+path.
+
+If ``null``, the keys of the ``choices`` array are used as labels.
+
+* Using a callable to set the label::
+
+    $builder->add('attending', 'choice', array(
+        'choices' => array(
+            'yes' => true,
+            'no' => false,
+            'maybe' => null,
+        ),
+        'choices_as_values' => true,
+        'choice_label' => function ($choice, $key) {
+            return 'form.choice.'.$key;
+        },
+    ));
+
+* Using a property path to set the label::
+
+    $builder->add('attending', 'choice', array(
+        'choices' => array(
+            Status::getInstance(Status::YES),
+            Status::getInstance(Status::NO),
+            Status::getInstance(Status::MAYBE),
+        ),
+        'choices_as_values' => true,
+        'choice_label' => 'displayName',
+    ));

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

@@ -0,0 +1,18 @@
+choice_name
+~~~~~~~~~~~
+
+.. versionadded:: 2.7
+    The ``choice_name`` option was introduced in Symfony 2.7.
+
+**type**: ``callable`` or ``string`` **default**: ``null``
+
+Returns the form name for each choice. That name is used as name of the
+checkbox/radio form for this choice. It is also used as index of the choice
+views in the template. Can be a callable (like for ``choice_label``) or a
+property path.
+
+The generated names must be valid form names, i.e. contain alpha-numeric
+symbols, underscores, hyphens and colons only. They must start with an
+alpha-numeric symbol or an underscore.
+
+If ``null``, an incrementing integer is used as name.

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

@@ -0,0 +1,13 @@
+choice_value
+~~~~~~~~~~~~
+
+.. versionadded:: 2.7
+    The ``choice_value`` option was introduced in Symfony 2.7.
+
+**type**: ``callable`` or ``string`` **default**: ``null``
+
+Returns the string value for each choice. This value is displayed in the
+``value`` attributes and submitted in the POST/PUT requests. Can be a
+callable (like for ``choice_label``) or a property path.
+
+If ``null``, an incrementing integer is used as value.

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

@@ -0,0 +1,29 @@
+group_by
+~~~~~~~~
+
+.. versionadded:: 2.7
+    The ``group_by`` option was introduced in Symfony 2.7.
+
+**type**: ``array``, ``callable`` or ``string`` **default**: ``null``
+
+Returns the grouping used for the choices. Can be an array/Traversable, a
+callable (like for ``choice_label``) or a property path.
+
+The return values of the callable/property path are used as group labels. If
+``null`` is returned, a choice is not grouped.
+
+If ``null``, the structure of the ``choices`` array is used to construct the
+groups::
+
+    $builder->add('attending', 'choice', array(
+        'choices' => array(
+            'Decided' => array(
+                'Yes' => true,
+                'No' => false,
+            ),
+            'Undecided' => array(
+                'Maybe' => null,
+            ),
+        ),
+        'choices_as_values' => true,
+    ));

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

@@ -1,16 +1,52 @@
 preferred_choices
 ~~~~~~~~~~~~~~~~~
 
-**type**: ``array`` **default**: ``array()``
+**type**: ``array``, ``callable`` or ``string`` **default**: ``array()``
 
-If this option is specified, then a sub-set of all of the options will be
+If this option is specified as an array, then a sub-set of all of the options will be
 moved to the top of the select menu. The following would move the "Baz"
 option to the top, with a visual separator between it and the rest of the
 options::
 
-    $builder->add('foo_choices', 'choice', array(
-        'choices' => array('foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz'),
-        'preferred_choices' => array('baz'),
+    $builder->add('attending', 'choice', array(
+        'choices' => array(
+            'Yes' => true,
+            'No' => false,
+            'Maybe' => null,
+        ),
+        'choices_as_values' => true,
+        'preferred_choices' => array(true),
+    ));
+
+.. versionadded:: 2.7
+    Setting a callable or propery path was introduced in Symfony 2.7.
+
+If this option is specified as a callable, then the the preferred options
+are computed by the callback::
+
+    $builder->add('attending', 'choice', array(
+        'choices' => array(
+            'Yes' => true,
+            'No' => false,
+            'Maybe' => null,
+        ),
+        'choices_as_values' => true,
+        'preferred_choices' => function ($choice, $key) {
+            return true === $choice;
+        },
+    ));
+
+If this option is specified as a property path, then the preferred options
+are taken from the objects::
+
+    $builder->add('attending', 'choice', array(
+        'choices' => array(
+            'Yes' => Status::getInstance(Status::YES),
+            'No' => Status::getInstance(Status::NO),
+            'Maybe' => Status::getInstance(Status::MAYBE),
+        ),
+        'choices_as_values' => true,
+        'preferred_choices' => 'preferred',
     ));
 
 Note that preferred choices are only meaningful when rendering as a ``select``