From f4e4730c689203e0e5c040bbaf20773c779dc17e Mon Sep 17 00:00:00 2001
From: Elnur Abdurrakhimov <elnur@elnur.org>
Date: Thu, 8 Dec 2011 23:04:03 +0400
Subject: [PATCH] Added a section on the empty_data option of the choice form
 type.

---
 reference/forms/types/choice.rst              |  3 +++
 .../forms/types/options/empty_data.rst.inc    | 22 +++++++++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 reference/forms/types/options/empty_data.rst.inc

diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
index 0635355ec19..8dd1a0355b2 100644
--- a/reference/forms/types/choice.rst
+++ b/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
 -----------------
 
diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc
new file mode 100644
index 00000000000..1827d560b4b
--- /dev/null
+++ b/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
+    ));