Skip to content

Commit 3763f71

Browse files
althausweaverryan
althaus
authored and
weaverryan
committed
Added basic choice type changes
1 parent fd35e21 commit 3763f71

File tree

7 files changed

+218
-19
lines changed

7 files changed

+218
-19
lines changed

‎reference/forms/types/choice.rst‎

Lines changed: 54 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',
6775
),
76+
'choices_as_values' => true,
6877
'multiple' => true,
6978
));
7079

71-
You can also use the ``choice_list`` option, which takes an object that
72-
can specify the choices for your widget.
80+
If you rely on your option value attribute (e.g. for JavaScript) you need to
81+
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',
89+
),
90+
'choices_as_values' => true,
91+
'choice_value' => function ($choice) {
92+
return $choice;
93+
},
94+
'multiple' => true,
95+
));
96+
97+
You can also use the ``choice_loader`` option, which can be used to load the
98+
list only partially in cases where a fully-loaded list is not necessary.
7399

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

@@ -85,19 +111,23 @@ 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).
95125

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.
126+
.. caution::
127+
128+
The ``choices_as_values`` option will be removed in Symfony 3.0, where
129+
the choices will be passed in the values of the ``choices`` option by
130+
default.
101131

102132
choice_list
103133
~~~~~~~~~~~
@@ -149,6 +179,16 @@ in HTML), ``0.1`` will be returned.
149179

150180
.. include:: /reference/forms/types/options/preferred_choices.rst.inc
151181

182+
.. include:: /reference/forms/types/options/choice_label.rst.inc
183+
184+
.. include:: /reference/forms/types/options/choice_name.rst.inc
185+
186+
.. include:: /reference/forms/types/options/choice_value.rst.inc
187+
188+
.. include:: /reference/forms/types/options/choice_attr.rst.inc
189+
190+
.. include:: /reference/forms/types/options/group_by.rst.inc
191+
152192
Overridden Options
153193
------------------
154194

‎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 choice
10+
as first and the key of the ``choices`` array as second argument) or a property
11+
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 a
12+
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, a
10+
callable (like for ``choice_label``) or a property path.
11+
12+
The return values of the callable/property path are used as group labels. If
13+
``null`` is returned, a choice is not grouped.
14+
15+
If ``null``, the structure of the ``choices`` array is used to construct the
16+
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: 41 additions & 5 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
6+
If this option is specified as an array, then a sub-set of all of the options will be
77
moved to the top of the select menu. The following would move the "Baz"
88
option to the top, with a visual separator between it and the rest of the
99
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)