Skip to content

Commit 626b8ab

Browse files
weaverryanweaverryan
committed
Merge branch 'improve_form_choice_reference' of https://github.com/althaus/symfony-docs into form-choice-options
* 'improve_form_choice_reference' of https://github.com/althaus/symfony-docs: Fixed preferred choices example Fixed linebreaking Added choices_as_values description [amend] Added choices_as_values description Added choice_loader basics Added basic choice type changes
2 parents 4676607 + 31134f5 commit 626b8ab

File tree

7 files changed

+270
-22
lines changed

7 files changed

+270
-22
lines changed

‎reference/forms/types/choice.rst

Lines changed: 103 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,17 @@ option.
1515
+-------------+------------------------------------------------------------------------------+
1616
| Options | - `choices`_ |
1717
| | - `choice_list`_ |
18+
| | - `choice_loader`_ |
19+
| | - `choice_label`_ |
20+
| | - `choice_name`_ |
21+
| | - `choice_value`_ |
22+
| | - `choice_attr`_ |
23+
| | - `choices_as_values`_ |
1824
| | - `placeholder`_ |
1925
| | - `expanded`_ |
2026
| | - `multiple`_ |
2127
| | - `preferred_choices`_ |
28+
| | - `group_by`_ |
2229
+-------------+------------------------------------------------------------------------------+
2330
| Overridden | - `compound`_ |
2431
| options | - `empty_data`_ |
@@ -51,7 +58,8 @@ user sees on the form (e.g. ``Male``).
5158
.. code-block:: php
5259
5360
$builder->add('gender', 'choice', array(
54-
'choices' => array('m' => 'Male', 'f' => 'Female'),
61+
'choices' => array('Male' => 'm', 'Female' => 'f'),
62+
'choices_as_values' => true,
5563
'required' => false,
5664
));
5765
@@ -61,15 +69,33 @@ of checkboxes depending on the ``expanded`` option::
6169

6270
$builder->add('availability', 'choice', array(
6371
'choices' => array(
64-
'morning' => 'Morning',
65-
'afternoon' => 'Afternoon',
66-
'evening' => 'Evening',
72+
'Morning' => 'morning',
73+
'Afternoon' => 'afternoon',
74+
'Evening' => 'evening',
75+
),
76+
'choices_as_values' => true,
77+
'multiple' => true,
78+
));
79+
80+
If you rely on your option value attribute (e.g. for JavaScript) you need
81+
to set ``choice_value``, otherwise the option values will be mapped to integer
82+
values::
83+
84+
$builder->add('availability', 'choice', array(
85+
'choices' => array(
86+
'Morning' => 'morning',
87+
'Afternoon' => 'afternoon',
88+
'Evening' => 'evening',
6789
),
90+
'choices_as_values' => true,
91+
'choice_value' => function ($choice) {
92+
return $choice;
93+
},
6894
'multiple' => true,
6995
));
7096

71-
You can also use the ``choice_list`` option, which takes an object that
72-
can specify the choices for your widget.
97+
You can also use the ``choice_loader`` option, which can be used to load
98+
the list only partially in cases where a fully-loaded list is not necessary.
7399

74100
.. _forms-reference-choice-tags:
75101

@@ -85,19 +111,59 @@ choices
85111

86112
This is the most basic way to specify the choices that should be used
87113
by this field. The ``choices`` option is an array, where the array key
88-
is the item value and the array value is the item's label::
114+
is the item's label and the array value is the item's value::
89115

90116
$builder->add('gender', 'choice', array(
91-
'choices' => array('m' => 'Male', 'f' => 'Female'),
117+
'choices' => array('Male' => 'm', 'Female' => 'f'),
118+
'choices_as_values' => true,
92119
));
93120

94-
.. tip::
121+
.. versionadded:: 2.7
122+
Symfony 2.7 introduced the option to flip the ``choices`` array to be
123+
able to use values that are not integers or strings (but e.g. floats
124+
or booleans).
125+
126+
choices_as_values
127+
~~~~~~~~~~~~~~~~~
95128

