diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst index decc14e5e93..e907290e7e0 100644 --- a/reference/forms/types/collection.rst +++ b/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 ` | @@ -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 diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index 9cdfc92a7e9..6b9bfb60aa4 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/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 diff --git a/reference/forms/types/options/required.rst.inc b/reference/forms/types/options/required.rst.inc index cf5e2bfe481..0c6c567d726 100644 --- a/reference/forms/types/options/required.rst.inc +++ b/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 \ No newline at end of file +.. 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