From 98213f76051d067f9210e2a9e07780fb2398441c Mon Sep 17 00:00:00 2001 From: Peter Rehm Date: Sat, 14 Dec 2013 16:21:21 +0100 Subject: [PATCH 1/3] Enhanced documentation to clearify the require option and added the option for symfony/symfony#9773 --- reference/forms/types/collection.rst | 18 ++++++++++++++++-- .../forms/types/options/empty_data.rst.inc | 14 +++++--------- reference/forms/types/options/required.rst.inc | 7 ++++++- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst index decc14e5e93..065c3900122 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. Existing collection entries will +however only be deleted if you have `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..2ca064df65e 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 ``required`` is ``true`` and ``data_class`` is set, then ``new $data_class()``; +* If ``required`` is ``true`` and no ``data_class`` is set, then ``array()``; +* If ``required`` 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 +set to explicitly ``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..f7047bdb2c2 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 +.. _`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 :doc:` empty_data` option. \ No newline at end of file From d47dc3aeaaf2d25d8d3ef2a3988b0d8ccc21d0b1 Mon Sep 17 00:00:00 2001 From: Peter Rehm Date: Sun, 15 Dec 2013 12:14:37 +0100 Subject: [PATCH 2/3] Formatted and minor improvements --- reference/forms/types/collection.rst | 6 +++--- reference/forms/types/options/empty_data.rst.inc | 2 +- reference/forms/types/options/required.rst.inc | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst index 065c3900122..e907290e7e0 100644 --- a/reference/forms/types/collection.rst +++ b/reference/forms/types/collection.rst @@ -336,13 +336,13 @@ 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. Existing collection entries will -however only be deleted if you have `allow_delete`_ option enabled, otherwise +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 diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index 2ca064df65e..aef293da824 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -14,7 +14,7 @@ The true default value of this option depends on the field options: But you can customize this to your needs. For example, if you want the ``gender`` field to be -set to explicitly ``null`` when no value is selected, you can do it like this: +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 f7047bdb2c2..0c6c567d726 100644 --- a/reference/forms/types/options/required.rst.inc +++ b/reference/forms/types/options/required.rst.inc @@ -10,9 +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 :doc:` empty_data` option. \ No newline at end of file + 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 From 38b37d425a7e136b6deae9c392ae5fb81f7ecbc6 Mon Sep 17 00:00:00 2001 From: Peter Rehm Date: Fri, 27 Dec 2013 12:54:51 +0100 Subject: [PATCH 3/3] Fixed explanation of field options --- reference/forms/types/options/empty_data.rst.inc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index aef293da824..6b9bfb60aa4 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -8,10 +8,10 @@ choice is selected. The true default value of this option depends on the field options: -* If ``required`` is ``true`` and ``data_class`` is set, then ``new $data_class()``; -* If ``required`` is ``true`` and no ``data_class`` is set, then ``array()``; -* If ``required`` 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``. 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: