bug #4083 [Reference] field dependent empty_data option description (…

…xabbuh)

This PR was merged into the 2.3 branch.

Discussion
----------

[Reference] field dependent empty_data option description

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | #4007

- [x] choice
- [x] collection
- [x] country
- [x] currency
- [x] email
- [x] entity
- [x] file
- [x] form
- [x] integer
- [x] language
- [x] locale
- [x] money
- [x] number
- [x] password
- [x] percent
- [x] radio
- [x] search
- [x] text
- [x] textarea
- [x] timezone
- [x] url

Replacement of #4033.

Commits
-------

6b61260 field dependent empty_data option description

reference/forms/types/choice.rst

@@ -115,6 +115,16 @@ Overridden Options
 ------------------
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 compound
 ~~~~~~~~

reference/forms/types/collection.rst

@@ -360,6 +360,12 @@ error_bubbling
 .. include:: /reference/forms/types/options/by_reference.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/country.rst

@@ -76,6 +76,16 @@ These options inherit from the :doc:`choice </reference/forms/types/choice>` typ
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/currency.rst

@@ -66,6 +66,16 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
 These options inherit from the :doc:`form</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/email.rst

@@ -36,6 +36,12 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/max_length.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/entity.rst

@@ -212,6 +212,16 @@ These options inherit from the :doc:`choice </reference/forms/types/choice>` typ
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/file.rst

@@ -84,6 +84,12 @@ Inherited Options
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``null``.
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/form.rst

@@ -53,6 +53,18 @@ Field Options
 .. include:: /reference/forms/types/options/data_class.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``data_class`` is set and ``required`` is ``true``, then ``new $data_class()``;
+* If ``data_class`` is set and ``required`` is ``false``, then ``null``;
+* If ``data_class`` is not set and ``compound`` is ``true``, then ``array()``
+  (empty array);
+* If ``data_class`` is not set and ``compound`` is ``false``, then ``''`` (empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/compound.rst.inc
 

reference/forms/types/integer.rst

@@ -71,6 +71,12 @@ Inherited Options
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/language.rst

@@ -77,6 +77,16 @@ These options inherit from the :doc:`choice </reference/forms/types/choice>` typ
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/locale.rst

@@ -79,6 +79,16 @@ These options inherit from the :doc:`choice </reference/forms/types/choice>` typ
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/money.rst

@@ -49,7 +49,7 @@ Specifies the currency that the money is being specified in. This determines
 the currency symbol that should be shown by the text box. Depending on
 the currency - the currency symbol may be shown before or after the input
 text field.
-    
+
 This can be any `3 letter ISO 4217 code`_. You can also set this to false to
 hide the currency symbol.
 
@@ -89,6 +89,12 @@ Inherited Options
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 
@@ -116,7 +122,7 @@ Form Variables
 --------------
 
 ============= ========== ===============================================================
-Variable      Type       Usage                                       
+Variable      Type       Usage
 ============= ========== ===============================================================
 money_pattern ``string`` The format to use to display the money, including the currency.
 ============= ========== ===============================================================

reference/forms/types/number.rst

@@ -46,7 +46,7 @@ rounding_mode
 If a submitted number needs to be rounded (based on the ``precision``
 option), you have several configurable options for that rounding. Each
 option is a constant on the :class:`Symfony\\Component\\Form\\Extension\\Core\\DataTransformer\\IntegerToLocalizedStringTransformer`:
-    
+
 *   ``IntegerToLocalizedStringTransformer::ROUND_DOWN`` Rounding mode to
     round towards zero.
 
@@ -79,6 +79,12 @@ Inherited Options
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

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

@@ -4,6 +4,5 @@ empty_data
 **type**: ``string`` **default**: ``mixed``
 
 This option determines what value the field will return when the ``empty_value``
-choice is selected.
-In checkbox, the value of ``empty_data`` is overriden by the value returned by
-the data transformer (see :doc:`/cookbook/form/data_transformers`).
+choice is selected. In the checkbox and the radio type, the value of ``empty_data``
+is overriden by the value returned by the data transformer (see :doc:`/cookbook/form/data_transformers`).

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

@@ -1,19 +1,15 @@
 empty_data
 ~~~~~~~~~~
 
-**type**: ``mixed`` **default**: depends on other field options, see below
+**type**: ``mixed``
 
-This option determines what value the field will return when the submitted
-value is empty. This may happen when the ``empty_value`` choice in a
-``choice`` field is selected or when an ``input`` field of some type is not
-required and left empty by the user.
+.. This file should only be included with start-after or end-before that's set to
+   this placeholder value. Its purpose is to let us include only part of this file.
 
-The true default value of this option depends on other field options:
+DEFAULT_PLACEHOLDER
 
-* If ``data_class`` is set and ``required`` is ``true``, then ``new $data_class()``;
-* If ``data_class`` is set and ``required`` is ``false``, then ``null``;
-* If ``data_class`` is not set and ``compound`` is ``true``, then ``array()``;
-* If ``data_class`` is not set and ``compound`` is ``false``, then ``''`` (empty string).
+This option determines what value the field will return when the submitted
+value is empty.
 
 But you can customize this to your needs. For example, if you want the
 ``gender`` choice field to be explicitly set to ``null`` when no value is

reference/forms/types/password.rst

@@ -53,6 +53,12 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/max_length.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/percent.rst

@@ -73,6 +73,12 @@ Inherited Options
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/radio.rst

@@ -44,7 +44,7 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/data.rst.inc
 
-.. include:: /reference/forms/types/options/empty_data.rst.inc
+.. include:: /reference/forms/types/options/checkbox_empty_data.rst.inc
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/search.rst

@@ -37,6 +37,12 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/max_length.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/text.rst

@@ -36,6 +36,12 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/max_length.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/textarea.rst

@@ -35,6 +35,12 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/max_length.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/timezone.rst

@@ -68,6 +68,16 @@ These options inherit from the :doc:`choice </reference/forms/types/choice>` typ
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/url.rst

@@ -51,6 +51,12 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/max_length.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc