diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst index 6efabd4dad1..9b44a076432 100644 --- a/reference/forms/types/country.rst +++ b/reference/forms/types/country.rst @@ -23,7 +23,7 @@ you should just use the ``choice`` type directly. | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+-----------------------------------------------------------------------+ | Overridden | - `choices`_ | -| Options | | +| options | | +-------------+-----------------------------------------------------------------------+ | Inherited | from the :doc:`choice ` type | | options | | diff --git a/reference/forms/types/currency.rst b/reference/forms/types/currency.rst index 14a433fc188..0f86a3cee07 100644 --- a/reference/forms/types/currency.rst +++ b/reference/forms/types/currency.rst @@ -17,7 +17,7 @@ you should just use the ``choice`` type directly. | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+------------------------------------------------------------------------+ | Overridden | - `choices`_ | -| Options | | +| options | | +-------------+------------------------------------------------------------------------+ | Inherited | from the :doc:`choice ` type | | options | | diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst index 33794d61d78..bd456e7f758 100644 --- a/reference/forms/types/date.rst +++ b/reference/forms/types/date.rst @@ -29,7 +29,9 @@ day and year) or three select boxes (see the `widget`_ option). | | - `widget`_ | | | - `years`_ | +----------------------+-----------------------------------------------------------------------------+ -| Overridden Options | - `by_reference`_ | +| Overridden options | - `by_reference`_ | +| | - `compound`_ | +| | - `data_class`_ | | | - `error_bubbling`_ | +----------------------+-----------------------------------------------------------------------------+ | Inherited | - `data`_ | @@ -125,6 +127,10 @@ by_reference The ``DateTime`` classes are treated as immutable objects. +.. include:: /reference/forms/types/options/compound_type.rst.inc + +.. include:: /reference/forms/types/options/data_class_date.rst.inc + error_bubbling ~~~~~~~~~~~~~~ diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst index 01ac12fb25c..b95d9d6cea2 100644 --- a/reference/forms/types/datetime.rst +++ b/reference/forms/types/datetime.rst @@ -33,6 +33,11 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array. | | - `with_seconds`_ | | | - `years`_ | +----------------------+-----------------------------------------------------------------------------+ +| Overridden options | - `by_reference`_ | +| | - `compound`_ | +| | - `data_class`_ | +| | - `error_bubbling`_ | ++----------------------+-----------------------------------------------------------------------------+ | Inherited | - `data`_ | | options | - `disabled`_ | | | - `inherit_data`_ | @@ -131,6 +136,25 @@ with the `date_widget`_ and `time_widget`_ options. .. include:: /reference/forms/types/options/years.rst.inc +Overridden Options +------------------ + +by_reference +~~~~~~~~~~~~ + +**default**: ``false`` + +The ``DateTime`` classes are treated as immutable objects. + +.. include:: /reference/forms/types/options/compound_type.rst.inc + +.. include:: /reference/forms/types/options/data_class_date.rst.inc + +error_bubbling +~~~~~~~~~~~~~~ + +**default**: ``false`` + Inherited Options ----------------- diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index f46229083fe..fd59bef9a29 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -19,7 +19,7 @@ objects from the database. | | - `property`_ | | | - `query_builder`_ | +-------------+------------------------------------------------------------------+ -| Overriden | - `choice_list`_ | +| Overridden | - `choice_list`_ | | options | - `choices`_ | +-------------+------------------------------------------------------------------+ | Inherited | from the :doc:`choice ` type: | diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst index b60666c3893..188f0d0ec59 100644 --- a/reference/forms/types/file.rst +++ b/reference/forms/types/file.rst @@ -9,9 +9,12 @@ The ``file`` type represents a file input in your form. +-------------+---------------------------------------------------------------------+ | Rendered as | ``input`` ``file`` field | +-------------+---------------------------------------------------------------------+ +| Overridden | - `compound`_ | +| options | - `data_class`_ | +| | - `empty_data`_ | ++-------------+---------------------------------------------------------------------+ | Inherited | - `disabled`_ | -| options | - `empty_data`_ | -| | - `error_bubbling`_ | +| options | - `error_bubbling`_ | | | - `error_mapping`_ | | | - `label`_ | | | - `label_attr`_ | @@ -24,6 +27,26 @@ The ``file`` type represents a file input in your form. | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FileType` | +-------------+---------------------------------------------------------------------+ +Overridden Options +------------------ + +.. include:: /reference/forms/types/options/compound_type.rst.inc + +data_class +~~~~~~~~~~ + +**type**: ``string`` **default**: :class:`Symfony\\Component\\HttpFoundation\\File\\File` + +This option sets the appropriate file-related data mapper to be used by the type. + +empty_data +~~~~~~~~~~ + +**type**: ``mixed`` **default**: ``null`` + +This option determines what value the field will return when the submitted +value is empty. + Basic Usage ----------- @@ -82,14 +105,6 @@ type: .. include:: /reference/forms/types/options/disabled.rst.inc -.. 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/error_bubbling.rst.inc .. include:: /reference/forms/types/options/error_mapping.rst.inc diff --git a/reference/forms/types/hidden.rst b/reference/forms/types/hidden.rst index 6e1b8500fab..272eb853852 100644 --- a/reference/forms/types/hidden.rst +++ b/reference/forms/types/hidden.rst @@ -9,8 +9,9 @@ The hidden type represents a hidden input field. +-------------+----------------------------------------------------------------------+ | Rendered as | ``input`` ``hidden`` field | +-------------+----------------------------------------------------------------------+ -| Overriden | - `error_bubbling`_ | -| options | - `required`_ | +| Overriden | - `compound`_ | +| options | - `error_bubbling`_ | +| | - `required`_ | +-------------+----------------------------------------------------------------------+ | Inherited | - `data`_ | | options | - `error_mapping`_ | @@ -25,6 +26,8 @@ The hidden type represents a hidden input field. Overridden Options ------------------ +.. include:: /reference/forms/types/options/compound_type.rst.inc + error_bubbling ~~~~~~~~~~~~~~ diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst index e6ea1895cb5..4a571df3652 100644 --- a/reference/forms/types/integer.rst +++ b/reference/forms/types/integer.rst @@ -16,6 +16,9 @@ integers. By default, all non-integer values (e.g. 6.78) will round down +-------------+-----------------------------------------------------------------------+ | Rendered as | ``input`` ``number`` field | +-------------+-----------------------------------------------------------------------+ +| Overridden | - `compound`_ | +| options | | ++-------------+-----------------------------------------------------------------------+ | Options | - `grouping`_ | | | - `precision`_ | | | - `rounding_mode`_ | @@ -38,6 +41,11 @@ integers. By default, all non-integer values (e.g. 6.78) will round down | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\IntegerType` | +-------------+-----------------------------------------------------------------------+ +Overridden Options +------------------ + +.. include:: /reference/forms/types/options/compound_type.rst.inc + Field Options ------------- diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst index 75689b88771..dcc1879daad 100644 --- a/reference/forms/types/language.rst +++ b/reference/forms/types/language.rst @@ -24,7 +24,7 @@ you should just use the ``choice`` type directly. | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+------------------------------------------------------------------------+ | Overridden | - `choices`_ | -| Options | | +| options | | +-------------+------------------------------------------------------------------------+ | Inherited | from the :doc:`choice ` type | | options | | diff --git a/reference/forms/types/locale.rst b/reference/forms/types/locale.rst index daa14e90e41..6126d577676 100644 --- a/reference/forms/types/locale.rst +++ b/reference/forms/types/locale.rst @@ -26,7 +26,7 @@ you should just use the ``choice`` type directly. | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+------------------------------------------------------------------------+ | Overridden | - `choices`_ | -| Options | | +| options | | +-------------+------------------------------------------------------------------------+ | Inherited | from the :doc:`choice ` type | | options | | diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst index 29d0abedd86..a1a7247bf15 100644 --- a/reference/forms/types/money.rst +++ b/reference/forms/types/money.rst @@ -14,6 +14,9 @@ how the input and output of the data is handled. +-------------+---------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+---------------------------------------------------------------------+ +| Overridden | - `compound`_ | +| options | | ++-------------+---------------------------------------------------------------------+ | Options | - `currency`_ | | | - `divisor`_ | | | - `grouping`_ | @@ -37,6 +40,11 @@ how the input and output of the data is handled. | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\MoneyType` | +-------------+---------------------------------------------------------------------+ +Overridden Options +------------------ + +.. include:: /reference/forms/types/options/compound_type.rst.inc + Field Options ------------- diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst index ec85bc52ad4..3dae2121195 100644 --- a/reference/forms/types/number.rst +++ b/reference/forms/types/number.rst @@ -11,6 +11,9 @@ that you want to use for your number. +-------------+----------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+----------------------------------------------------------------------+ +| Overridden | - `compound`_ | +| options | | ++-------------+----------------------------------------------------------------------+ | Options | - `grouping`_ | | | - `precision`_ | | | - `rounding_mode`_ | @@ -33,6 +36,11 @@ that you want to use for your number. | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\NumberType` | +-------------+----------------------------------------------------------------------+ +Overridden Options +------------------ + +.. include:: /reference/forms/types/options/compound_type.rst.inc + Field Options ------------- diff --git a/reference/forms/types/options/compound_type.rst.inc b/reference/forms/types/options/compound_type.rst.inc new file mode 100644 index 00000000000..39e4abc3dfc --- /dev/null +++ b/reference/forms/types/options/compound_type.rst.inc @@ -0,0 +1,8 @@ +compound +~~~~~~~~ + +**type**: ``boolean`` **default**: ``false`` + +This option specifies whether the type contains child types or not. This option +is managed internally for built-in types, so there is no need to configure +it explicitly. diff --git a/reference/forms/types/options/data_class_date.rst.inc b/reference/forms/types/options/data_class_date.rst.inc new file mode 100644 index 00000000000..d11296e263f --- /dev/null +++ b/reference/forms/types/options/data_class_date.rst.inc @@ -0,0 +1,8 @@ +data_class +~~~~~~~~~~ + +**type**: ``string`` **default**: ``null`` + +The internal normalized representation of this type is an array, not a ``\DateTime`` +object. Therefore, the ``data_class`` option is initialized to ``null`` to avoid +the ``FormType`` object from initializing it to ``\DateTime``. diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst index 8382a0fc0e9..70506f5abc0 100644 --- a/reference/forms/types/password.rst +++ b/reference/forms/types/password.rst @@ -11,6 +11,9 @@ The ``password`` field renders an input password text box. +-------------+------------------------------------------------------------------------+ | Options | - `always_empty`_ | +-------------+------------------------------------------------------------------------+ +| Overridden | - `trim`_ | +| options | | ++-------------+------------------------------------------------------------------------+ | Inherited | - `disabled`_ | | options | - `empty_data`_ | | | - `error_bubbling`_ | @@ -21,7 +24,6 @@ The ``password`` field renders an input password text box. | | - `max_length`_ | | | - `read_only`_ | | | - `required`_ | -| | - `trim`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`text ` | +-------------+------------------------------------------------------------------------+ @@ -44,6 +46,18 @@ Put simply, if for some reason you want to render your password field *with* the password value already entered into the box, set this to false and submit the form. +Overridden Options +------------------ + +trim +~~~~ + +**type**: ``boolean`` **default**: ``false`` + +Unlike the rest of form types, the ``password`` type doesn't apply the +:phpfunction:`trim` function to the value submitted by the user. This ensures that +the password is merged back onto the underlying object exactly as it was typed +by the user. Inherited Options ----------------- @@ -76,13 +90,3 @@ The default value is ``''`` (the empty string). .. include:: /reference/forms/types/options/read_only.rst.inc .. include:: /reference/forms/types/options/required.rst.inc - -trim -~~~~ - -**type**: ``boolean`` **default**: ``false`` - -If true, the whitespace of the submitted string value will be stripped -via the :phpfunction:`trim` function when the data is bound. This guarantees -that if a value is submitted with extra whitespace, it will be removed before -the value is merged back onto the underlying object. diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst index 4aea0b90481..12aded78a3e 100644 --- a/reference/forms/types/percent.rst +++ b/reference/forms/types/percent.rst @@ -15,6 +15,9 @@ This field adds a percentage sign "``%``" after the input box. +-------------+-----------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+-----------------------------------------------------------------------+ +| Overridden | - `compound`_ | +| options | | ++-------------+-----------------------------------------------------------------------+ | Options | - `precision`_ | | | - `type`_ | +-------------+-----------------------------------------------------------------------+ @@ -36,6 +39,11 @@ This field adds a percentage sign "``%``" after the input box. | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\PercentType` | +-------------+-----------------------------------------------------------------------+ +Overridden Options +------------------ + +.. include:: /reference/forms/types/options/compound_type.rst.inc + Field Options ------------- diff --git a/reference/forms/types/repeated.rst b/reference/forms/types/repeated.rst index 8a69f565100..4556ecc88d8 100644 --- a/reference/forms/types/repeated.rst +++ b/reference/forms/types/repeated.rst @@ -20,7 +20,7 @@ accuracy. | | - `type`_ | +-------------+------------------------------------------------------------------------+ | Overridden | - `error_bubbling`_ | -| Options | | +| options | | +-------------+------------------------------------------------------------------------+ | Inherited | - `data`_ | | options | - `error_mapping`_ | diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst index 68e2c18875b..dcd598de69e 100644 --- a/reference/forms/types/text.rst +++ b/reference/forms/types/text.rst @@ -9,6 +9,9 @@ The text field represents the most basic input text field. +-------------+--------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+--------------------------------------------------------------------+ +| Overridden | - `compound`_ | +| options | | ++-------------+--------------------------------------------------------------------+ | Inherited | - `data`_ | | options | - `disabled`_ | | | - `empty_data`_ | @@ -27,6 +30,10 @@ The text field represents the most basic input text field. | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType` | +-------------+--------------------------------------------------------------------+ +Overridden Options +------------------ + +.. include:: /reference/forms/types/options/compound_type.rst.inc Inherited Options ----------------- diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst index b8765688db5..d531cc09f86 100644 --- a/reference/forms/types/time.rst +++ b/reference/forms/types/time.rst @@ -26,7 +26,9 @@ stored as a ``DateTime`` object, a string, a timestamp or an array. | | - `with_minutes`_ | | | - `with_seconds`_ | +----------------------+-----------------------------------------------------------------------------+ -| Overridden Options | - `by_reference`_ | +| Overridden options | - `by_reference`_ | +| | - `compound`_ | +| | - `data_class`_ | | | - `error_bubbling`_ | +----------------------+-----------------------------------------------------------------------------+ | Inherited | - `data`_ | @@ -139,6 +141,10 @@ by_reference The ``DateTime`` classes are treated as immutable objects. +.. include:: /reference/forms/types/options/compound_type.rst.inc + +.. include:: /reference/forms/types/options/data_class_date.rst.inc + error_bubbling ~~~~~~~~~~~~~~ diff --git a/reference/forms/types/timezone.rst b/reference/forms/types/timezone.rst index b8c6fd65d2d..6764c1b62e5 100644 --- a/reference/forms/types/timezone.rst +++ b/reference/forms/types/timezone.rst @@ -19,7 +19,7 @@ you should just use the ``choice`` type directly. | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+------------------------------------------------------------------------+ | Overridden | - `choices`_ | -| Options | | +| options | | +-------------+------------------------------------------------------------------------+ | Inherited | from the :doc:`choice ` type | | options | |