Skip to content

Commit

Permalink
feature #5313 Documented the overridden form options (javiereguiluz)
Browse files Browse the repository at this point in the history 
This PR was merged into the 2.3 branch.

Discussion
----------

Documented the overridden form options

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | all
| Fixed tickets | #3412

Commits
-------

84633db Fixed a typo
596a0bc Reordered two overridden options
62a11d5 Added missing types in overridden options
2b63f24 Fixed the order of the different options
e14b650 Fixed the order of the different options
0a5781b Improved the explanation about the "compoun" option
eb20dc8 Fixer minor issues
974dfef Fixed errors noticed by Wouter
32c0af1 Removed a duplicated "trim" option in the "password" type
1dc53fa Removed again a duplicated option explanation
7f8e09a Removed a duplicated option explanation in "file" type
48b402b Extracted the common "data_class" option explanation for data-related types
f44e971 Documented the overridden options of "date" type
e41b3cc Documented overridden options for "file" type
8e825d9 Documented the overridden options of the "password" type
618e11d Documented the overridden options for "time" type
7ce8191 Documented overridden options for hidden field
a8ad338 Documented overriden options for numeric types
e66ec5c Created a compound_type file because this option is shared with lots of types
8d360d9 Documented the Overridden Options of the Text type
  • Loading branch information
@weaverryan
weaverryan committed Jun 28, 2015
2 parents 314da54 + 84633db commit cd8f49b
Show file tree
Hide file tree
Showing 20 changed files with 145 additions and 32 deletions.
2 changes: 1 addition & 1 deletion reference/forms/types/country.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 </reference/forms/types/choice>` type |
| options | |
Expand Down
2 changes: 1 addition & 1 deletion reference/forms/types/currency.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 </reference/forms/types/choice>` type |
| options | |
Expand Down
8 changes: 7 additions & 1 deletion reference/forms/types/date.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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
~~~~~~~~~~~~~~

Expand Down
24 changes: 24 additions & 0 deletions reference/forms/types/datetime.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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
-----------------

Expand Down
2 changes: 1 addition & 1 deletion reference/forms/types/entity.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ objects from the database.
| | - `property`_ |
| | - `query_builder`_ |
+-------------+------------------------------------------------------------------+
| Overriden | - `choice_list`_ |
| Overridden | - `choice_list`_ |
| options | - `choices`_ |
+-------------+------------------------------------------------------------------+
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type: |
Expand Down
35 changes: 25 additions & 10 deletions reference/forms/types/file.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand All @@ -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
-----------

Expand Down Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions reference/forms/types/hidden.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand All @@ -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
~~~~~~~~~~~~~~

Expand Down
8 changes: 8 additions & 0 deletions reference/forms/types/integer.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand All @@ -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
-------------

Expand Down
2 changes: 1 addition & 1 deletion reference/forms/types/language.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 </reference/forms/types/choice>` type |
| options | |
Expand Down
2 changes: 1 addition & 1 deletion reference/forms/types/locale.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 </reference/forms/types/choice>` type |
| options | |
Expand Down
8 changes: 8 additions & 0 deletions reference/forms/types/money.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand All @@ -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
-------------

Expand Down
8 changes: 8 additions & 0 deletions reference/forms/types/number.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand All @@ -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
-------------

Expand Down
8 changes: 8 additions & 0 deletions reference/forms/types/options/compound_type.rst.inc
View file
Original file line number Diff line number Diff line change
@@ -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.
8 changes: 8 additions & 0 deletions reference/forms/types/options/data_class_date.rst.inc
View file
Original file line number Diff line number Diff line change
@@ -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``.
26 changes: 15 additions & 11 deletions reference/forms/types/password.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand All @@ -21,7 +24,6 @@ The ``password`` field renders an input password text box.
| | - `max_length`_ |
| | - `read_only`_ |
| | - `required`_ |
| | - `trim`_ |
+-------------+------------------------------------------------------------------------+
| Parent type | :doc:`text </reference/forms/types/text>` |
+-------------+------------------------------------------------------------------------+
Expand All @@ -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
-----------------
Expand Down Expand Up @@ -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.
8 changes: 8 additions & 0 deletions reference/forms/types/percent.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
+-------------+-----------------------------------------------------------------------+
Expand All @@ -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
-------------

Expand Down
2 changes: 1 addition & 1 deletion reference/forms/types/repeated.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ accuracy.
| | - `type`_ |
+-------------+------------------------------------------------------------------------+
| Overridden | - `error_bubbling`_ |
| Options | |
| options | |
+-------------+------------------------------------------------------------------------+
| Inherited | - `data`_ |
| options | - `error_mapping`_ |
Expand Down
Loading

0 comments on commit cd8f49b

Please sign in to comment.