Skip to content

Commit 0c0ebda

Browse files
weaverryanweaverryan
committed
Merge pull request #2694 from docteurklein/patch-2
add error_mapping form option documentation
2 parents b0da69a + fe31fd2 commit 0c0ebda

25 files changed

+107
-2
lines changed

‎reference/forms/types/checkbox.rst

+3
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ if the box is unchecked, the value will be set to false.
1818
| | - `read_only`_ |
1919
| | - `disabled`_ |
2020
| | - `error_bubbling`_ |
21+
| | - `error_mapping`_ |
2122
| | - `mapped`_ |
2223
+-------------+------------------------------------------------------------------------+
2324
| Parent type | :doc:`field</reference/forms/types/form>` |
@@ -61,4 +62,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
6162

6263
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
6364

65+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
66+
6467
.. include:: /reference/forms/types/options/mapped.rst.inc

‎reference/forms/types/choice.rst

+3
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ option.
2525
| | - `read_only`_ |
2626
| | - `disabled`_ |
2727
| | - `error_bubbling`_ |
28+
| | - `error_mapping`_ |
2829
| | - `mapped`_ |
2930
| | - `virtual`_ |
3031
| | - `by_reference`_ |
@@ -121,6 +122,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
121122

122123
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
123124

125+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
126+
124127
.. include:: /reference/forms/types/options/mapped.rst.inc
125128

126129
.. include:: /reference/forms/types/options/virtual.rst.inc

‎reference/forms/types/collection.rst

+3
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ forms, which is useful when creating forms that expose one-to-many relationships
2222
+-------------+-----------------------------------------------------------------------------+
2323
| Inherited | - `label`_ |
2424
| options | - `error_bubbling`_ |
25+
| | - `error_mapping`_ |
2526
| | - `by_reference`_ |
2627
| | - `empty_data`_ |
2728
| | - `mapped`_ |
@@ -345,6 +346,8 @@ Not all options are listed here - only the most applicable to this type:
345346

346347
.. include:: /reference/forms/types/options/mapped.rst.inc
347348

349+
.. include:: /reference/forms/types/options/_error_mapping.rst.inc
350+
348351
error_bubbling
349352
~~~~~~~~~~~~~~
350353

‎reference/forms/types/country.rst

+3
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ you should just use the ``choice`` type directly.
3030
| | - `preferred_choices`_ |
3131
| | - `empty_value`_ |
3232
| | - `error_bubbling`_ |
33+
| | - `error_mapping`_ |
3334
| | - `required`_ |
3435
| | - `label`_ |
3536
| | - `read_only`_ |
@@ -68,6 +69,8 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
6869

6970
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
7071

72+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
73+
7174
These options inherit from the :doc:`date</reference/forms/types/form>` type:
7275

7376
.. include:: /reference/forms/types/options/required.rst.inc

‎reference/forms/types/date.rst

+3
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ day, and year) or three select boxes (see the `widget_` option).
3838
| | - `disabled`_ |
3939
| | - `mapped`_ |
4040
| | - `virtual`_ |
41+
| | - `error_mapping`_ |
4142
+----------------------+-----------------------------------------------------------------------------+
4243
| Parent type | ``field`` (if text), ``form`` otherwise |
4344
+----------------------+-----------------------------------------------------------------------------+
@@ -148,3 +149,5 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
148149
.. include:: /reference/forms/types/options/mapped.rst.inc
149150

150151
.. include:: /reference/forms/types/options/virtual.rst.inc
152+
153+
.. include:: /reference/forms/types/options/error_mapping.rst.inc

‎reference/forms/types/email.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ The ``email`` field is a text field that is rendered using the HTML5
1717
| | - `read_only`_ |
1818
| | - `disabled`_ |
1919
| | - `error_bubbling`_ |
20+
| | - `error_mapping`_ |
2021
| | - `mapped`_ |
2122
+-------------+---------------------------------------------------------------------+
2223
| Parent type | :doc:`field</reference/forms/types/form>` |
@@ -43,4 +44,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
4344

4445
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
4546

46-
.. include:: /reference/forms/types/options/mapped.rst.inc
47+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
48+
49+
.. include:: /reference/forms/types/options/mapped.rst.inc

‎reference/forms/types/entity.rst

