8000 Merge branch '4.4' into 5.0 · symfony/symfony-docs@d51fa1e · GitHub
[go: up one dir, main page]
Skip to content

Commit d51fa1e

Browse files
OskarStarkOskarStark
committed
Merge branch '4.4' into 5.0
* 4.4: [Form] minor fixes in ChoiceType options
2 parents 6a07a71 + a3d4ae9 commit d51fa1e

File tree

7 files changed

+51
-30
lines changed

7 files changed

+51
-30
lines changed

‎reference/forms/types/choice.rst

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -82,8 +82,8 @@ This will create a ``select`` drop-down like this:
8282

8383
If the user selects ``No``, the form will return ``false`` for this field. Similarly,
8484
if the starting data for this field is ``true``, then ``Yes`` will be auto-selected.
85-
In other words, the **value** of each item is the value you want to get/set in PHP
86-
code, while the **key** is what will be shown to the user.
85+
In other words, the **choice** of each item is the value you want to get/set in PHP
86+
code, while the **key** is the **label** that will be shown to the user.
8787

8888
Advanced Example (with Objects!)
8989
--------------------------------
@@ -103,23 +103,40 @@ method::
103103
new Category('Cat3'),
104104
new Category('Cat4'),
105105
],
106-
'choice_label' => function(Category $category, $key, $value) {
107-
return strtoupper($category->getName());
106+
// "name" is a property path, meaning Symfony will look for a public
107+
// property or a public method like "getName()" to define the input
108+
// string value that will be submitted by the form
109+
'choice_value' => 'name',
110+
// a callback to return the label for a given choice
111+
// if a placeholder is used, its empty value (null) may be passed but
112+
// its label is defined by its own "placeholder" option
113+
'choice_label' => function(?Category $category) {
114+
return $category ? strtoupper($category->getName()) : '';
108115
},
109-
'choice_attr' => function(Category $category, $key, $value) {
110-
return ['class' => 'category_'.strtolower($category->getName())];
116+
// returns the html attributes for each option input (may be radio/checkbox)
117+
'choice_attr' => function(?Category $category) {
118+
return $category ? ['class' => 'category_'.strtolower($category->getName())] : [];
111119
},
112-
'group_by' => function(Category $category, $key, $value) {
120+
// every option can use a string property path or any callable that get
121+
// passed each choice as argument, but it may not be needed
122+
'group_by' => function() {
113123
// randomly assign things into 2 groups
114124
return rand(0, 1) == 1 ? 'Group A' : 'Group B';
115125
},
116-
'preferred_choices' => function(Category $category, $key, $value) {
117-
return $category->getName() == 'Cat2' || $category->getName() == 'Cat3';
126+
// a callback to return whether a category is preferred
127+
'preferred_choices' => function(?Category $category) {
128+
return $category && 100 < $category->getArticleCounts();
118129
},
119130
]);
120131

121-
You can also customize the `choice_name`_ and `choice_value`_ of each choice if
122-
you need further HTML customization.
132+
You can also customize the `choice_name`_ of each choice. You can learn more
133+
about all of these options in the sections below.
134+
135+
.. caution::
136+
137+
The *placeholder* is a specific field, when the choices are optional the
138+
first item in the list must be empty, so the user can unselect.
139+
Be sure to always handle the empty choice ``null`` when using callbacks.
123140

124141
.. _forms-reference-choice-tags:
125142

@@ -159,7 +176,7 @@ by passing a multi-dimensional ``choices`` array::
159176
.. image:: /_images/reference/form/choice-example4.png
160177
:align: center
161178

162-
To get fancier, use the `group_by`_ option.
179+
To get fancier, use the `group_by`_ option instead.
163180

164181
Field Options
165182
-------------
@@ -177,7 +194,10 @@ is the item's label and the array value is the item's value::
177194
// ...
178195

179196
$builder->add('inStock', ChoiceType::class, [
180-
'choices' => ['In Stock' => true, 'Out of Stock' => false],
197+
'choices' => [
198+
'In Stock' => true,
199+
'Out of Stock' => false,
200+
],
181201
]);
182202

183203
If there are choice values that are not scalar or the stringified

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
``choice_attr``
22
~~~~~~~~~~~~~~~
33

4-
**type**: ``array``, ``callable`` or ``string`` **default**: ``[]``
4+
**type**: ``array``, ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``[]``
55

66
Use this to add additional HTML attributes to each choice. This can be
77
an associative array where the keys match the choice keys and the values

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
``choice_label``
22
~~~~~~~~~~~~~~~~
33

4-
**type**: ``string``, ``callable`` or ``false`` **default**: ``null``
4+
**type**: ``string``, ``callable``, ``false`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
55

6-
Normally, the array key of each item in the ``choices`` option is used as the
6+
By default, the array key of each item in the ``choices`` option is used as the
77
text that's shown to the user. The ``choice_label`` option allows you to take
88
more control::
99

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
``choice_name``
22
~~~~~~~~~~~~~~~
33

4-
**type**: ``callable`` or ``string`` **default**: ``null``
4+
**type**: ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
55

66
Controls the internal field name of the choice. You normally don't care about this,
77
but in some advanced cases, you might. For example, this "name" becomes the index
8-
of the choice views in the template.
8+
of the choice views in the template and is used as part o the field name
9+
attribute.
910
1011
This can be a callable or a property path. See `choice_label`_ for similar usage.
11-
If ``null`` is used, an incrementing integer is used as the name.
12+
By default, the choice key or an incrementing integer may be used (starting at ``0``).
1213
1314
.. caution::
1415

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
``choice_value``
22
~~~~~~~~~~~~~~~~
33

4-
**type**: ``callable`` or ``string`` **default**: ``null``
4+
**type**: ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
55

66
Returns the string "value" for each choice, which must be unique across all choices.
77
This is used in the ``value`` attribute in HTML and submitted in the POST/PUT requests.
88
You don't normally need to worry about this, but it might be handy when processing
99
an API request (since you can configure the value that will be sent in the API request).
1010
11-
This can be a callable or a property path. If ``null`` is given, an incrementing
12-
integer is used as the value.
11+
This can be a callable or a property path. By default, the choices are used if they
12+
can be casted to strings. Otherwise an incrementing integer is used (starting at ``0``).
1313
1414
If you pass a callable, it will receive one argument: the choice itself. When using
1515
the :doc:`/reference/forms/types/entity`, the argument will be the entity object
16-
for each choice or ``null`` in some cases, which you need to handle::
16+
for each choice or ``null`` in a placeholder is used, which you need to handle::
1717
18-
'choice_value' => function (MyOptionEntity $entity = null) {
18+
'choice_value' => function (?MyOptionEntity $entity) {
1919
return $entity ? $entity->getId() : '';
2020
},

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
``group_by``
22
~~~~~~~~~~~~
33

4-
**type**: ``string`` or ``callable`` **default**: ``null``
4+
**type**: ``string``, ``callable`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
55

66
You can group the ``<option>`` elements of a ``<select>`` into ``<optgroup>``
77
by passing a multi-dimensional array to ``choices``. See the
@@ -25,9 +25,9 @@ Take the following example::
2525
'group_by' => function($choice, $key, $value) {
2626
if ($choice <= new \DateTime('+3 days')) {
2727
return 'Soon';
28-
} else {
29-
return 'Later';
3028
}
29+
30+
return 'Later';
3131
},
3232
]);
3333

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
``preferred_choices``
22
~~~~~~~~~~~~~~~~~~~~~
33

4-
**type**: ``array``, ``callable`` or ``string`` **default**: ``[]``
4+
**type**: ``array``, ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``[]``
55

66
This option allows you to display certain choices at the top of your list with a
77
visual separator between them and the complete list of options. If you have a
8-
form of languages, you can list the most popular on top, like Bork Bork and Pirate::
8+
form of languages, you can list the most popular on top, like Bork and Pirate::
99

1010
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
1111
// ...
@@ -14,7 +14,7 @@ form of languages, you can list the most popular on top, like Bork Bork and Pira
1414
'choices' => [
1515
'English' => 'en',
1616
'Spanish' => 'es',
17-
'Bork' => 'muppets',
17+
'Bork' => 'muppets',
1818
'Pirate' => 'arr',
1919
],
2020
'preferred_choices' => ['muppets', 'arr'],

0 commit comments

Comments
 (0)
0