96-
When the values to choose from are not integers or strings (but e.g.
97-
floats or booleans), you should use the `choice_list`_ option instead.
98-
With this option you are able to keep the original data format which
99-
is important to ensure that the user input is validated properly and
100-
useless database updates caused by a data type mismatch are avoided.
129+
**type**: ``boolean`` **default**: false
130+
131+
.. versionadded:: 2.7
132+
133+
The ``choices_as_values`` option of ChoiceType was introduced in Symfony
134+
2.7.
135+
136+
The ``choices_as_values`` option was introduced to ensure backward compatibility
137+
with the modified handling of the ``choices`` optio. Being set to ``false``
138+
the choices array will be read as values mapping the keys. Setting the option
139+
to ``true`` will enable the new handling of the choices mapping keys to
140+
values.
141+
142+
* Before 2.7::
143+
144+
$builder->add('gender', 'choice', array(
145+
'choices' => array('m' => 'Male', 'f' => 'Female'),
146+
'choices_as_values' => false,
147+
));
148+
149+
* Optional since 2.7::
150+
151+
$builder->add('gender', 'choice', array(
152+
'choices' => array('Male' => 'm', 'Female' => 'f'),
153+
'choices_as_values' => true,
154+
));
155+
156+
* Default for 3.0::
157+
158+
$builder->add('gender', 'choice', array(
159+
'choices' => array('Male' => 'm', 'Female' => 'f'),
160+
));
161+
162+
.. caution::
163+
164+
The ``choices_as_values`` option will be removed in Symfony 3.0,
165+
where the choices will be passed in the values of the ``choices``
166+
option by default.
101167

102168
choice_list
103169
~~~~~~~~~~~
@@ -141,6 +207,19 @@ But don't be confused! If ``Full`` is selected (value ``0`` in HTML), ``1``
141207
will be returned in your form. If ``Almost empty`` is selected (value ``2``
142208
in HTML), ``0.1`` will be returned.
143209

