From 906e345d04b170d3367cfc8e523239137867db0d Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 14 Jul 2011 18:37:12 -0500 Subject: [PATCH] [reference][form] Large update to the formatting of the field references so that things are more usable and readable --- reference/forms/types/birthday.rst | 43 +++++---- reference/forms/types/checkbox.rst | 24 +++-- reference/forms/types/choice.rst | 66 +++++++------ reference/forms/types/country.rst | 14 +-- reference/forms/types/date.rst | 30 +++--- reference/forms/types/datetime.rst | 67 ++++++++----- reference/forms/types/email.rst | 32 +++---- reference/forms/types/entity.rst | 95 ++++++++++++------- reference/forms/types/field.rst | 2 +- reference/forms/types/file.rst | 25 ++++- reference/forms/types/hidden.rst | 10 -- reference/forms/types/integer.rst | 54 ++++++----- reference/forms/types/language.rst | 14 +-- reference/forms/types/locale.rst | 14 +-- reference/forms/types/money.rst | 86 +++++++++-------- reference/forms/types/number.rst | 87 ++++++++++------- reference/forms/types/options/data.rst.inc | 22 ++--- .../forms/types/options/data_timezone.rst.inc | 11 ++- .../forms/types/options/date_format.rst.inc | 16 ++-- .../forms/types/options/date_input.rst.inc | 23 +++-- .../forms/types/options/date_pattern.rst.inc | 22 +++-- .../forms/types/options/date_widget.rst.inc | 18 ++-- reference/forms/types/options/days.rst.inc | 11 ++- .../types/options/error_bubbling.rst.inc | 12 ++- .../forms/types/options/expanded.rst.inc | 10 +- .../forms/types/options/grouping.rst.inc | 7 ++ reference/forms/types/options/hours.rst.inc | 9 +- .../invalid_message_parameters.rst.inc | 24 +++-- .../options/invalid_message_template.rst.inc | 20 ++-- reference/forms/types/options/label.rst.inc | 17 ++-- .../forms/types/options/max_length.rst.inc | 10 +- reference/forms/types/options/minutes.rst.inc | 9 +- reference/forms/types/options/months.rst.inc | 9 +- .../forms/types/options/multiple.rst.inc | 14 ++- .../types/options/preferred_choices.rst.inc | 50 +++++----- .../forms/types/options/read_only.rst.inc | 10 +- .../forms/types/options/required.rst.inc | 19 ++-- reference/forms/types/options/seconds.rst.inc | 9 +- reference/forms/types/options/trim.rst.inc | 14 ++- .../forms/types/options/user_timezone.rst.inc | 11 ++- .../forms/types/options/with_seconds.rst.inc | 9 +- reference/forms/types/options/years.rst.inc | 10 +- reference/forms/types/password.rst | 42 ++++---- reference/forms/types/percent.rst | 51 ++++++---- reference/forms/types/radio.rst | 24 +++-- reference/forms/types/repeated.rst | 6 +- reference/forms/types/search.rst | 32 ++++--- reference/forms/types/text.rst | 23 ++--- reference/forms/types/textarea.rst | 27 +++--- reference/forms/types/time.rst | 64 ++++++++----- reference/forms/types/timezone.rst | 14 +-- reference/forms/types/url.rst | 37 +++++--- 52 files changed, 815 insertions(+), 564 deletions(-) create mode 100644 reference/forms/types/options/grouping.rst.inc diff --git a/reference/forms/types/birthday.rst b/reference/forms/types/birthday.rst index 2fec65a5d3d..a13c55d5171 100644 --- a/reference/forms/types/birthday.rst +++ b/reference/forms/types/birthday.rst @@ -7,39 +7,44 @@ birthday Field Type A :doc:`date` field that specializes in handling birthdate data. -Can be rendered as a single text box or three select boxes (month, day, and year) +Can be rendered as a single text box, three text boxes (month, day, and year), +or three select boxes. -This type is essentially the same as the ``date`` type, but with a more appropriate -default for the ``years`` option. The ``years`` option defaults to 120 -years ago to the current year. +This type is essentially the same as the :doc:`date` +type, but with a more appropriate default for the ``years`_ option. The ``years`_ +option defaults to 120 years ago to the current year. +----------------------+------------------------------------------------------------------------------------------------------------------------+ | Underlying Data Type | can be ``DateTime``, ``string``, ``timestamp``, or ``array`` (see the :ref:`input option `) | +----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Rendered as | can be three select boxes or a text box, based on the ``widget`` option | +| Rendered as | can be three select boxes or 1 or 3 text boxes, based on the `widget`_ option | +----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Options | - ``years`` | +| Options | - `years`_ | +----------------------+------------------------------------------------------------------------------------------------------------------------+ -| Inherited | - ``widget`` | -| options | - ``input`` | -| | - ``months`` | -| | - ``days`` | -| | - ``format`` | -| | - ``pattern`` | -| | - ``data_timezone`` | -| | - ``user_timezone`` | +| Inherited | - `widget`_ | +| options | - `input`_ | +| | - `months`_ | +| | - `days`_ | +| | - `format`_ | +| | - `pattern`_ | +| | - `data_timezone`_ | +| | - `user_timezone`_ | +----------------------+------------------------------------------------------------------------------------------------------------------------+ | Parent type | :doc:`date` | +----------------------+------------------------------------------------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\BirthdayType` | +----------------------+------------------------------------------------------------------------------------------------------------------------+ -Options -------- +Field Options +------------- -* ``years`` [type: ``array``, default: 120 years ago to the current year ] - List of years available to the year field type. This option is only - relevant when the ``widget`` option is set to ``choice``. +years +~~~~~ + +**type**: ``array`` **default**: 120 years ago to the current year + +List of years available to the year field type. This option is only +relevant when the ``widget`` option is set to ``choice``. Inherited options ----------------- diff --git a/reference/forms/types/checkbox.rst b/reference/forms/types/checkbox.rst index 5b0e36cfbe5..33898477dd0 100644 --- a/reference/forms/types/checkbox.rst +++ b/reference/forms/types/checkbox.rst @@ -11,12 +11,12 @@ if the box is unchecked, the value will be set to false. +-------------+------------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+------------------------------------------------------------------------+ -| Options | - ``value`` | +| Options | - `value`_ | +-------------+------------------------------------------------------------------------+ -| Inherited | - ``required`` | -| options | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`field` | +-------------+------------------------------------------------------------------------+ @@ -33,12 +33,16 @@ Example Usage 'required' => false, )); -Options -------- +Field Options +------------- + +value +~~~~~ + +**type**: ``mixed`` **default**: ``1`` -* ``value`` [type: mixed, default: 1] - The value that's actually used as the value for the checkbox. This does - not affect the value that's set on your object. +The value that's actually used as the value for the checkbox. This does +not affect the value that's set on your object. Inherited options ----------------- diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst index f2c4ab587c4..b0a40811e57 100644 --- a/reference/forms/types/choice.rst +++ b/reference/forms/types/choice.rst @@ -13,16 +13,16 @@ option. +-------------+-----------------------------------------------------------------------------+ | Rendered as | can be various tags (see below) | +-------------+-----------------------------------------------------------------------------+ -| Options | - ``choices`` | -| | - ``choice_list`` | -| | - ``multiple`` | -| | - ``expanded`` | -| | - ``preferred_choices`` | -| | - ``error_bubbling`` | +| Options | - `choices`_ | +| | - `choice_list`_ | +| | - `multiple`_ | +| | - `expanded`_ | +| | - `preferred_choices`_ | +-------------+-----------------------------------------------------------------------------+ -| Inherited | - ``required`` | -| options | - ``label`` | -| | - ``read_only`` | +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+-----------------------------------------------------------------------------+ | Parent type | :doc:`form` (if expanded), ``field`` otherwise | +-------------+-----------------------------------------------------------------------------+ @@ -68,25 +68,31 @@ specify the choices for your widget. .. include:: /reference/forms/types/options/empty_value.rst.inc -Options -------- - -* ``choices`` [type: array] - This is the most basic way to specify the choices that should be used - by this field. The ``choices`` option is an array, where the array key - is the item value and the array value is the item's label: - - .. code-block:: php - - $builder->add('gender', 'choice', array( - 'choices' => array('m' => 'Male', 'f' => 'Female') - )); - -* ``choice_list`` [type: ``Symfony\Component\Form\ChoiceList\ChoiceListInterface``] - This is one way of specifying the options to be used for this field. - The ``choice_list`` option must be an instance of the ``ChoiceListInterface``. - For more advanced cases, a custom class that implements the interface - can be created to supply the choices. +Field Options +------------- + +choices +~~~~~~~ + +**type**: ``array`` **default**: ``array()`` + +This is the most basic way to specify the choices that should be used +by this field. The ``choices`` option is an array, where the array key +is the item value and the array value is the item's label:: + + $builder->add('gender', 'choice', array( + 'choices' => array('m' => 'Male', 'f' => 'Female') + )); + +choice_list +~~~~~~~~~~~ + +**type**: ``Symfony\Component\Form\ChoiceList\ChoiceListInterface`` + +This is one way of specifying the options to be used for this field. +The ``choice_list`` option must be an instance of the ``ChoiceListInterface``. +For more advanced cases, a custom class that implements the interface +can be created to supply the choices. .. include:: /reference/forms/types/options/multiple.rst.inc @@ -94,8 +100,6 @@ Options .. include:: /reference/forms/types/options/preferred_choices.rst.inc -.. include:: /reference/forms/types/options/error_bubbling.rst.inc - Inherited options ----------------- @@ -106,3 +110,5 @@ These options inherit from the :doc:`field` type: .. include:: /reference/forms/types/options/label.rst.inc .. include:: /reference/forms/types/options/read_only.rst.inc + +.. include:: /reference/forms/types/options/error_bubbling.rst.inc diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst index c8b9c910ca4..ff24ed259f1 100644 --- a/reference/forms/types/country.rst +++ b/reference/forms/types/country.rst @@ -22,13 +22,13 @@ you should just use the ``choice`` type directly. +-------------+-----------------------------------------------------------------------+ | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+-----------------------------------------------------------------------+ -| Inherited | - ``multiple`` | -| options | - ``expanded`` | -| | - ``preferred_choices`` | -| | - ``error_bubbling`` | -| | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | +| Inherited | - `multiple`_ | +| options | - `expanded`_ | +| | - `preferred_choices`_ | +| | - `error_bubbling`_ | +| | - `required`_ | +| | - `label`_ | +| | - `read_only`_ | +-------------+-----------------------------------------------------------------------+ | Parent type | :doc:`choice` | +-------------+-----------------------------------------------------------------------+ diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst index 3d4d5121a94..040d1687793 100644 --- a/reference/forms/types/date.rst +++ b/reference/forms/types/date.rst @@ -8,26 +8,26 @@ A field that allows the user to modify date information via a variety of different HTML elements. The underlying data used for this field type can be a ``DateTime`` object, -a string, a timestamp or an array. As long as the ``input`` option is set -correctly, the field will take care of all of the details (see the ``input`` option). +a string, a timestamp or an array. As long as the ``input`_ option is set +correctly, the field will take care of all of the details. -The field can be rendered as a single text box or three select boxes (month, -day, and year). +The field can be rendered as a single text box, three text boxes (month, +day, and year) or three select boxes (see the `widget_` option). +----------------------+-----------------------------------------------------------------------------+ | Underlying Data Type | can be ``DateTime``, string, timestamp, or array (see the ``input`` option) | +----------------------+-----------------------------------------------------------------------------+ | Rendered as | single text box or three select fields | +----------------------+-----------------------------------------------------------------------------+ -| Options | - ``widget`` | -| | - ``input`` | -| | - ``years`` | -| | - ``months`` | -| | - ``days`` | -| | - ``format`` | -| | - ``pattern`` | -| | - ``data_timezone`` | -| | - ``user_timezone`` | +| Options | - `widget`_ | +| | - `input`_ | +| | - `years`_ | +| | - `months`_ | +| | - `days`_ | +| | - `format`_ | +| | - `pattern`_ | +| | - `data_timezone`_ | +| | - `user_timezone`_ | +----------------------+-----------------------------------------------------------------------------+ | Parent type | ``field`` (if text), ``form`` otherwise | +----------------------+-----------------------------------------------------------------------------+ @@ -65,8 +65,8 @@ you'd need to set ``input`` to ``timestamp``: The field also supports an ``array`` and ``string`` as valid ``input`` option values. -Options -------- +Field Options +------------- .. include:: /reference/forms/types/options/date_widget.rst.inc diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst index c2490c4dc76..c111835ce23 100644 --- a/reference/forms/types/datetime.rst +++ b/reference/forms/types/datetime.rst @@ -15,45 +15,58 @@ data can be a ``DateTime`` object, a string, a timestamp or an array. +----------------------+-----------------------------------------------------------------------------+ | Rendered as | single text box or three select fields | +----------------------+-----------------------------------------------------------------------------+ -| Options | - ``date_widget`` | -| | - ``time_widget`` | -| | - ``input`` | -| | - ``years`` | -| | - ``months`` | -| | - ``days`` | -| | - ``format`` | -| | - ``pattern`` | -| | - ``data_timezone`` | -| | - ``user_timezone`` | +| Options | - `date_widget`_ | +| | - `time_widget`_ | +| | - `input`_ | +| | - `date_format`_ | +| | - `years`_ | +| | - `months`_ | +| | - `days`_ | +----------------------+-----------------------------------------------------------------------------+ | Parent type | :doc:`form` | +----------------------+-----------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\DateTimeType` | +----------------------+-----------------------------------------------------------------------------+ -Options +Field Options ------- -* ``date_widget`` [type: string, default: choice] - Defines the ``widget`` option for the :doc:`date` type +date_widget +~~~~~~~~~~~ -* ``time_widget`` [type: string, default: choice] - Defines the ``widget`` option for the :doc:`time` type +**type**: ``string`` **default**: ``choice`` -* ``input`` [type: string, default: ``datetime``] - The value of the input for the widget. Can be ``string``, ``datetime`` - or ``array``. The form type input value will be returned in the format - specified. The input of ``April 21th, 2011 18:15:30`` as an array would return: +Defines the ``widget`` option for the :doc:`date` type - .. code-block:: php +time_widget +~~~~~~~~~~~ - array('month' => 4, 'day' => 21, 'year' => 2011, 'hour' => 18, 'minute' => 15, 'second' => 30) +**type**: ``string`` **default**: ``choice`` -.. include:: /reference/forms/types/options/years.rst.inc +Defines the ``widget`` option for the :doc:`time` type -.. include:: /reference/forms/types/options/months.rst.inc +input +~~~~~ -.. include:: /reference/forms/types/options/days.rst.inc +**type**: ``string`` **default**: ``datetime`` + +The format of the *input* data - i.e. the format that the date is stored on +your underlying object. Valid values are: + +* ``string`` (e.g. ``2011-06-05 12:15:00``) +* ``datetime`` (a ``DateTime`` object) +* ``array`` (e.g. ``array(2011, 06, 05, 12, 15, 0)``) +* ``timestamp`` (e.g. ``1307276100``) + +The value that comes back from the form will also be normalized back into +this format. + +date_format +~~~~~~~~~~~ + +**type**: ``integer`` or ``string`` **default**: ``IntlDateFormatter::MEDIUM`` + +Defines the ``format`` option that will be passed down to the date field. .. include:: /reference/forms/types/options/hours.rst.inc @@ -61,6 +74,12 @@ Options .. include:: /reference/forms/types/options/seconds.rst.inc +.. include:: /reference/forms/types/options/years.rst.inc + +.. include:: /reference/forms/types/options/months.rst.inc + +.. include:: /reference/forms/types/options/days.rst.inc + .. include:: /reference/forms/types/options/with_seconds.rst.inc .. include:: /reference/forms/types/options/data_timezone.rst.inc diff --git a/reference/forms/types/email.rst b/reference/forms/types/email.rst index 78ae04e1dd9..c485c7ec5b5 100644 --- a/reference/forms/types/email.rst +++ b/reference/forms/types/email.rst @@ -7,20 +7,20 @@ email Field Type The ``email`` field is a text field that is rendered using the HTML5 ```` tag. -+-------------+-------------------------------------------------------------------+ -| Rendered as | ``input`` ``email`` field (a text box) | -+-------------+-------------------------------------------------------------------+ -| Inherited | - ``max_length`` | -| Options | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``trim`` | -| | - ``error_bubbling`` | -+-------------+-------------------------------------------------------------------+ -| Parent type | :doc:`text` | -+-------------+-------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\UrlType` | -+-------------+-------------------------------------------------------------------+ ++-------------+---------------------------------------------------------------------+ +| Rendered as | ``input`` ``email`` field (a text box) | ++-------------+---------------------------------------------------------------------+ +| Inherited | - `max_length`_ | +| options | - `required`_ | +| | - `label`_ | +| | - `trim`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | ++-------------+---------------------------------------------------------------------+ +| Parent type | :doc:`field` | ++-------------+---------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\EmailType` | ++-------------+---------------------------------------------------------------------+ Inherited Options ----------------- @@ -33,8 +33,8 @@ These options inherit from the :doc:`field` type: .. include:: /reference/forms/types/options/label.rst.inc -.. include:: /reference/forms/types/options/read_only.rst.inc - .. include:: /reference/forms/types/options/trim.rst.inc +.. include:: /reference/forms/types/options/read_only.rst.inc + .. include:: /reference/forms/types/options/error_bubbling.rst.inc diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index 5e187743473..16e487568f2 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -9,26 +9,26 @@ entity. For example, if you have a ``Category`` entity, you could use this field to display a ``select`` field of all, or some, of the ``Category`` objects from the database. -+----------------------+------------------------------------------------------------------+ -| Underlying Data Type | An array of entity "identifiers" (e.g. an array of selected ids) | -+----------------------+------------------------------------------------------------------+ -| Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | -+----------------------+------------------------------------------------------------------+ -| Options | - ``class`` | -| | - ``property`` | -| | - ``query_builder`` | -| | - ``multiple`` | -| | - ``expanded`` | -| | - ``preferred_choices`` | -| | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | -+----------------------+------------------------------------------------------------------+ -| Parent type | :doc:`choice` | -+----------------------+------------------------------------------------------------------+ -| Class | :class:`Symfony\\Bridge\\Doctrine\\Form\\Type\\EntityType` | -+----------------------+------------------------------------------------------------------+ ++-------------+------------------------------------------------------------------+ +| Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | ++-------------+------------------------------------------------------------------+ +| Options | - `class`_ | +| | - `property`_ | +| | - `query_builder`_ | +| | - `em`_ | ++-------------+------------------------------------------------------------------+ +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `multiple`_ | +| | - `expanded`_ | +| | - `preferred_choices`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | ++-------------+------------------------------------------------------------------+ +| Parent type | :doc:`choice` | ++-------------+------------------------------------------------------------------+ +| Class | :class:`Symfony\\Bridge\\Doctrine\\Form\\Type\\EntityType` | ++-------------+------------------------------------------------------------------+ Basic Usage ----------- @@ -66,23 +66,48 @@ option. The easiest way to use the option is as follows:: .. include:: /reference/forms/types/options/empty_value.rst.inc -Options -------- +Field Options +------------- -* ``class`` **required** [type: string] - The class of your entity (e.g. ``Acme\StoreBundle\Entity\Category``). +class +~~~~~ -* ``property`` [type: string] - This is the property that should be used for displaying the entities - as text in the HTML element. If left blank, the entity object will be - cast into a string and so must have a ``__toString()`` method. +**type**: ``string`` **required** -* ``query_builder`` [type: ``Doctrine\ORM\QueryBuilder`` or a Closure] - If specified, this is used to query the subset of options (and their - order) that should be used for the field. The value of this option can - either be a ``QueryBuilder`` object or a Closure. If using a Closure, - it should take a single argument, which is the ``EntityRepository`` of - the entity. +The class of your entity (e.g. ``Acme\StoreBundle\Entity\Category``). + +property +~~~~~~~~ + +**type**: ``string`` + +This is the property that should be used for displaying the entities +as text in the HTML element. If left blank, the entity object will be +cast into a string and so must have a ``__toString()`` method. + +query_builder +~~~~~~~~~~~~~ + +**type**: ``Doctrine\ORM\QueryBuilder`` or a Closure + +If specified, this is used to query the subset of options (and their +order) that should be used for the field. The value of this option can +either be a ``QueryBuilder`` object or a Closure. If using a Closure, +it should take a single argument, which is the ``EntityRepository`` of +the entity. + +em +~~ + +**type**: ``string`` **default**: the default entity manager + +If specified, the specified entity manager will be used to load the choices +instead of the default entity manager. + +Inherited options +----------------- + +These options inherit from the :doc:`choice` type: .. include:: /reference/forms/types/options/multiple.rst.inc @@ -90,6 +115,8 @@ Options .. include:: /reference/forms/types/options/preferred_choices.rst.inc +These options inherit from the :doc:`field` type: + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc diff --git a/reference/forms/types/field.rst b/reference/forms/types/field.rst index 59a422d66e7..cf1fbac29db 100644 --- a/reference/forms/types/field.rst +++ b/reference/forms/types/field.rst @@ -7,7 +7,7 @@ The Abstract "field" Type The ``field`` form type is not an actual field type you use, but rather functions as the parent field type for many other fields. -The ``field`` type predefines a couple of options : +The ``field`` type predefines a couple of options: .. include:: /reference/forms/types/options/data.rst.inc diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst index f855517edd6..1a8f67c4b6c 100644 --- a/reference/forms/types/file.rst +++ b/reference/forms/types/file.rst @@ -9,7 +9,10 @@ The ``file`` type represents a file input in your form. +-------------+---------------------------------------------------------------------+ | Rendered as | ``input`` ``file`` field | +-------------+---------------------------------------------------------------------+ -| Options | none | +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+---------------------------------------------------------------------+ | Parent type | :doc:`form` | +-------------+---------------------------------------------------------------------+ @@ -43,7 +46,9 @@ used to move the ``attachment`` file to a permanent location: // ... if ($form->isValid()) { - $form['attachment']->move($dir, $file); + $someNewFilename = ... + + $form['attachment']->move($dir, $someNewFilename); // ... } @@ -51,7 +56,8 @@ used to move the ``attachment`` file to a permanent location: // ... } -The ``move()`` method takes a directory and a file name as its arguments:: +The ``move()`` method takes a directory and a file name as its arguments. +You might calculate the filename in one of the following ways:: // use the original file name $file->move($dir, $file->getClientOriginalName()); @@ -71,3 +77,16 @@ before using it directly. Read the :doc:`cookbook ` for an example of how to manage a file upload associated with a Doctrine entity. + +Inherited options +----------------- + +These options inherit from the :doc:`field` type: + +.. include:: /reference/forms/types/options/required.rst.inc + +.. include:: /reference/forms/types/options/label.rst.inc + +.. include:: /reference/forms/types/options/read_only.rst.inc + +.. include:: /reference/forms/types/options/error_bubbling.rst.inc \ No newline at end of file diff --git a/reference/forms/types/hidden.rst b/reference/forms/types/hidden.rst index 3cdda1924a8..a51978892d6 100644 --- a/reference/forms/types/hidden.rst +++ b/reference/forms/types/hidden.rst @@ -9,17 +9,7 @@ The hidden type represents a hidden input field. +-------------+----------------------------------------------------------------------+ | Rendered as | ``input`` ``hidden`` field | +-------------+----------------------------------------------------------------------+ -| Options | ``error_bubbling`` | -+-------------+----------------------------------------------------------------------+ | Parent type | ``field`` | +-------------+----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\HiddenType` | +-------------+----------------------------------------------------------------------+ - -Options -------- - -* ``error_bubbling`` [type: Boolean, default: true] - - .. include:: /reference/forms/types/options/error_bubbling.rst.inc - :start-line: 1 diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst index f02f073b980..5467466e2bc 100644 --- a/reference/forms/types/integer.rst +++ b/reference/forms/types/integer.rst @@ -15,34 +15,44 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6 +-------------+-----------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+-----------------------------------------------------------------------+ -| Options | - ``rounding_mode`` | +| Options | - `rounding_mode`_ | +| | - `grouping`_ | +-------------+-----------------------------------------------------------------------+ -| Inherited | - ``required`` | -| options | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+-----------------------------------------------------------------------+ -| Parent type | ``field`` | +| Parent type | :doc:`field` | +-------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\IntegerType` | +-------------+-----------------------------------------------------------------------+ -Options -------- - -* ``rounding_mode`` [type: integer, default: ``IntegerToLocalizedStringTransformer::ROUND_DOWN``] - By default, if the user enters a non-integer number, it will be rounded - down. There are several other rounding methods, and each is a constant - on the :class:`Symfony\\Component\\Form\\Extension\\Core\\DataTransformer\\IntegerToLocalizedStringTransformer`: - - * ``IntegerToLocalizedStringTransformer::ROUND_DOWN`` - Rounding mode to round towards zero. - * ``IntegerToLocalizedStringTransformer::ROUND_FLOOR`` - Rounding mode to round towards negative infinity. - * ``IntegerToLocalizedStringTransformer::ROUND_UP`` - Rounding mode to round away from zero. - * ``IntegerToLocalizedStringTransformer::ROUND_CEILING`` - Rounding mode to round towards positive infinity. +Field Options +------------- + +rounding_mode +~~~~~~~~~~~~~ + +**type**: ``integer`` **default**: ``IntegerToLocalizedStringTransformer::ROUND_DOWN`` + +By default, if the user enters a non-integer number, it will be rounded +down. There are several other rounding methods, and each is a constant +on the :class:`Symfony\\Component\\Form\\Extension\\Core\\DataTransformer\\IntegerToLocalizedStringTransformer`: + +* ``IntegerToLocalizedStringTransformer::ROUND_DOWN`` Rounding mode to + round towards zero. + +* ``IntegerToLocalizedStringTransformer::ROUND_FLOOR`` Rounding mode to + round towards negative infinity. + +* ``IntegerToLocalizedStringTransformer::ROUND_UP`` Rounding mode to round + away from zero. + +* ``IntegerToLocalizedStringTransformer::ROUND_CEILING`` Rounding mode + to round towards positive infinity. + +.. include:: /reference/forms/types/options/grouping.rst.inc Inherited options ----------------- diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst index 06872d487b9..c048be3ca9c 100644 --- a/reference/forms/types/language.rst +++ b/reference/forms/types/language.rst @@ -23,13 +23,13 @@ you should just use the ``choice`` type directly. +-------------+------------------------------------------------------------------------+ | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+------------------------------------------------------------------------+ -| Inherited | - ``multiple`` | -| options | - ``expanded`` | -| | - ``preferred_choices`` | -| | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `multiple`_ | +| options | - `expanded`_ | +| | - `preferred_choices`_ | +| | - `error_bubbling`_ | +| | - `required`_ | +| | - `label`_ | +| | - `read_only`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`choice` | +-------------+------------------------------------------------------------------------+ diff --git a/reference/forms/types/locale.rst b/reference/forms/types/locale.rst index 678b7a1348f..cd070f637c6 100644 --- a/reference/forms/types/locale.rst +++ b/reference/forms/types/locale.rst @@ -24,13 +24,13 @@ you should just use the ``choice`` type directly. +-------------+------------------------------------------------------------------------+ | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+------------------------------------------------------------------------+ -| Inherited | - ``multiple`` | -| options | - ``expanded`` | -| | - ``preferred_choices`` | -| | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `multiple`_ | +| options | - `expanded`_ | +| | - `preferred_choices`_ | +| | - `error_bubbling`_ | +| | - `required`_ | +| | - `label`_ | +| | - `read_only`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`choice` | +-------------+------------------------------------------------------------------------+ diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst index 97f7c66cc7e..3f85f309928 100644 --- a/reference/forms/types/money.rst +++ b/reference/forms/types/money.rst @@ -14,53 +14,65 @@ how the input and output of the data is handled. +-------------+---------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+---------------------------------------------------------------------+ -| Options | - ``currency`` | -| | - ``divisor`` | -| | - ``precision`` | -| | - ``grouping`` | +| Options | - `currency`_ | +| | - `divisor`_ | +| | - `precision`_ | +| | - `grouping`_ | +-------------+---------------------------------------------------------------------+ -| Inherited | - ``required`` | -| options | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+---------------------------------------------------------------------+ | Parent type | :doc:`field` | +-------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\MoneyType` | +-------------+---------------------------------------------------------------------+ -Options -------- +Field Options +------------- -* ``currency`` [type: string, default ``EUR``] - 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 also be set to false to hide the currency symbol. +currency +~~~~~~~~ -* ``divisor`` [type: integer, default: ``1``] - If, for some reason, you need to divide your starting value by a number - before rendering it to the user, you can use the ``divisor`` option. - For example: - - .. code-block:: php +**type**: ``string`` **default**: ``EUR`` + +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. - $builder->add('price', 'money', array( - 'divisor' => 100, - )); - - In this case, if the ``price`` field is set to ``9900``, then the value - ``99`` will actually be rendered to the user. When the user submits the - value ``99``, it will be multiplied by ``100`` and ``9900`` will ultimately - be set back on your object. - -* ``precision`` [type: integer, default: 2] - For some reason, if you need some precision other than 2 decimal places, - you can modify this value. You probably won't need to do this unless, - for example, you want to round to the nearest dollar (set the precision - to ``0``). +This can also be set to false to hide the currency symbol. + +divisor +~~~~~~~ + +**type**: ``integer`` **default**: ``1`` + +If, for some reason, you need to divide your starting value by a number +before rendering it to the user, you can use the ``divisor`` option. +For example:: + + $builder->add('price', 'money', array( + 'divisor' => 100, + )); + +In this case, if the ``price`` field is set to ``9900``, then the value +``99`` will actually be rendered to the user. When the user submits the +value ``99``, it will be multiplied by ``100`` and ``9900`` will ultimately +be set back on your object. + +precision +~~~~~~~~~ + +**type**: ``integer`` **default**: ``2`` + +For some reason, if you need some precision other than 2 decimal places, +you can modify this value. You probably won't need to do this unless, +for example, you want to round to the nearest dollar (set the precision +to ``0``). + +.. include:: /reference/forms/types/options/grouping.rst.inc Inherited Options ----------------- diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst index 7e31c79a4df..59db4c9b00b 100644 --- a/reference/forms/types/number.rst +++ b/reference/forms/types/number.rst @@ -11,52 +11,67 @@ you want to use for your number. +-------------+----------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+----------------------------------------------------------------------+ -| Options | - ``rounding_mode`` | -| | - ``precision`` | -| | - ``grouping`` | +| Options | - `rounding_mode`_ | +| | - `precision`_ | +| | - `grouping`_ | +-------------+----------------------------------------------------------------------+ -| Inherited | - ``required`` | -| options | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+----------------------------------------------------------------------+ | Parent type | :doc:`field` | +-------------+----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\NumberType` | +-------------+----------------------------------------------------------------------+ -Options -------- +Field Options +------------- -* ``precision`` [type: integer, default: Locale-specific (usually around ``3``)] - This specifies how many decimals will be allowed until the field rounds - the submitted value (via ``rounding_mode``). For example, if ``precision`` - is set to ``2``, a submitted value of ``20.123`` will be rounded to, - for example, ``20.12`` (depending on your ``rounding_mode``). +precision +~~~~~~~~~ -* ``rounding_mode`` [type: integer, default: ``IntegerToLocalizedStringTransformer::ROUND_DOWN``] - 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`: +**type**: ``integer`` **default**: Locale-specific (usually around ``3``) + +This specifies how many decimals will be allowed until the field rounds +the submitted value (via ``rounding_mode``). For example, if ``precision`` +is set to ``2``, a submitted value of ``20.123`` will be rounded to, +for example, ``20.12`` (depending on your ``rounding_mode``). + +rounding_mode +~~~~~~~~~~~~~ + +**type**: ``integer`` **default**: ``IntegerToLocalizedStringTransformer::ROUND_DOWN`` + +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. - * ``IntegerToLocalizedStringTransformer::ROUND_FLOOR`` - Rounding mode to round towards negative infinity. - * ``IntegerToLocalizedStringTransformer::ROUND_UP`` - Rounding mode to round away from zero. - * ``IntegerToLocalizedStringTransformer::ROUND_CEILING`` - Rounding mode to round towards positive infinity. - * ``IntegerToLocalizedStringTransformer::ROUND_HALFDOWN`` - Rounding mode to round towards "nearest neighbor" unless both neighbors - are equidistant, in which case round down. - * ``IntegerToLocalizedStringTransformer::ROUND_HALFEVEN`` - Rounding mode to round towards the "nearest neighbor" unless both - neighbors are equidistant, in which case, round towards the even - neighbor. - * ``IntegerToLocalizedStringTransformer::ROUND_HALFUP`` - Rounding mode to round towards "nearest neighbor" unless both neighbors - are equidistant, in which case round up. +* ``IntegerToLocalizedStringTransformer::ROUND_DOWN`` Rounding mode to + round towards zero. + +* ``IntegerToLocalizedStringTransformer::ROUND_FLOOR`` Rounding mode to + round towards negative infinity. + +* ``IntegerToLocalizedStringTransformer::ROUND_UP`` Rounding mode to round + away from zero. + +* ``IntegerToLocalizedStringTransformer::ROUND_CEILING`` Rounding mode + to round towards positive infinity. + +* ``IntegerToLocalizedStringTransformer::ROUND_HALFDOWN`` Rounding mode + to round towards "nearest neighbor" unless both neighbors are equidistant, + in which case round down. + +* ``IntegerToLocalizedStringTransformer::ROUND_HALFEVEN`` Rounding mode + to round towards the "nearest neighbor" unless both neighbors are equidistant, + in which case, round towards the even neighbor. + +* ``IntegerToLocalizedStringTransformer::ROUND_HALFUP`` Rounding mode to + round towards "nearest neighbor" unless both neighbors are equidistant, + in which case round up. + +.. include:: /reference/forms/types/options/grouping.rst.inc Inherited Options ----------------- diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index 94aedfd0ff2..9e3fef10d0b 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -1,17 +1,15 @@ -* ``data`` [type: any, default: the field's initial value] - When you create a form, each field initially displays the value of the - corresponding property of the form's domain object. If you want to override - this initial value, you can set it in the data option. - - .. code-block:: php +data +~~~~ - use Symfony\Component\Form\HiddenField +**type**: mixed **default**: Defaults to field of the underlying object (if there is one) - $field = new HiddenField('token', array( - 'data' => 'abcdef', - )); +When you create a form, each field initially displays the value of the +corresponding property of the form's domain object (if an object is bound +to the form). If you want to override the initial value for the form or just +and individual field, you can set it in the data option:: - // renders abcdef - echo $field->getData(); + $builder->add('token', 'hidden', array( + 'data' => 'abcdef', + )); diff --git a/reference/forms/types/options/data_timezone.rst.inc b/reference/forms/types/options/data_timezone.rst.inc index 7970554e275..3f774a1c3f3 100644 --- a/reference/forms/types/options/data_timezone.rst.inc +++ b/reference/forms/types/options/data_timezone.rst.inc @@ -1,6 +1,9 @@ -* ``data_timezone`` [type: string, default: system default timezone] - Timezone for the data being stored. This must be one of the `PHP supported timezones`__ +data_timezone +~~~~~~~~~~~~~ -.. _PhpTimezones: http://php.net/manual/en/timezones.php +**type**: ``string`` **default**: system default timezone -__ PhpTimezones_ \ No newline at end of file +Timezone that the input data is stored in. This must be one of the +`PHP supported timezones`_ + +.. _`PHP supported timezones`: http://php.net/manual/en/timezones.php \ No newline at end of file diff --git a/reference/forms/types/options/date_format.rst.inc b/reference/forms/types/options/date_format.rst.inc index 6d791d20137..cff0a8ebd8e 100644 --- a/reference/forms/types/options/date_format.rst.inc +++ b/reference/forms/types/options/date_format.rst.inc @@ -1,6 +1,10 @@ -* ``format`` [type: integer or string, default: ``IntlDateFormatter::MEDIUM``] - Option passed to the ``IntlDateFormatter`` class, used to transform user input - into the proper format. This is critical when the ``widget`` option is - set to ``text``, and will define how to transform the input. By default, - the format is determined based on the current user locale; you can override - it by passing the format as a string. +format +~~~~~~ + +**type**: ``integer`` or ``string`` **default**: ``IntlDateFormatter::MEDIUM`` + +Option passed to the ``IntlDateFormatter`` class, used to transform user input +into the proper format. This is critical when the `widget`_ option is +set to ``single_text``, and will define how to transform the input. By default, +the format is determined based on the current user locale; you can override +it by passing the format as a string. diff --git a/reference/forms/types/options/date_input.rst.inc b/reference/forms/types/options/date_input.rst.inc index 39cbd338251..af95bb5ab97 100644 --- a/reference/forms/types/options/date_input.rst.inc +++ b/reference/forms/types/options/date_input.rst.inc @@ -1,8 +1,15 @@ -* ``input`` [type: string, default: ``datetime``] - The value of the input for the widget. Can be ``string``, ``datetime`` - or ``array``. The form type input value will be returned in the format - specified. The input of ``April 21th, 2011`` as an array would return: - - .. code-block:: php - - array('month' => 4, 'day' => 21, 'year' => 2011 ) \ No newline at end of file +input +~~~~~ + +**type**: ``string`` **default**: ``datetime`` + +The format of the *input* data - i.e. the format that the date is stored on +your underlying object. Valid values are: + +* ``string`` (e.g. ``2011-06-05``) +* ``datetime`` (a ``DateTime`` object) +* ``array`` (e.g. ``array(2011, 06, 05)``) +* ``timestamp`` (e.g. ``1307232000``) + +The value that comes back from the form will also be normalized back into +this format. \ No newline at end of file diff --git a/reference/forms/types/options/date_pattern.rst.inc b/reference/forms/types/options/date_pattern.rst.inc index 99955117c64..8df621ebe53 100644 --- a/reference/forms/types/options/date_pattern.rst.inc +++ b/reference/forms/types/options/date_pattern.rst.inc @@ -1,10 +1,14 @@ -* ``pattern`` [type: string, default: null] - This option is only relevant when the ``widget`` is set to ``choice``. - The default pattern is based off the ``format`` option, and tries to - match the characters ``M``, ``d``, and ``y`` in the format pattern. If - no match is found, the default is the string ``{{ year }}-{{ month }}-{{ day }}``. - Tokens for this option include: +pattern +~~~~~~~ - * ``{{ year }}``: Replaced with the ``year`` widget - * ``{{ month }}``: Replaced with the ``month`` widget - * ``{{ day }}``: Replaced with the ``day`` widget \ No newline at end of file +**type**: ``string`` + +This option is only relevant when the `widget`_ is set to ``choice``. +The default pattern is based off the `format`_ option, and tries to +match the characters ``M``, ``d``, and ``y`` in the format pattern. If +no match is found, the default is the string ``{{ year }}-{{ month }}-{{ day }}``. +Tokens for this option include: + + * ``{{ year }}``: Replaced with the ``year`` widget + * ``{{ month }}``: Replaced with the ``month`` widget + * ``{{ day }}``: Replaced with the ``day`` widget \ No newline at end of file diff --git a/reference/forms/types/options/date_widget.rst.inc b/reference/forms/types/options/date_widget.rst.inc index 2e22d1bcb61..8fc89e3d09e 100644 --- a/reference/forms/types/options/date_widget.rst.inc +++ b/reference/forms/types/options/date_widget.rst.inc @@ -1,10 +1,14 @@ -* ``widget`` [type: string, default: ``choice``] - Type of widget used for this form type. Can be ``text`` or ``single_text`` or ``choice``. +widget +~~~~~~ - * ``text``: renders a three field input of type text (month, day, year). +**type**: ``string`` **default**: ``choice`` - * ``single_text``: renders a single input of type text. User's input is validated - based on the ``format`` option. +The basic way in which this field should be rendered. Can be one of the following: - * ``choice``: renders three select inputs. The order of the selects - is defined in the ``pattern`` option. +* ``choice``: renders three select inputs. The order of the selects is defined + in the `pattern`_ option. + +* ``text``: renders a three field input of type text (month, day, year). + +* ``single_text``: renders a single input of type text. User's input is validated + based on the `format`_ option. diff --git a/reference/forms/types/options/days.rst.inc b/reference/forms/types/options/days.rst.inc index 4f82497696a..75fb46f2086 100644 --- a/reference/forms/types/options/days.rst.inc +++ b/reference/forms/types/options/days.rst.inc @@ -1,6 +1,9 @@ -* ``days`` [type: array, default: 1 to 31 ] - List of days available to the day field type. This option is only relevant when the ``widget`` option is set to ``choice``. +days +~~~~ - .. code-block:: php +**type**: ``array`` **default**: 1 to 31 - 'days' => range(1,31) +List of days available to the day field type. This option is only relevant +when the ``widget`` option is set to ``choice``:: + + 'days' => range(1,31) diff --git a/reference/forms/types/options/error_bubbling.rst.inc b/reference/forms/types/options/error_bubbling.rst.inc index 43402e2acdf..5442477b82a 100644 --- a/reference/forms/types/options/error_bubbling.rst.inc +++ b/reference/forms/types/options/error_bubbling.rst.inc @@ -1,4 +1,8 @@ -* ``error_bubbling`` [type: Boolean, default: false] - If true, any errors for this field will be passed to the parent field - or form. For example, if set to true on a normal field, any errors for - that field will be attached to the main form, not to the specific field. \ No newline at end of file +error_bubbling +~~~~~~~~~~~~~~ + +**type**: ``Boolean`` **default**: ``false`` + +If true, any errors for this field will be passed to the parent field +or form. For example, if set to true on a normal field, any errors for +that field will be attached to the main form, not to the specific field. \ No newline at end of file diff --git a/reference/forms/types/options/expanded.rst.inc b/reference/forms/types/options/expanded.rst.inc index 25c73c13d2a..2543527300c 100644 --- a/reference/forms/types/options/expanded.rst.inc +++ b/reference/forms/types/options/expanded.rst.inc @@ -1,3 +1,7 @@ -* ``expanded`` [type: Boolean, default: false] - If set to true, radio buttons or checkboxes will be rendered (depending - on the ``multiple`` value). If false, a select element will be rendered. \ No newline at end of file +expanded +~~~~~~~~ + +**type**: ``Boolean`` **default**: ``false`` + +If set to true, radio buttons or checkboxes will be rendered (depending +on the ``multiple`` value). If false, a select element will be rendered. \ No newline at end of file diff --git a/reference/forms/types/options/grouping.rst.inc b/reference/forms/types/options/grouping.rst.inc new file mode 100644 index 00000000000..11077d2816c --- /dev/null +++ b/reference/forms/types/options/grouping.rst.inc @@ -0,0 +1,7 @@ +grouping +~~~~~~~~ + +**type**: ``integer`` **default**: ``false`` + +The value set as the ``NumberFormatter::GROUPING_USED`` attribute when using +the PHP ``NumberFormatter`` class. \ No newline at end of file diff --git a/reference/forms/types/options/hours.rst.inc b/reference/forms/types/options/hours.rst.inc index 44da7bfa864..67cad0ae85f 100644 --- a/reference/forms/types/options/hours.rst.inc +++ b/reference/forms/types/options/hours.rst.inc @@ -1,2 +1,7 @@ -* ``hours`` [type: integer, default: 1 to 23 ] - List of hours available to the hours field type. This option is only relevant when the ``widget`` option is set to ``choice``. \ No newline at end of file +hours +~~~~~ + +**type**: ``integer`` **default**: 1 to 23 + +List of hours available to the hours field type. This option is only relevant +when the ``widget`` option is set to ``choice``. \ No newline at end of file diff --git a/reference/forms/types/options/invalid_message_parameters.rst.inc b/reference/forms/types/options/invalid_message_parameters.rst.inc index 4f69db9005e..d13bf86302c 100644 --- a/reference/forms/types/options/invalid_message_parameters.rst.inc +++ b/reference/forms/types/options/invalid_message_parameters.rst.inc @@ -1,10 +1,14 @@ -* ``invalid_message_parameters`` [type: array, default: ``array()``] - When setting the ``invalid_message_template`` option, you may need to - include some variables in the string. This can be done by adding placeholders - to that option and including the variables in this option:: - - $builder->add('some_field', 'some_type', array( - // ... - 'invalid_message_template' => 'You entered an invalid value - it should include %num% letters', - 'invalid_message_parameters' => array('%num%' => 6), - )); \ No newline at end of file +invalid_message_parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``array()`` + +When setting the ``invalid_message_template`` option, you may need to +include some variables in the string. This can be done by adding placeholders +to that option and including the variables in this option:: + + $builder->add('some_field', 'some_type', array( + // ... + 'invalid_message_template' => 'You entered an invalid value - it should include %num% letters', + 'invalid_message_parameters' => array('%num%' => 6), + )); \ No newline at end of file diff --git a/reference/forms/types/options/invalid_message_template.rst.inc b/reference/forms/types/options/invalid_message_template.rst.inc index e3b53528cd7..813709c599c 100644 --- a/reference/forms/types/options/invalid_message_template.rst.inc +++ b/reference/forms/types/options/invalid_message_template.rst.inc @@ -1,8 +1,12 @@ -* ``invalid_message_template`` [type: string, default: ``This value is not valid``] - This is the validation error message that's used when the data entered - is determined by internal validation of a field type. This might happen, - for example, if the user enters a string into a :doc:`time` - field that cannot be converted into a real time. For normal validation - messages (such as when setting a minimum length for a field), set the - validation messages with your validation rules - (:ref:`reference`). \ No newline at end of file +invalid_message_template +~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``This value is not valid`` + +This is the validation error message that's used when the data entered +is determined by internal validation of a field type. This might happen, +for example, if the user enters a string into a :doc:`time` +field that cannot be converted into a real time. For normal validation +messages (such as when setting a minimum length for a field), set the +validation messages with your validation rules +(:ref:`reference`). \ No newline at end of file diff --git a/reference/forms/types/options/label.rst.inc b/reference/forms/types/options/label.rst.inc index cdbc5183a6b..a8e99e57e62 100644 --- a/reference/forms/types/options/label.rst.inc +++ b/reference/forms/types/options/label.rst.inc @@ -1,8 +1,11 @@ -* ``label`` [type: string] - Sets the label that will be used when rendering the field. If blank, - the label will be auto-generated based on the name of the field. The label - can also be directly set inside the template: +label +~~~~~ + +**type**: ``string`` **default**: The label is "guessed" from the field name + +Sets the label that will be used when rendering the field. The label can +also be directly set inside the template: - .. code-block:: jinja - - {{ render_label(form.name, 'Name') }} \ No newline at end of file +.. code-block:: jinja + + {{ render_label(form.name, 'Your name') }} \ No newline at end of file diff --git a/reference/forms/types/options/max_length.rst.inc b/reference/forms/types/options/max_length.rst.inc index bf04c351a88..6c123bfe8b1 100644 --- a/reference/forms/types/options/max_length.rst.inc +++ b/reference/forms/types/options/max_length.rst.inc @@ -1,3 +1,7 @@ -* ``max_length`` [type: integer] - This option is used to add a ``max_length`` attribute, which is used by - some browsers to limit the amount of text in a field. \ No newline at end of file +max_length +~~~~~~~~~~ + +**type**: ``integer`` + +This option is used to add a ``max_length`` attribute, which is used by +some browsers to limit the amount of text in a field. \ No newline at end of file diff --git a/reference/forms/types/options/minutes.rst.inc b/reference/forms/types/options/minutes.rst.inc index 3b9b1e71320..250acba026b 100644 --- a/reference/forms/types/options/minutes.rst.inc +++ b/reference/forms/types/options/minutes.rst.inc @@ -1,2 +1,7 @@ -* ``minutes`` [type: integer, default: 1 to 59 ] - List of minutes available to the minutes field type. This option is only relevant when the ``widget`` option is set to ``choice``. \ No newline at end of file +minutes +~~~~~~~ + +**type**: ``integer`` **default**: 1 to 59 + +List of minutes available to the minutes field type. This option is only +relevant when the ``widget`` option is set to ``choice``. \ No newline at end of file diff --git a/reference/forms/types/options/months.rst.inc b/reference/forms/types/options/months.rst.inc index a607b2a7f5e..a53c00faeb4 100644 --- a/reference/forms/types/options/months.rst.inc +++ b/reference/forms/types/options/months.rst.inc @@ -1,2 +1,7 @@ -* ``months`` [type: array, default: 1 to 12 ] - List of months available to the month field type. This option is only relevant when the ``widget`` option is set to ``choice``. +months +~~~~~~ + +**type**: ``array`` **default**: 1 to 12 + +List of months available to the month field type. This option is only relevant +when the ``widget`` option is set to ``choice``. diff --git a/reference/forms/types/options/multiple.rst.inc b/reference/forms/types/options/multiple.rst.inc index e7db93b5d07..7de60eda538 100644 --- a/reference/forms/types/options/multiple.rst.inc +++ b/reference/forms/types/options/multiple.rst.inc @@ -1,5 +1,9 @@ -* ``multiple`` [type: Boolean, default: false] - If true, the user will be able to select multiple options (as opposed - to choosing just one option). Depending on the value of the ``expanded`` - option, this will render either a select tag or checkboxes if true and - a select tag or radio buttons if false. \ No newline at end of file +multiple +~~~~~~~~ + +**type**: ``Boolean`` **default**: ``false`` + +If true, the user will be able to select multiple options (as opposed +to choosing just one option). Depending on the value of the ``expanded`` +option, this will render either a select tag or checkboxes if true and +a select tag or radio buttons if false. The returned value will be an array. \ No newline at end of file diff --git a/reference/forms/types/options/preferred_choices.rst.inc b/reference/forms/types/options/preferred_choices.rst.inc index 5a4fb090a7b..a195fd1a940 100644 --- a/reference/forms/types/options/preferred_choices.rst.inc +++ b/reference/forms/types/options/preferred_choices.rst.inc @@ -1,28 +1,28 @@ -* ``preferred_choices`` [type: array] - If this option is specified, then a sub-set of the total number of options - will be moved to the top of the select menu. The following would move - the "Baz" option to the top, with a visual separator between it and the - rest of the options: - - .. code-block:: php - - $builder->add('foo_choices', 'choice', array( - 'choices' => array('foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz'), - 'preferred_choices' => array('baz'), - )); - - Note that preferred choices are only meaningful when rendering as a - ``select`` element (i.e. ``expanded`` is false). The preferred choices - and normal choices are separated visually by a set of dotted lines - (i.e. ``-------------------``). This can be customized when rendering - the field: +preferred_choices +~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``array()`` + +If this option is specified, then a sub-set of all of the options will be +moved to the top of the select menu. The following would move the "Baz" option +to the top, with a visual separator between it and the rest of the options:: - .. configuration-block:: + $builder->add('foo_choices', 'choice', array( + 'choices' => array('foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz'), + 'preferred_choices' => array('baz'), + )); + +Note that preferred choices are only meaningful when rendering as a ``select`` +element (i.e. ``expanded`` is false). The preferred choices and normal choices +are separated visually by a set of dotted lines (i.e. ``-------------------``). +This can be customized when rendering the field: + +.. configuration-block:: + + .. code-block:: jinja - .. code-block:: jinja - - {{ form_widget(form.foo_choices, { 'separator': '=====' }) }} + {{ form_widget(form.foo_choices, { 'separator': '=====' }) }} - .. code-block:: php - - widget($form['foo_choices'], array('separator' => '=====')) ?> + .. code-block:: php + + widget($form['foo_choices'], array('separator' => '=====')) ?> diff --git a/reference/forms/types/options/read_only.rst.inc b/reference/forms/types/options/read_only.rst.inc index 6e112fcae4d..f0b91763eb9 100644 --- a/reference/forms/types/options/read_only.rst.inc +++ b/reference/forms/types/options/read_only.rst.inc @@ -1,3 +1,7 @@ -* ``read_only`` [type: Boolean, default: false] - If this option is true, the field will be rendered with the ``disabled`` - attribute so that the field is not editable. \ No newline at end of file +read_only +~~~~~~~~~ + +**type**: ``Boolean`` **default**: ``false`` + +If this option is true, the field will be rendered with the ``disabled`` +attribute so that the field is not editable. \ No newline at end of file diff --git a/reference/forms/types/options/required.rst.inc b/reference/forms/types/options/required.rst.inc index 112d214d711..ae806c8ca4b 100644 --- a/reference/forms/types/options/required.rst.inc +++ b/reference/forms/types/options/required.rst.inc @@ -1,10 +1,13 @@ -* ``required`` [type: Boolean, default: true] - The ``required`` option can be used to render an `HTML5 required attribute`_. - Note that this is independent from validation: if you include the required - attribute on the field type but omit any required validation, the object - will appear to be valid to your application with a blank value. In other - words, this is a *nice* feature that will add client-side validation for - browsers that support HTML5. It's not, however, a replacement for true - server-side validation. +required +~~~~~~~~ + +**type**: ``Boolean`` **default**: ``true`` + +If true, an `HTML5 required attribute`_ will be rendered. The corresponding +``label`` will also render with a ``required`` class. + +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.org/forms.html \ No newline at end of file diff --git a/reference/forms/types/options/seconds.rst.inc b/reference/forms/types/options/seconds.rst.inc index c9a33610842..049597f7576 100644 --- a/reference/forms/types/options/seconds.rst.inc +++ b/reference/forms/types/options/seconds.rst.inc @@ -1,2 +1,7 @@ -* ``seconds`` [type: integer, default: 1 to 59 ] - List of seconds available to the seconds field type. This option is only relevant when the ``widget`` option is set to ``choice``. \ No newline at end of file +seconds +~~~~~~~ + +**type**: ``integer`` **default**: 1 to 59 + +List of seconds available to the seconds field type. This option is only +relevant when the ``widget`` option is set to ``choice``. \ No newline at end of file diff --git a/reference/forms/types/options/trim.rst.inc b/reference/forms/types/options/trim.rst.inc index 3615317779c..1665e5d4333 100644 --- a/reference/forms/types/options/trim.rst.inc +++ b/reference/forms/types/options/trim.rst.inc @@ -1,5 +1,9 @@ -* ``trim`` [type: Boolean, default: true] - If true, the whitespace of the submitted string value will be stripped - via the ``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. \ No newline at end of file +trim +~~~~ + +**type**: ``Boolean`` **default**: ``true`` + +If true, the whitespace of the submitted string value will be stripped +via the ``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. \ No newline at end of file diff --git a/reference/forms/types/options/user_timezone.rst.inc b/reference/forms/types/options/user_timezone.rst.inc index 2a5deb8b8b4..2e63fe711ff 100644 --- a/reference/forms/types/options/user_timezone.rst.inc +++ b/reference/forms/types/options/user_timezone.rst.inc @@ -1,6 +1,9 @@ -* ``user_timezone`` [type: string, default: system default timezone] - Timezone for the data being submitted by the user. This must be one of the `PHP supported timezones`__ +user_timezone +~~~~~~~~~~~~~ -.. _PhpTimezones: http://php.net/manual/en/timezones.php +**type**: ``string`` **default**: system default timezone -__ PhpTimezones_ \ No newline at end of file +Timezone for how the data should be shown to the user (and therefore also +the data that the user submits). This must be one of the `PHP supported timezones`_ + +.. _`PHP supported timezones`: http://php.net/manual/en/timezones.php \ No newline at end of file diff --git a/reference/forms/types/options/with_seconds.rst.inc b/reference/forms/types/options/with_seconds.rst.inc index 6328109fe8b..684a748fb3e 100644 --- a/reference/forms/types/options/with_seconds.rst.inc +++ b/reference/forms/types/options/with_seconds.rst.inc @@ -1,2 +1,7 @@ -* ``with_seconds`` [type: Boolean, default: false] - Whether or not to include seconds in the input. This will result in an additional input to capture seconds. \ No newline at end of file +with_seconds +~~~~~~~~~~~~ + +**type**: ``Boolean`` **default**: ``false`` + +Whether or not to include seconds in the input. This will result in an additional +input to capture seconds. \ No newline at end of file diff --git a/reference/forms/types/options/years.rst.inc b/reference/forms/types/options/years.rst.inc index ccbc9290391..7b4f30f2623 100644 --- a/reference/forms/types/options/years.rst.inc +++ b/reference/forms/types/options/years.rst.inc @@ -1,3 +1,7 @@ -* ``years`` [type: array, default: five years before to five years after the current year ] - List of years available to the year field type. This option is only - relevant when the ``widget`` option is set to ``choice``. +years +~~~~~ + +**type**: ``array`` **default**: five years before to five years after the current year + +List of years available to the year field type. This option is only relevant +when the ``widget`` option is set to ``choice``. diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst index d43f4db5f59..cdea69c117f 100644 --- a/reference/forms/types/password.rst +++ b/reference/forms/types/password.rst @@ -9,44 +9,48 @@ The ``password`` field renders an input password text box. +-------------+------------------------------------------------------------------------+ | Rendered as | ``input`` ``password`` field | +-------------+------------------------------------------------------------------------+ -| Options | - ``always_empty`` | -| | - ``max_length`` | -| | - ``trim`` | +| Options | - `always_empty`_ | +-------------+------------------------------------------------------------------------+ -| Inherited | - ``required`` | -| options | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `max_length`_ | +| options | - `required`_ | +| | - `label`_ | +| | - `trim`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`text` | +-------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\PasswordType` | +-------------+------------------------------------------------------------------------+ -Options -------- +Field Options +------------- -* ``always_empty`` [type: Boolean, default: true] - If set to true, the field will *always* render blank, even if the corresponding - field has a value. When set to false, the password field will be rendered - with the ``value`` attribute set to its true value. - - 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. +always_empty +~~~~~~~~~~~~ -.. include:: /reference/forms/types/options/max_length.rst.inc +**type**: ``Boolean`` **default**: ``true`` -.. include:: /reference/forms/types/options/trim.rst.inc +If set to true, the field will *always* render blank, even if the corresponding +field has a value. When set to false, the password field will be rendered +with the ``value`` attribute set to its true value. + +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. Inherited Options ----------------- These options inherit from the :doc:`field` type: +.. include:: /reference/forms/types/options/max_length.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc +.. include:: /reference/forms/types/options/trim.rst.inc + .. include:: /reference/forms/types/options/read_only.rst.inc -.. include:: /reference/forms/types/options/error_bubbling.rst.inc +.. include:: /reference/forms/types/options/error_bubbling.rst.inc \ No newline at end of file diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst index 3b14051395a..7e839a9f2f7 100644 --- a/reference/forms/types/percent.rst +++ b/reference/forms/types/percent.rst @@ -15,12 +15,13 @@ This field adds a percentage sign "``%``" after the input box. +-------------+-----------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+-----------------------------------------------------------------------+ -| Options | - ``type`` | +| Options | - `type`_ | +| | - `precision`_ | +-------------+-----------------------------------------------------------------------+ -| Inherited | - ``required`` | -| options | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `required`_ | +| options | - `label`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+-----------------------------------------------------------------------+ | Parent type | :doc:`field` | +-------------+-----------------------------------------------------------------------+ @@ -30,20 +31,33 @@ This field adds a percentage sign "``%``" after the input box. Options ------- -* ``type`` [type: string, default: ``fractional``] - This controls how your data is stored on your object. For example, a percentage - corresponding to "55%", might be stored as ``.55`` or ``55`` on your - object. The two "types" handle these two cases: +type +~~~~ + +**type**: ``string`` **default**: ``fractional`` + +This controls how your data is stored on your object. For example, a percentage +corresponding to "55%", might be stored as ``.55`` or ``55`` on your +object. The two "types" handle these two cases: - * ``fractional`` - If your data is stored as a decimal (e.g. ``.55``), use this type. - The data will be multiplied by ``100`` before being shown to the - user (e.g. ``55``). The submitted data will be divided by ``100`` - on form submit so that the decimal value is stored (``.55``); - * ``integer`` - If your data is stored as an integer (e.g. 55), then use this option. - The raw value (``55``) is shown to the user and stored on your object. - Note that this only works for integer values. +* ``fractional`` + If your data is stored as a decimal (e.g. ``.55``), use this type. + The data will be multiplied by ``100`` before being shown to the + user (e.g. ``55``). The submitted data will be divided by ``100`` + on form submit so that the decimal value is stored (``.55``); + +* ``integer`` + If your data is stored as an integer (e.g. 55), then use this option. + The raw value (``55``) is shown to the user and stored on your object. + Note that this only works for integer values. + +precision +~~~~~~~~~ + +**type**: ``integer`` **default**: ``0`` + +By default, the input numbers are are rounded. To allow for more decimal +places, use this option. Inherited Options ----------------- @@ -57,3 +71,4 @@ These options inherit from the :doc:`field` type: .. include:: /reference/forms/types/options/read_only.rst.inc .. include:: /reference/forms/types/options/error_bubbling.rst.inc + diff --git a/reference/forms/types/radio.rst b/reference/forms/types/radio.rst index 77ccbb996e7..487073973c8 100644 --- a/reference/forms/types/radio.rst +++ b/reference/forms/types/radio.rst @@ -15,24 +15,28 @@ If you want to have a Boolean field, use :doc:`checkbox` | +-------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\RadioType` | +-------------+---------------------------------------------------------------------+ -Options -------- +Field Options +------------- -* ``value`` [type: mixed, default: 1] - The value that's actually used as the value for the radio button. This does - not affect the value that's set on your object. +value +~~~~~ + +**type**: ``mixed`` **default**: ``1`` + +The value that's actually used as the value for the radio button. This does +not affect the value that's set on your object. Inherited Options ----------------- diff --git a/reference/forms/types/repeated.rst b/reference/forms/types/repeated.rst index 4efcb6150de..0b05a09c9f6 100644 --- a/reference/forms/types/repeated.rst +++ b/reference/forms/types/repeated.rst @@ -17,9 +17,9 @@ accuracy. | | - `first_name`_ | | | - `second_name`_ | +-------------+------------------------------------------------------------------------+ -| Inherited | - ``invalid_message_template`` | -| options | - ``invalid_message_parameters`` | -| | - ``error_bubbling`` | +| Inherited | - `invalid_message_template`_ | +| options | - `invalid_message_parameters`_ | +| | - `error_bubbling`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`field` | +-------------+------------------------------------------------------------------------+ diff --git a/reference/forms/types/search.rst b/reference/forms/types/search.rst index 2cd187b99e6..bd888e9c5d8 100644 --- a/reference/forms/types/search.rst +++ b/reference/forms/types/search.rst @@ -4,28 +4,30 @@ search Field Type ================= -The ``search`` field is a text field that is used for the entry of searches, -and is rendered by default using a ``search`` input type which can be used -by user agents to present a specialized rendering for search boxes (such -as the `one used in WebKit-based browsers`_). +This renders an ```` field, which is a text box with +special functionality supported by some browsers. + +Read about the input search field at `DiveIntoHTML5.org`_ +-------------+----------------------------------------------------------------------+ | Rendered as | ``input search`` field | +-------------+----------------------------------------------------------------------+ -| Inherited | - ``max_length`` | -| options | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``trim`` | -| | - ``error_bubbling`` | +| Inherited | - `max_length`_ | +| options | - `required`_ | +| | - `label`_ | +| | - `trim`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+----------------------------------------------------------------------+ | Parent type | :doc:`text` | +-------------+----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\SearchType` | +-------------+----------------------------------------------------------------------+ -Options -------- +Inherited Options +----------------- + +These options inherit from the :doc:`field` type: .. include:: /reference/forms/types/options/max_length.rst.inc @@ -33,10 +35,10 @@ Options .. include:: /reference/forms/types/options/label.rst.inc -.. include:: /reference/forms/types/options/read_only.rst.inc - .. include:: /reference/forms/types/options/trim.rst.inc +.. include:: /reference/forms/types/options/read_only.rst.inc + .. include:: /reference/forms/types/options/error_bubbling.rst.inc -.. _`one used in WebKit-based browsers`: http://alexking.org/blog/2006/11/12/safari-search-boxes +.. _`DiveIntoHTML5.org`: http://diveintohtml5.org/forms.html#type-search diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst index 13eb3f1a1f3..eaca7bb0598 100644 --- a/reference/forms/types/text.rst +++ b/reference/forms/types/text.rst @@ -9,35 +9,32 @@ The text field represents the most basic input text field. +-------------+--------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+--------------------------------------------------------------------+ -| Options | - ``max_length`` | -+-------------+--------------------------------------------------------------------+ -| Inherited | - ``trim`` | -| options | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `max_length`_ | +| options | - `required`_ | +| | - `label`_ | +| | - `trim`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+--------------------------------------------------------------------+ | Parent type | :doc:`field` | +-------------+--------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType` | +-------------+--------------------------------------------------------------------+ -Options -------- - -.. include:: /reference/forms/types/options/max_length.rst.inc - -.. include:: /reference/forms/types/options/trim.rst.inc Inherited Options ----------------- These options inherit from the :doc:`field` type: +.. include:: /reference/forms/types/options/max_length.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc +.. include:: /reference/forms/types/options/trim.rst.inc + .. include:: /reference/forms/types/options/read_only.rst.inc .. include:: /reference/forms/types/options/error_bubbling.rst.inc diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst index e95fcd34ab4..3b77ddf9b97 100644 --- a/reference/forms/types/textarea.rst +++ b/reference/forms/types/textarea.rst @@ -7,37 +7,34 @@ textarea Field Type Renders a ``textarea`` HTML element. +-------------+------------------------------------------------------------------------+ -| Rendered as | ``textarea`` field | +| Rendered as | ``textarea`` tag | +-------------+------------------------------------------------------------------------+ -| Options | - ``max_length`` | -+-------------+------------------------------------------------------------------------+ -| Inherited | - ``trim`` | -| options | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `max_length`_ | +| options | - `required`_ | +| | - `label`_ | +| | - `trim`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`field` | +-------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TextareaType` | +-------------+------------------------------------------------------------------------+ -Options -------- - -.. include:: /reference/forms/types/options/max_length.rst.inc - -.. include:: /reference/forms/types/options/trim.rst.inc - Inherited Options ----------------- These options inherit from the :doc:`field` type: +.. include:: /reference/forms/types/options/max_length.rst.inc + .. include:: /reference/forms/types/options/required.rst.inc .. include:: /reference/forms/types/options/label.rst.inc +.. include:: /reference/forms/types/options/trim.rst.inc + .. include:: /reference/forms/types/options/read_only.rst.inc .. include:: /reference/forms/types/options/error_bubbling.rst.inc + diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst index 5b35ee2ece4..c9325da3418 100644 --- a/reference/forms/types/time.rst +++ b/reference/forms/types/time.rst @@ -6,23 +6,23 @@ time Field Type A field to capture time input. -This can be rendered as a text field or a series of choice fields. The underlying -data can be stored as a ``DateTime`` object, a string, a timestamp or an -array. +This can be rendered as a text field, a series of text fields (e.g. hour, +minute, second) or a series of select fields. The underlying data can be stored +as a ``DateTime`` object, a string, a timestamp or an array. +----------------------+-----------------------------------------------------------------------------+ | Underlying Data Type | can be ``DateTime``, string, timestamp, or array (see the ``input`` option) | +----------------------+-----------------------------------------------------------------------------+ | Rendered as | can be various tags (see below) | +----------------------+-----------------------------------------------------------------------------+ -| Options | - ``widget`` | -| | - ``input`` | -| | - ``with_seconds`` | -| | - ``hours`` | -| | - ``minutes`` | -| | - ``seconds`` | -| | - ``data_timezone`` | -| | - ``user_timezone`` | +| Options | - `widget`_ | +| | - `input`_ | +| | - `with_seconds`_ | +| | - `hours`_ | +| | - `minutes`_ | +| | - `seconds`_ | +| | - `data_timezone`_ | +| | - `user_timezone`_ | +----------------------+-----------------------------------------------------------------------------+ | Parent type | form | +----------------------+-----------------------------------------------------------------------------+ @@ -60,22 +60,38 @@ you'd need to set ``input`` to ``timestamp``: The field also supports an ``array`` and ``string`` as valid ``input`` option values. -Options -------- +Field Options +------------- -* ``widget`` [type: string, default: ``choice``] - Type of widget used for this form type. Can be ``text`` or ``choice``. - - * ``text``: renders a single input of type text. User's input is validated based on the ``format`` option. - * ``choice``: renders two select inputs (three select inputs if ``with_seconds`` is set to ``true``). +widget +~~~~~~ -* ``input`` [type: string, default: ``datetime``] - The value of the input for the widget. Can be ``string``, ``datetime`` or ``array``. The form type input value will be returned - in the format specified. The value "12:30" with the ``input`` option set to ``array`` would return: - - .. code-block:: php +**type**: ``string`` **default**: ``choice`` - array('hour' => '12', 'minute' => '30' ) +The basic way in which this field should be rendered. Can be one of the following: + +* ``choice``: renders two (or three if `with_seconds`_ is true) select inputs. + +* ``text``: renders a two or three text inputs (hour, minute, second). + +* ``single_text``: renders a single input of type text. User's input is validated +based on the `format`_ option. + +input +~~~~~ + +**type**: ``string`` **default**: ``datetime`` + +The format of the *input* data - i.e. the format that the date is stored on +your underlying object. Valid values are: + +* ``string`` (e.g. ``12:17:26``) +* ``datetime`` (a ``DateTime`` object) +* ``array`` (e.g. ``array(12, 17, 26)``) +* ``timestamp`` (e.g. ``1307232000``) + +The value that comes back from the form will also be normalized back into +this format. .. include:: /reference/forms/types/options/with_seconds.rst.inc diff --git a/reference/forms/types/timezone.rst b/reference/forms/types/timezone.rst index 96316cc71a4..61dc9e9f429 100644 --- a/reference/forms/types/timezone.rst +++ b/reference/forms/types/timezone.rst @@ -18,13 +18,13 @@ you should just use the ``choice`` type directly. +-------------+------------------------------------------------------------------------+ | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) | +-------------+------------------------------------------------------------------------+ -| Inherited | - ``multiple`` | -| options | - ``expanded`` | -| | - ``preferred_choices`` | -| | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``error_bubbling`` | +| Inherited | - `multiple`_ | +| options | - `expanded`_ | +| | - `preferred_choices`_ | +| | - `error_bubbling`_ | +| | - `required`_ | +| | - `label`_ | +| | - `read_only`_ | +-------------+------------------------------------------------------------------------+ | Parent type | :doc:`choice` | +-------------+------------------------------------------------------------------------+ diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst index b04133fc00d..74dbb26c4b9 100644 --- a/reference/forms/types/url.rst +++ b/reference/forms/types/url.rst @@ -12,26 +12,35 @@ have a protocol. | Rendered as | ``input url`` field | +-------------+-------------------------------------------------------------------+ | Options | - ``default_protocol`` | -| | - ``max_length`` | -| | - ``required`` | -| | - ``label`` | -| | - ``read_only`` | -| | - ``trim`` | -| | - ``error_bubbling`` | ++-------------+-------------------------------------------------------------------+ +| Inherited | - `max_length`_ | +| options | - `required`_ | +| | - `label`_ | +| | - `trim`_ | +| | - `read_only`_ | +| | - `error_bubbling`_ | +-------------+-------------------------------------------------------------------+ | Parent type | :doc:`text` | +-------------+-------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\UrlType` | +-------------+-------------------------------------------------------------------+ -Options -------- +Field Options +------------- + +default_protocol +~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``http`` + +If a value is submitted that doesn't begin with some protocol (e.g. ``http://``, +``ftp://``, etc), this protocol will be prepended to the string when +the data is bound to the form. -* ``default_protocol`` [type: string, default: ``http``] +Inherited Options +----------------- - If a value is submitted that doesn't begin with some protocol (e.g. ``http://``, - ``ftp://``, etc), this protocol will be prepended to the string when - the data is bound to the form. +These options inherit from the :doc:`field` type: .. include:: /reference/forms/types/options/max_length.rst.inc @@ -39,8 +48,8 @@ Options .. include:: /reference/forms/types/options/label.rst.inc -.. include:: /reference/forms/types/options/read_only.rst.inc - .. include:: /reference/forms/types/options/trim.rst.inc +.. include:: /reference/forms/types/options/read_only.rst.inc + .. include:: /reference/forms/types/options/error_bubbling.rst.inc