Merge pull request #907 from elnur/choice-empty-data

Added a section on the empty_data option of the choice form type

Author: weaverryan

reference/forms/types/choice.rst

@@ -19,6 +19,7 @@ option.
 |             | - `expanded`_                                                               |
 |             | - `preferred_choices`_                                                      |
 |             | - `empty_value`_                                                            |
+|             | - `empty_data`_                                                             |
 +-------------+-----------------------------------------------------------------------------+
 | Inherited   | - `required`_                                                               |
 | options     | - `label`_                                                                  |
@@ -101,6 +102,8 @@ can be created to supply the choices.
 
 .. include:: /reference/forms/types/options/empty_value.rst.inc
 
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+
 Inherited options
 -----------------
 

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

@@ -0,0 +1,22 @@
+empty_data
+~~~~~~~~~~
+
+**type**: ``mixed`` **default**: ``array()`` if ``multiple`` or ``expanded``, ``''`` otherwise
+
+This option determines what value the field will return when the ``empty_value``
+choice is selected.
+
+For example, if you want the ``gender`` field to be set to ``null`` when no
+value is selected, you can do it like this:
+
+.. code-block:: php
+
+    $builder->add('gender', 'choice', array(
+        'choices' => array(
+            'm' => 'Male',
+            'f' => 'Female'
+        ),
+        'required'    => false,
+        'empty_value' => 'Choose your gender',
+        'empty_data'  => null
+    ));