+3
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ objects from the database.
3030
| | - `read_only`_ |
3131
| | - `disabled`_ |
3232
| | - `error_bubbling`_ |
33+
| | - `error_mapping`_ |
3334
| | - `mapped`_ |
3435
+-------------+------------------------------------------------------------------+
3536
| Parent type | :doc:`choice</reference/forms/types/choice>` |
@@ -173,4 +174,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
173174

174175
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
175176

177+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
178+
176179
.. include:: /reference/forms/types/options/mapped.rst.inc

‎reference/forms/types/file.rst

+3
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ The ``file`` type represents a file input in your form.
1414
| | - `read_only`_ |
1515
| | - `disabled`_ |
1616
| | - `error_bubbling`_ |
17+
| | - `error_mapping`_ |
1718
| | - `mapped`_ |
1819
+-------------+---------------------------------------------------------------------+
1920
| Parent type | :doc:`form</reference/forms/types/form>` |
@@ -95,4 +96,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
9596

9697
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
9798

99+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
100+
98101
.. include:: /reference/forms/types/options/mapped.rst.inc

‎reference/forms/types/hidden.rst

+3
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ The hidden type represents a hidden input field.
1515
| Inherited | - `data`_ |
1616
| options | - `property_path`_ |
1717
| | - `mapped`_ |
18+
| | - `error_mapping`_ |
1819
+-------------+----------------------------------------------------------------------+
1920
| Parent type | :doc:`field</reference/forms/types/form>` |
2021
+-------------+----------------------------------------------------------------------+
@@ -48,3 +49,5 @@ These options inherit from the :doc:`date</reference/forms/types/form>` type:
4849
.. include:: /reference/forms/types/options/property_path.rst.inc
4950

5051
.. include:: /reference/forms/types/options/mapped.rst.inc
52+
53+
.. include:: /reference/forms/types/options/error_mapping.rst.inc

‎reference/forms/types/integer.rst

+3
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6
2323
| | - `read_only`_ |
2424
| | - `disabled`_ |
2525
| | - `error_bubbling`_ |
26+
| | - `error_mapping`_ |
2627
| | - `invalid_message`_ |
2728
| | - `invalid_message_parameters`_ |
2829
| | - `mapped`_ |
@@ -73,6 +74,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
7374

7475
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
7576

77+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
78+
7679
.. include:: /reference/forms/types/options/invalid_message.rst.inc
7780

7881
.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc

‎reference/forms/types/language.rst

+3
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ you should just use the ``choice`` type directly.
3131
| | - `preferred_choices`_ |
3232
| | - `empty_value`_ |
3333
| | - `error_bubbling`_ |
34+
| | - `error_mapping`_ |
3435
| | - `required`_ |
3536
| | - `label`_ |
3637
| | - `read_only`_ |
@@ -69,6 +70,8 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
6970

7071
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
7172

73+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
74+
7275
These options inherit from the :doc:`date</reference/forms/types/form>` type:
7376

7477
.. include:: /reference/forms/types/options/required.rst.inc

‎reference/forms/types/locale.rst

+3
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ you should just use the ``choice`` type directly.
3232
| | - `preferred_choices`_ |
3333
| | - `empty_value`_ |
3434
| | - `error_bubbling`_ |
35+
| | - `error_mapping`_ |
3536
| | - `required`_ |
3637
| | - `label`_ |
3738
| | - `read_only`_ |
@@ -71,6 +72,8 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
7172

7273
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
7374

75+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
76+
7477
These options inherit from the :doc:`date</reference/forms/types/form>` type:
7578

7679
.. include:: /reference/forms/types/options/required.rst.inc

‎reference/forms/types/money.rst

+3
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ how the input and output of the data is handled.
2424
| | - `read_only`_ |
2525
| | - `disabled`_ |
2626
| | - `error_bubbling`_ |
27+
| | - `error_mapping`_ |
2728
| | - `invalid_message`_ |
2829
| | - `invalid_message_parameters`_ |
2930
| | - `mapped`_ |
@@ -94,6 +95,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
9495

9596
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
9697

98+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
99+
97100
.. include:: /reference/forms/types/options/invalid_message.rst.inc
98101

99102
.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc

‎reference/forms/types/number.rst

