Skip to content

Commit 906e345

Browse files
weaverryanweaverryan
committed
[reference][form] Large update to the formatting of the field references so that things are more usable and readable
1 parent 8f1e280 commit 906e345

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+815
-564
lines changed

‎reference/forms/types/birthday.rst

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,39 +7,44 @@ birthday Field Type
77
A :doc:`date</reference/forms/types/date>` field that specializes in handling
88
birthdate data.
99

10-
Can be rendered as a single text box or three select boxes (month, day, and year)
10+
Can be rendered as a single text box, three text boxes (month, day, and year),
11+
or three select boxes.
1112

12-
This type is essentially the same as the ``date`` type, but with a more appropriate
13-
default for the ``years`` option. The ``years`` option defaults to 120
14-
years ago to the current year.
13+
This type is essentially the same as the :doc:`date</reference/forms/types/date>`
14+
type, but with a more appropriate default for the ``years`_ option. The ``years`_
15+
option defaults to 120 years ago to the current year.
1516
1617
+----------------------+------------------------------------------------------------------------------------------------------------------------+
1718
| Underlying Data Type | can be ``DateTime``, ``string``, ``timestamp``, or ``array`` (see the :ref:`input option <form-reference-date-input>`) |
1819
+----------------------+------------------------------------------------------------------------------------------------------------------------+
19-
| Rendered as | can be three select boxes or a text box, based on the ``widget`` option |
20+
| Rendered as | can be three select boxes or 1 or 3 text boxes, based on the `widget`_ option |
2021
+----------------------+------------------------------------------------------------------------------------------------------------------------+
21-
| Options | - ``years`` |
22+
| Options | - `years`_ |
2223
+----------------------+------------------------------------------------------------------------------------------------------------------------+
23-
| Inherited | - ``widget`` |
24-
| options | - ``input`` |
25-
| | - ``months`` |
26-
| | - ``days`` |
27-
| | - ``format`` |
28-
| | - ``pattern`` |
29-
| | - ``data_timezone`` |
30-
| | - ``user_timezone`` |
24+
| Inherited | - `widget`_ |
25+
| options | - `input`_ |
26+
| | - `months`_ |
27+
| | - `days`_ |
28+
| | - `format`_ |
29+
| | - `pattern`_ |
30+
| | - `data_timezone`_ |
31+
| | - `user_timezone`_ |
3132
+----------------------+------------------------------------------------------------------------------------------------------------------------+
3233
| Parent type | :doc:`date</reference/forms/types/date>` |
3334
+----------------------+------------------------------------------------------------------------------------------------------------------------+
3435
| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\BirthdayType` |
3536
+----------------------+------------------------------------------------------------------------------------------------------------------------+
3637

37-
Options
38-
-------
38+
Field Options
39+
-------------
3940

40-
* ``years`` [type: ``array``, default: 120 years ago to the current year ]
41-
List of years available to the year field type. This option is only
42-
relevant when the ``widget`` option is set to ``choice``.
41+
years
42+
~~~~~
43+
44+
**type**: ``array`` **default**: 120 years ago to the current year
45+
46+
List of years available to the year field type. This option is only
47+
relevant when the ``widget`` option is set to ``choice``.
4348

4449
Inherited options
4550
-----------------

‎reference/forms/types/checkbox.rst

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ if the box is unchecked, the value will be set to false.
1111
+-------------+------------------------------------------------------------------------+
1212
| Rendered as | ``input`` ``text`` field |
1313
+-------------+------------------------------------------------------------------------+
14-
| Options | - ``value`` |
14+
| Options | - `value`_ |
1515
+-------------+------------------------------------------------------------------------+
16-
| Inherited | - ``required`` |
17-
| options | - ``label`` |
18-
| | - ``read_only`` |
19-
| | - ``error_bubbling`` |
16+
| Inherited | - `required`_ |
17+
| options | - `label`_ |
18+
| | - `read_only`_ |
19+
| | - `error_bubbling`_ |
2020
+-------------+------------------------------------------------------------------------+
2121
| Parent type | :doc:`field</reference/forms/types/field>` |
2222
+-------------+------------------------------------------------------------------------+
@@ -33,12 +33,16 @@ Example Usage
3333
'required' => false,
3434
));
3535
36-
Options
37-
-------
36+
Field Options
37+
-------------
38+
39+
value
40+
~~~~~
41+
42+
**type**: ``mixed`` **default**: ``1``
3843

39-
* ``value`` [type: mixed, default: 1]
40-
The value that's actually used as the value for the checkbox. This does
41-
not affect the value that's set on your object.
44+
The value that's actually used as the value for the checkbox. This does
45+
not affect the value that's set on your object.
4246

4347
Inherited options
4448
-----------------

‎reference/forms/types/choice.rst

Lines changed: 36 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,16 @@ option.
1313
+-------------+-----------------------------------------------------------------------------+
1414
| Rendered as | can be various tags (see below) |
1515
+-------------+-----------------------------------------------------------------------------+
16-
| Options | - ``choices`` |
17-
| | - ``choice_list`` |
18-
| | - ``multiple`` |
19-
| | - ``expanded`` |
20-
| | - ``preferred_choices`` |
21-
| | - ``error_bubbling`` |
16+
| Options | - `choices`_ |
17+
| | - `choice_list`_ |
18+
| | - `multiple`_ |
19+
| | - `expanded`_ |
20+
| | - `preferred_choices`_ |
2221
+-------------+-----------------------------------------------------------------------------+
23-
| Inherited | - ``required`` |
24-
| options | - ``label`` |
25-
| | - ``read_only`` |
22+
| Inherited | - `required`_ |
23+
| options | - `label`_ |
24+
| | - `read_only`_ |
25+
| | - `error_bubbling`_ |
2626
+-------------+-----------------------------------------------------------------------------+
2727
| Parent type | :doc:`form</reference/forms/types/form>` (if expanded), ``field`` otherwise |
2828
+-------------+-----------------------------------------------------------------------------+
@@ -68,34 +68,38 @@ specify the choices for your widget.
6868

6969
.. include:: /reference/forms/types/options/empty_value.rst.inc
7070

71-
Options
72-
-------
73-
74-
* ``choices`` [type: array]
75-
This is the most basic way to specify the choices that should be used
76-
by this field. The ``choices`` option is an array, where the array key
77-
is the item value and the array value is the item's label:
78-
79-
.. code-block:: php
80-
81-
$builder->add('gender', 'choice', array(
82-
'choices' => array('m' => 'Male', 'f' => 'Female')
83-
));
84-
85-
* ``choice_list`` [type: ``Symfony\Component\Form\ChoiceList\ChoiceListInterface``]
86-
This is one way of specifying the options to be used for this field.
87-
The ``choice_list`` option must be an instance of the ``ChoiceListInterface``.
88-
For more advanced cases, a custom class that implements the interface
89-
can be created to supply the choices.
71+
Field Options
72+
-------------
73+
74+
choices
75+
~~~~~~~
76+
77+
**type**: ``array`` **default**: ``array()``
78+
79+
This is the most basic way to specify the choices that should be used
80+
by this field. The ``choices`` option is an array, where the array key
81+
is the item value and the array value is the item's label::
82+
83+
$builder->add('gender', 'choice', array(
84+
'choices' => array('m' => 'Male', 'f' => 'Female')
85+
));
86+
87+
choice_list
88+
~~~~~~~~~~~
89+
90+
**type**: ``Symfony\Component\Form\ChoiceList\ChoiceListInterface``
91+
92+
This is one way of specifying the options to be used for this field.
93+
The ``choice_list`` option must be an instance of the ``ChoiceListInterface``.
94+
For more advanced cases, a custom class that implements the interface
95+
can be created to supply the choices.
9096

9197
.. include:: /reference/forms/types/options/multiple.rst.inc
9298

9399
.. include:: /reference/forms/types/options/expanded.rst.inc
94100

95101
.. include:: /reference/forms/types/options/preferred_choices.rst.inc
96102

97-
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
98-
99103
Inherited options
100104
-----------------
101105

@@ -106,3 +110,5 @@ These options inherit from the :doc:`field</reference/forms/types/field>` type:
106110
.. include:: /reference/forms/types/options/label.rst.inc
107111

108112
.. include:: /reference/forms/types/options/read_only.rst.inc
113+
114+
.. include:: /reference/forms/types/options/error_bubbling.rst.inc

‎reference/forms/types/country.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,13 @@ you should just use the ``choice`` type directly.
2222
+-------------+-----------------------------------------------------------------------+
2323
| Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) |
2424
+-------------+-----------------------------------------------------------------------+
25-
| Inherited | - ``multiple`` |
26-
| options | - ``expanded`` |
27-
| | - ``preferred_choices`` |
28-
| | - ``error_bubbling`` |
29-
| | - ``required`` |
30-
| | - ``label`` |
31-
| | - ``read_only`` |
25+
| Inherited | - `multiple`_ |
26+
| options | - `expanded`_ |
27+
| | - `preferred_choices`_ |
28+
| | - `error_bubbling`_ |
29+
| | - `required`_ |
30+
| | - `label`_ |
31+
| | - `read_only`_ |
3232
+-------------+-----------------------------------------------------------------------+
3333
| Parent type | :doc:`choice</reference/forms/types/choice>` |
3434
+-------------+-----------------------------------------------------------------------+

‎reference/forms/types/date.rst

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,26 +8,26 @@ A field that allows the user to modify date information via a variety of
88
different HTML elements.
99

1010
The underlying data used for this field type can be a ``DateTime`` object,
11-
a string, a timestamp or an array. As long as the ``input`` option is set
12-
correctly, the field will take care of all of the details (see the ``input`` option).
11+
a string, a timestamp or an array. As long as the ``input`_ option is set
12+
correctly, the field will take care of all of the details.
1313
14-
The field can be rendered as a single text box or three select boxes (month,
15-
day, and year).
14+
The field can be rendered as a single text box, three text boxes (month,
15+
day, and year) or three select boxes (see the `widget_` option).
1616
1717
+----------------------+-----------------------------------------------------------------------------+
1818
| Underlying Data Type | can be ``DateTime``, string, timestamp, or array (see the ``input`` option) |
1919
+----------------------+-----------------------------------------------------------------------------+
2020
| Rendered as | single text box or three select fields |
2121
+----------------------+-----------------------------------------------------------------------------+
22-
| Options | - ``widget`` |
23-
| | - ``input`` |
24-
| | - ``years`` |
25-
| | - ``months`` |
26-
| | - ``days`` |
27-
| | - ``format`` |
28-
| | - ``pattern`` |
29-
| | - ``data_timezone`` |
30-
| | - ``user_timezone`` |
22+
| Options | - `widget`_ |
23+
| | - `input`_ |
24+
| | - `years`_ |
25+
| | - `months`_ |
26+
| | - `days`_ |
27+
| | - `format`_ |
28+
| | - `pattern`_ |
29+
| | - `data_timezone`_ |
30+
| | - `user_timezone`_ |
3131
+----------------------+-----------------------------------------------------------------------------+
3232
| Parent type | ``field`` (if text), ``form`` otherwise |
3333
+----------------------+-----------------------------------------------------------------------------+
@@ -65,8 +65,8 @@ you'd need to set ``input`` to ``timestamp``:
6565
The field also supports an ``array`` and ``string`` as valid ``input`` option
6666
values.
6767

68-
Options
69-
-------
68+
Field Options
69+
-------------
7070

7171
.. include:: /reference/forms/types/options/date_widget.rst.inc
7272

0 commit comments

Comments
 (0)