210+
choice_loader
211+
~~~~~~~~~~~~~
212+
213+
.. versionadded:: 2.7
214+
215+
The ``choice_loader`` option of ChoiceType was introduced in Symfony
216+
2.7.
217+
218+
The choice loader can be used to load the list only partially in cases where
219+
a fully-loaded list is not necessary.
220+
221+
**type**: :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\ChoiceLoaderInterface`
222+
144223
.. include:: /reference/forms/types/options/placeholder.rst.inc
145224

146225
.. include:: /reference/forms/types/options/expanded.rst.inc
@@ -149,6 +228,16 @@ in HTML), ``0.1`` will be returned.
149228

150229
.. include:: /reference/forms/types/options/preferred_choices.rst.inc
151230

231+
.. include:: /reference/forms/types/options/choice_label.rst.inc
232+
233+
.. include:: /reference/forms/types/options/choice_name.rst.inc
234+
235+
.. include:: /reference/forms/types/options/choice_value.rst.inc
236+
237+
.. include:: /reference/forms/types/options/choice_attr.rst.inc
238+
239+
.. include:: /reference/forms/types/options/group_by.rst.inc
240+
152241
Overridden Options
153242
------------------
154243

‎reference/forms/types/options/choice_attr.rst.inc

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
choice_attr
2+
~~~~~~~~~~~
3+
4+
.. versionadded:: 2.7
5+
The ``choice_attr`` option was introduced in Symfony 2.7.
6+
7+
**type**: ``array``, ``callable`` or ``string`` **default**: ``array()``
8+
9+
Returns the additional HTML attributes for choices. Can be an array, a callable
10+
(like for ``choice_label``) or a property path.
11+
12+
If an array, the keys of the ``choices`` array must be used as keys::
13+
14+
$builder->add('attending', 'choice', array(
15+
'choices' => array(
16+
'Yes' => true,
17+
'No' => false,
18+
'Maybe' => null,
19+
),
20+
'choices_as_values' => true,
21+
'choice_attr' => array(
22+
'Maybe' => array('class' => 'greyed-out'),
23+
),
24+
));

‎reference/forms/types/options/choice_label.rst.inc

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
choice_label
2+
~~~~~~~~~~~~
3+
4+
.. versionadded:: 2.7
5+
The ``choice_label`` option was introduced in Symfony 2.7.
6+
7+
**type**: ``callable`` or ``string`` **default**: ``null``
8+
9+
Returns the label for each choice. Can be a callable (which receives the
10+
choice as first and the key of the ``choices`` array as second argument)
11+
or a property path.
12+
13+
If ``null``, the keys of the ``choices`` array are used as labels.
14+
15+
* Using a callable to set the label::
16+
17+
$builder->add('attending', 'choice', array(
18+
'choices' => array(
19+
'yes' => true,
20+
'no' => false,
21+
'maybe' => null,
22+
),
23+
'choices_as_values' => true,
24+
'choice_label' => function ($choice, $key) {
25+
return 'form.choice.'.$key;
26+
},
27+
));
28+
29+
* Using a property path to set the label::
30+
31+
$builder->add('attending', 'choice', array(
32+
'choices' => array(
33+
Status::getInstance(Status::YES),
34+
Status::getInstance(Status::NO),
35+
Status::getInstance(Status::MAYBE),
36+
),
37+
'choices_as_values' => true,
38+
'choice_label' => 'displayName',
39+
));

‎reference/forms/types/options/choice_name.rst.inc

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
choice_name
2+
~~~~~~~~~~~
3+
4+
.. versionadded:: 2.7
5+
The ``choice_name`` option was introduced in Symfony 2.7.
6+
7+
**type**: ``callable`` or ``string`` **default**: ``null``
8+
9+
Returns the form name for each choice. That name is used as name of the
10+
checkbox/radio form for this choice. It is also used as index of the choice
11+
views in the template. Can be a callable (like for ``choice_label``) or
12+
a property path.
13+
14+
The generated names must be valid form names, i.e. contain alpha-numeric
15+
symbols, underscores, hyphens and colons only. They must start with an
16+
alpha-numeric symbol or an underscore.
17+
18+
If ``null``, an incrementing integer is used as name.

‎reference/forms/types/options/choice_value.rst.inc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
choice_value
2+
~~~~~~~~~~~~
3+
4+
.. versionadded:: 2.7
5+
The ``choice_value`` option was introduced in Symfony 2.7.
6+
7+
**type**: ``callable`` or ``string`` **default**: ``null``
8+
9+
Returns the string value for each choice. This value is displayed in the
10+
``value`` attributes and submitted in the POST/PUT requests. Can be a
11+
callable (like for ``choice_label``) or a property path.
12+
13+
If ``null``, an incrementing integer is used as value.

‎reference/forms/types/options/group_by.rst.inc

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
group_by
2+
~~~~~~~~
3+
4+
.. versionadded:: 2.7
5+
The ``group_by`` option was introduced in Symfony 2.7.
6+
7+
**type**: ``array``, ``callable`` or ``string`` **default**: ``null``
8+
9+
Returns the grouping used for the choices. Can be an array/Traversable,
10+
a callable (like for ``choice_label``) or a property path.
11+
12+
The return values of the callable/property path are used as group labels.
13+
If ``null`` is returned, a choice is not grouped.
14+
15+
If ``null``, the structure of the ``choices`` array is used to construct
16+
the groups::
17+
18+
$builder->add('attending', 'choice', array(
19+
'choices' => array(
20+
'Decided' => array(
21+
'Yes' => true,
22+
'No' => false,
23+
),
24+
'Undecided' => array(
25+
'Maybe' => null,
26+
),
27+
),
28+
'choices_as_values' => true,
29+
));

‎reference/forms/types/options/preferred_choices.rst.inc

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,52 @@
11
preferred_choices
22
~~~~~~~~~~~~~~~~~
33

4-
**type**: ``array`` **default**: ``array()``
4+
**type**: ``array``, ``callable`` or ``string`` **default**: ``array()``
55

6-
If this option is specified, then a sub-set of all of the options will be
7-
moved to the top of the select menu. The following would move the "Baz"
8-
option to the top, with a visual separator between it and the rest of the
9-
options::
6+
If this option is specified as an array, then a sub-set of all of the options
7+
will be moved to the top of the select menu. The following would move the
8+
"Yes" option to the top, with a visual separator between it and the rest
9+
of the options::
1010

11-
$builder->add('foo_choices', 'choice', array(
12-
'choices' => array('foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz'),
13-
'preferred_choices' => array('baz'),
11+
$builder->add('attending', 'choice', array(
12+
'choices' => array(
13+
'Yes' => true,
14+
'No' => false,
15+
'Maybe' => null,
16+
),
17+
'choices_as_values' => true,
18+
'preferred_choices' => array(true),
19+
));
20+
21+
.. versionadded:: 2.7
22+
Setting a callable or propery path was introduced in Symfony 2.7.
23+
24+
If this option is specified as a callable, then the the preferred options
25+
are computed by the callback::
26+
27+
$builder->add('attending', 'choice', array(
28+
'choices' => array(
29+
'Yes' => true,
30+
'No' => false,
31+
'Maybe' => null,
32+
),
33+
'choices_as_values' => true,
34+
'preferred_choices' => function ($choice, $key) {
35+
return true === $choice;
36+
},
37+
));
38+
39+
If this option is specified as a property path, then the preferred options
40+
are taken from the objects::
41+
42+
$builder->add('attending', 'choice', array(
43+
'choices' => array(
44+
'Yes' => Status::getInstance(Status::YES),
45+
'No' => Status::getInstance(Status::NO),
46+
'Maybe' => Status::getInstance(Status::MAYBE),
47+
),
48+
'choices_as_values' => true,
49+
'preferred_choices' => 'preferred',
1450
));
1551

1652
Note that preferred choices are only meaningful when rendering as a ``select``

0 commit comments

Comments
 (0)