Improvements of the CollectionType Documentation

reference/forms/types/collection.rst

@@ -19,12 +19,14 @@ forms, which is useful when creating forms that expose one-to-many relationships
 |             | - `allow_delete`_                                                           |
 |             | - `prototype`_                                                              |
 |             | - `prototype_name`_                                                         |
+|             | - `delete_empty`_                                                           |
 +-------------+-----------------------------------------------------------------------------+
 | Inherited   | - `label`_                                                                  |
 | options     | - `error_bubbling`_                                                         |
 |             | - `error_mapping`_                                                          |
 |             | - `by_reference`_                                                           |
 |             | - `empty_data`_                                                             |
+|             | - `required`_                                                               |
 |             | - `mapped`_                                                                 |
 +-------------+-----------------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                                   |
@@ -34,9 +36,9 @@ forms, which is useful when creating forms that expose one-to-many relationships
 
 .. note::
 
-    If you are working with a collection of Doctrine entities, pay special 
+    If you are working with a collection of Doctrine entities, pay special
     attention to the `allow_add`_, `allow_delete`_ and `by_reference`_ options.
-    You can also see a complete example in the cookbook article 
+    You can also see a complete example in the cookbook article
     :doc:`/cookbook/form/form_collections`.
 
 Basic Usage
@@ -333,6 +335,16 @@ If you have several collections in your form, or worse, nested collections
 you may want to change the placeholder so that unrelated placeholders are not
 replaced with the same value.
 
+delete_empty
+~~~~~~~~~~~~
+
+**type**: ``Boolean`` **default**: ``false``
+
+If you want to explicitly remove entirely empty collection entries from your
+form you have to set this option to true. However, existing collection entries
+will only be deleted if you have the allow_delete_ option enabled. Otherwise
+the empty values will be kept.
+
 Inherited options
 -----------------
 
@@ -357,3 +369,5 @@ error_bubbling
 .. include:: /reference/forms/types/options/by_reference.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+
+.. include:: /reference/forms/types/options/required.rst.inc

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

@@ -8,17 +8,13 @@ choice is selected.
 
 The true default value of this option depends on the field options:
 
-* If ``compound`` is ``true`` and ``data_class`` is set, then ``new $data_class()``;
-* If ``compound`` is ``true`` and no ``data_class`` is set, then ``array()``;
-* If ``compound`` is ``false``, then ``null``.
+* If ``data_class`` is set and  ``required`` is  ``true``, then ``null``;
+* If ``data_class`` is set and  ``required`` is  ``false``, then ``new $data_class()``;
+* If ``data_class`` is not set and  ``compound`` is  ``true``, then ``array()``;
+* If ``data_class`` is not set and  ``compound`` is  ``false``, then ``null``.
 
-.. tip::
-
-    The ``compound`` option is set to ``true`` when the field actually represents
-    a collection of fields (e.g. a form of fields).
-
-For example, if you want the ``gender`` field to be set to ``null`` when no
-value is selected, you can do it like this:
+But you can customize this to your needs. For example, if you want the ``gender`` field to be
+explicitly set to ``null`` when no value is selected, you can do it like this:
 
 .. code-block:: php
 

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

@@ -10,4 +10,9 @@ This is superficial and independent from validation. At best, if you let Symfony
 guess your field type, then the value of this option will be guessed from
 your validation information.
 
-.. _`HTML5 required attribute`: http://diveintohtml5.info/forms.html
+.. note::
+
+    The required option does also affect the way how empty data of your form is
+    being handled. For further details check the `empty_data`_ option.
+
+.. _`HTML5 required attribute`: http://diveintohtml5.info/forms.html