From 6b61260743e587cc62023b7138de8f309376c3c6 Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Thu, 17 Jul 2014 22:41:46 +0200 Subject: [PATCH] field dependent empty_data option description --- reference/forms/types/choice.rst | 10 ++++++++++ reference/forms/types/collection.rst | 6 ++++++ reference/forms/types/country.rst | 10 ++++++++++ reference/forms/types/currency.rst | 10 ++++++++++ reference/forms/types/email.rst | 6 ++++++ reference/forms/types/entity.rst | 10 ++++++++++ reference/forms/types/file.rst | 6 ++++++ reference/forms/types/form.rst | 12 ++++++++++++ reference/forms/types/integer.rst | 6 ++++++ reference/forms/types/language.rst | 10 ++++++++++ reference/forms/types/locale.rst | 10 ++++++++++ reference/forms/types/money.rst | 10 ++++++++-- reference/forms/types/number.rst | 8 +++++++- .../types/options/checkbox_empty_data.rst.inc | 5 ++--- reference/forms/types/options/empty_data.rst.inc | 16 ++++++---------- reference/forms/types/password.rst | 6 ++++++ reference/forms/types/percent.rst | 6 ++++++ reference/forms/types/radio.rst | 2 +- reference/forms/types/search.rst | 6 ++++++ reference/forms/types/text.rst | 6 ++++++ reference/forms/types/textarea.rst | 6 ++++++ reference/forms/types/timezone.rst | 10 ++++++++++ reference/forms/types/url.rst | 6 ++++++ 23 files changed, 166 insertions(+), 17 deletions(-) diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst index f7e298ec0aa..d55e1ffb771 100644 --- a/reference/forms/types/choice.rst +++ b/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 ~~~~~~~~ diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst index fc8aecd01ae..4402f015dbd 100644 --- a/reference/forms/types/collection.rst +++ b/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 diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst index 700e4adb6c6..f077b1fc34a 100644 --- a/reference/forms/types/country.rst +++ b/reference/forms/types/country.rst @@ -76,6 +76,16 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`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 diff --git a/reference/forms/types/currency.rst b/reference/forms/types/currency.rst index ba7597bf564..053ffa09101 100644 --- a/reference/forms/types/currency.rst +++ b/reference/forms/types/currency.rst @@ -66,6 +66,16 @@ These options inherit from the :doc:`choice` type These options inherit from the :doc:`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 diff --git a/reference/forms/types/email.rst b/reference/forms/types/email.rst index b27a919db92..53a01e25080 100644 --- a/reference/forms/types/email.rst +++ b/reference/forms/types/email.rst @@ -36,6 +36,12 @@ These options inherit from the :doc:`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 diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index e68cf6718d6..b11e5971492 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -212,6 +212,16 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`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 diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst index 32c718f3a8c..044d88874d9 100644 --- a/reference/forms/types/file.rst +++ b/reference/forms/types/file.rst @@ -84,6 +84,12 @@ Inherited Options These options inherit from the :doc:`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 diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst index a3b2ab83e65..d3b281ad6ae 100644 --- a/reference/forms/types/form.rst +++ b/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 diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst index 14add652997..78e564ebf49 100644 --- a/reference/forms/types/integer.rst +++ b/reference/forms/types/integer.rst @@ -71,6 +71,12 @@ Inherited Options These options inherit from the :doc:`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 diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst index 1b8e78b2db4..fc24b91e36e 100644 --- a/reference/forms/types/language.rst +++ b/reference/forms/types/language.rst @@ -77,6 +77,16 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`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 diff --git a/reference/forms/types/locale.rst b/reference/forms/types/locale.rst index 56b588662aa..4a33d06f600 100644 --- a/reference/forms/types/locale.rst +++ b/reference/forms/types/locale.rst @@ -79,6 +79,16 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`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 diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst index 0f6f07248bb..60fbc9feeca 100644 --- a/reference/forms/types/money.rst +++ b/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 ` 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. ============= ========== =============================================================== diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst index 8152a65c913..196880502f8 100644 --- a/reference/forms/types/number.rst +++ b/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 ` 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 diff --git a/reference/forms/types/options/checkbox_empty_data.rst.inc b/reference/forms/types/options/checkbox_empty_data.rst.inc index d7a09ba3b7b..9e3c2e79427 100644 --- a/reference/forms/types/options/checkbox_empty_data.rst.inc +++ b/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`). diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index d778c65a79c..34ca9cb878c 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/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 diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst index 12ed8b17d77..248b1e9595e 100644 --- a/reference/forms/types/password.rst +++ b/reference/forms/types/password.rst @@ -53,6 +53,12 @@ These options inherit from the :doc:`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 diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst index c1c2b673ac0..bc0c9bda317 100644 --- a/reference/forms/types/percent.rst +++ b/reference/forms/types/percent.rst @@ -73,6 +73,12 @@ Inherited Options These options inherit from the :doc:`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 diff --git a/reference/forms/types/radio.rst b/reference/forms/types/radio.rst index 946899170cb..5bc292b7d05 100644 --- a/reference/forms/types/radio.rst +++ b/reference/forms/types/radio.rst @@ -44,7 +44,7 @@ These options inherit from the :doc:`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 diff --git a/reference/forms/types/search.rst b/reference/forms/types/search.rst index 9ff7b9d8393..5fd671e981f 100644 --- a/reference/forms/types/search.rst +++ b/reference/forms/types/search.rst @@ -37,6 +37,12 @@ These options inherit from the :doc:`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 diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst index 675b1f800ae..5fbe7759688 100644 --- a/reference/forms/types/text.rst +++ b/reference/forms/types/text.rst @@ -36,6 +36,12 @@ These options inherit from the :doc:`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 diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst index 19e65434c57..a584fdc90c1 100644 --- a/reference/forms/types/textarea.rst +++ b/reference/forms/types/textarea.rst @@ -35,6 +35,12 @@ These options inherit from the :doc:`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 diff --git a/reference/forms/types/timezone.rst b/reference/forms/types/timezone.rst index 89ca811e3fb..3902184d0b6 100644 --- a/reference/forms/types/timezone.rst +++ b/reference/forms/types/timezone.rst @@ -68,6 +68,16 @@ These options inherit from the :doc:`choice ` typ These options inherit from the :doc:`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 diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst index 44a68d68218..ceacbc4deeb 100644 --- a/reference/forms/types/url.rst +++ b/reference/forms/types/url.rst @@ -51,6 +51,12 @@ These options inherit from the :doc:`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