+3
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ you want to use for your number.
2020
| | - `read_only`_ |
2121
| | - `disabled`_ |
2222
| | - `error_bubbling`_ |
23+
| | - `error_mapping`_ |
2324
| | - `invalid_message`_ |
2425
| | - `invalid_message_parameters`_ |
2526
| | - `mapped`_ |
@@ -92,6 +93,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
9293

9394
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
9495

96+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
97+
9598
.. include:: /reference/forms/types/options/invalid_message.rst.inc
9699

97100
.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc

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

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. versionadded:: 2.1
2+
The ``error_mapping`` option is new to Symfony 2.1.
3+
4+
error_mapping
5+
~~~~~~~~~~~~~
6+
7+
**type**: ``array`` **default**: ``empty``
8+
9+
This option permits to modify the default target of errors.
10+
11+
Imagine a custom method named ``matchingCityAndZipCode`` validates
12+
whether the city and zip code matches.
13+
Unfortunately, there is no "matchingCityAndZipCode" field in your form,
14+
so all that Symfony can do for you is display the error on top of the form.
15+
16+
With customized error mapping, you can do better:
17+
make the error be mapped to the city field.
18+
19+
Here are the rules to understand the left and the right side of the mapping:
20+
21+
* The left side contains property paths.
22+
* If the violation is generated on a property or method of a class,
23+
its path is simply propertyName.
24+
* If the violation is generated on an entry of an ``array``
25+
or ``ArrayAccess`` object, the property path is ``[indexName]``.
26+
* You can construct nested property paths by concatenating them,
27+
separating properties by dots,
28+
* for example: ``addresses[work].matchingCityAndZipCode``
29+
* The left side of the error mapping also accepts a dot ``.``,
30+
which refers to the field itself.
31+
That means that any error added to the field is added to the given
32+
nested field instead.
33+
* The right side contains simply the names of fields in the form.

‎reference/forms/types/password.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ The ``password`` field renders an input password text box.
1818
| | - `read_only`_ |
1919
| | - `disabled`_ |
2020
| | - `error_bubbling`_ |
21+
| | - `error_mapping`_ |
2122
| | - `mapped`_ |
2223
+-------------+------------------------------------------------------------------------+
2324
| Parent type | :doc:`text</reference/forms/types/text>` |
@@ -59,4 +60,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
5960

6061
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
6162

62-
.. include:: /reference/forms/types/options/mapped.rst.inc
63+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
64+
65+
.. include:: /reference/forms/types/options/mapped.rst.inc

‎reference/forms/types/percent.rst

+3
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ This field adds a percentage sign "``%``" after the input box.
2323
| | - `read_only`_ |
2424
| | - `disabled`_ |
2525
| | - `error_bubbling`_ |
26+
| | - `error_mapping`_ |
2627
| | - `invalid_message`_ |
2728
| | - `invalid_message_parameters`_ |
2829
| | - `mapped`_ |
@@ -78,6 +79,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
7879

7980
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
8081

82+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
83+
8184
.. include:: /reference/forms/types/options/invalid_message.rst.inc
8285

8386
.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc

‎reference/forms/types/radio.rst

+3
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ If you want to have a Boolean field, use :doc:`checkbox</reference/forms/types/c
2222
| | - `read_only`_ |
2323
| | - `disabled`_ |
2424
| | - `error_bubbling`_ |
25+
| | - `error_mapping`_ |
2526
| | - `mapped`_ |
2627
+-------------+---------------------------------------------------------------------+
2728
| Parent type | :doc:`field</reference/forms/types/form>` |
@@ -55,4 +56,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
5556

5657
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
5758

59+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
60+
5861
.. include:: /reference/forms/types/options/mapped.rst.inc

‎reference/forms/types/repeated.rst

+3
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ accuracy.
2525
| Inherited | - `invalid_message`_ |
2626
| options | - `invalid_message_parameters`_ |
2727
| | - `mapped`_ |
28+
| | - `error_mapping`_ |
2829
+-------------+------------------------------------------------------------------------+
2930
| Parent type | :doc:`field</reference/forms/types/form>` |
3031
+-------------+------------------------------------------------------------------------+
@@ -189,3 +190,5 @@ These options inherit from the :doc:`date</reference/forms/types/form>` type:
189190
.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
190191

191192
.. include:: /reference/forms/types/options/mapped.rst.inc
193+
194+
.. include:: /reference/forms/types/options/error_mapping.rst.inc

0 commit comments

Comments
 (0)