Merge pull request symfony#2694 from docteurklein/patch-2

weaverryan · weaverryan · commit 0c0ebdaf3ebc · 2013-06-22T12:56:38.000-07:00
add error_mapping form option documentation
diff --git a/reference/forms/types/checkbox.rst b/reference/forms/types/checkbox.rst
@@ -18,6 +18,7 @@ if the box is unchecked, the value will be set to false.
 |             | - `read_only`_                                                         |
 |             | - `disabled`_                                                          |
 |             | - `error_bubbling`_                                                    |
+|             | - `error_mapping`_                                                     |
 |             | - `mapped`_                                                            |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`field</reference/forms/types/form>`                              |
@@ -61,4 +62,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/mapped.rst.inc
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -25,6 +25,7 @@ option.
 |             | - `read_only`_                                                              |
 |             | - `disabled`_                                                               |
 |             | - `error_bubbling`_                                                         |
+|             | - `error_mapping`_                                                          |
 |             | - `mapped`_                                                                 |
 |             | - `virtual`_                                                                |
 |             | - `by_reference`_                                                           |
@@ -121,6 +122,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
 .. include:: /reference/forms/types/options/virtual.rst.inc
diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst
@@ -22,6 +22,7 @@ forms, which is useful when creating forms that expose one-to-many relationships
 +-------------+-----------------------------------------------------------------------------+
 | Inherited   | - `label`_                                                                  |
 | options     | - `error_bubbling`_                                                         |
+|             | - `error_mapping`_                                                          |
 |             | - `by_reference`_                                                           |
 |             | - `empty_data`_                                                             |
 |             | - `mapped`_                                                                 |
@@ -345,6 +346,8 @@ Not all options are listed here - only the most applicable to this type:
 
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
+.. include:: /reference/forms/types/options/_error_mapping.rst.inc
+
 error_bubbling
 ~~~~~~~~~~~~~~
 
diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst
@@ -30,6 +30,7 @@ you should just use the ``choice`` type directly.
 |             | - `preferred_choices`_                                                |
 |             | - `empty_value`_                                                      |
 |             | - `error_bubbling`_                                                   |
+|             | - `error_mapping`_                                                    |
 |             | - `required`_                                                         |
 |             | - `label`_                                                            |
 |             | - `read_only`_                                                        |
@@ -68,6 +69,8 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 These options inherit from the :doc:`date</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/required.rst.inc
diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst
@@ -38,6 +38,7 @@ day, and year) or three select boxes (see the `widget_` option).
 |                      | - `disabled`_                                                               |
 |                      | - `mapped`_                                                                 |
 |                      | - `virtual`_                                                                |
+|                      | - `error_mapping`_                                                          |
 +----------------------+-----------------------------------------------------------------------------+
 | Parent type          | ``field`` (if text), ``form`` otherwise                                     |
 +----------------------+-----------------------------------------------------------------------------+
@@ -148,3 +149,5 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
 .. include:: /reference/forms/types/options/virtual.rst.inc
+
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
diff --git a/reference/forms/types/email.rst b/reference/forms/types/email.rst
@@ -17,6 +17,7 @@ The ``email`` field is a text field that is rendered using the HTML5
 |             | - `read_only`_                                                      |
 |             | - `disabled`_                                                       |
 |             | - `error_bubbling`_                                                 |
+|             | - `error_mapping`_                                                  |
 |             | - `mapped`_                                                         |
 +-------------+---------------------------------------------------------------------+
 | Parent type | :doc:`field</reference/forms/types/form>`                           |
@@ -43,4 +44,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
-.. include:: /reference/forms/types/options/mapped.rst.inc
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
+.. include:: /reference/forms/types/options/mapped.rst.inc
diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst
@@ -30,6 +30,7 @@ objects from the database.
 |             | - `read_only`_                                                   |
 |             | - `disabled`_                                                    |
 |             | - `error_bubbling`_                                              |
+|             | - `error_mapping`_                                               |
 |             | - `mapped`_                                                      |
 +-------------+------------------------------------------------------------------+
 | Parent type | :doc:`choice</reference/forms/types/choice>`                     |
@@ -173,4 +174,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/mapped.rst.inc
diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst
@@ -14,6 +14,7 @@ The ``file`` type represents a file input in your form.
 |             | - `read_only`_                                                      |
 |             | - `disabled`_                                                       |
 |             | - `error_bubbling`_                                                 |
+|             | - `error_mapping`_                                                  |
 |             | - `mapped`_                                                         |
 +-------------+---------------------------------------------------------------------+
 | Parent type | :doc:`form</reference/forms/types/form>`                            |
@@ -95,4 +96,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/mapped.rst.inc
diff --git a/reference/forms/types/hidden.rst b/reference/forms/types/hidden.rst
@@ -15,6 +15,7 @@ The hidden type represents a hidden input field.
 | Inherited   | - `data`_                                                            |
 | options     | - `property_path`_                                                   |
 |             | - `mapped`_                                                          |
+|             | - `error_mapping`_                                                   |
 +-------------+----------------------------------------------------------------------+
 | Parent type | :doc:`field</reference/forms/types/form>`                            |
 +-------------+----------------------------------------------------------------------+
@@ -48,3 +49,5 @@ These options inherit from the :doc:`date</reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/property_path.rst.inc
 
 .. include:: /reference/forms/types/options/mapped.rst.inc
+
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst
@@ -23,6 +23,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6
 |             | - `read_only`_                                                        |
 |             | - `disabled`_                                                         |
 |             | - `error_bubbling`_                                                   |
+|             | - `error_mapping`_                                                    |
 |             | - `invalid_message`_                                                  |
 |             | - `invalid_message_parameters`_                                       |
 |             | - `mapped`_                                                           |
@@ -73,6 +74,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst
@@ -31,6 +31,7 @@ you should just use the ``choice`` type directly.
 |             | - `preferred_choices`_                                                 |
 |             | - `empty_value`_                                                       |
 |             | - `error_bubbling`_                                                    |
+|             | - `error_mapping`_                                                     |
 |             | - `required`_                                                          |
 |             | - `label`_                                                             |
 |             | - `read_only`_                                                         |
@@ -69,6 +70,8 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 These options inherit from the :doc:`date</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/required.rst.inc
diff --git a/reference/forms/types/locale.rst b/reference/forms/types/locale.rst
@@ -32,6 +32,7 @@ you should just use the ``choice`` type directly.
 |             | - `preferred_choices`_                                                 |
 |             | - `empty_value`_                                                       |
 |             | - `error_bubbling`_                                                    |
+|             | - `error_mapping`_                                                     |
 |             | - `required`_                                                          |
 |             | - `label`_                                                             |
 |             | - `read_only`_                                                         |
@@ -71,6 +72,8 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 These options inherit from the :doc:`date</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/required.rst.inc
diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst
@@ -24,6 +24,7 @@ how the input and output of the data is handled.
 |             | - `read_only`_                                                      |
 |             | - `disabled`_                                                       |
 |             | - `error_bubbling`_                                                 |
+|             | - `error_mapping`_                                                  |
 |             | - `invalid_message`_                                                |
 |             | - `invalid_message_parameters`_                                     |
 |             | - `mapped`_                                                         |
@@ -94,6 +95,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst
@@ -20,6 +20,7 @@ you want to use for your number.
 |             | - `read_only`_                                                       |
 |             | - `disabled`_                                                        |
 |             | - `error_bubbling`_                                                  |
+|             | - `error_mapping`_                                                   |
 |             | - `invalid_message`_                                                 |
 |             | - `invalid_message_parameters`_                                      |
 |             | - `mapped`_                                                          |
@@ -92,6 +93,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/options/error_mapping.rst.inc b/reference/forms/types/options/error_mapping.rst.inc
@@ -0,0 +1,33 @@
+.. versionadded:: 2.1
+    The ``error_mapping`` option is new to Symfony 2.1.
+
+error_mapping
+~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``empty``
+
+This option permits to modify the default target of errors.
+
+Imagine a custom method named ``matchingCityAndZipCode`` validates 
+whether the city and zip code matches.
+Unfortunately, there is no "matchingCityAndZipCode" field in your form, 
+so all that Symfony can do for you is display the error on top of the form. 
+
+With customized error mapping, you can do better: 
+make the error be mapped to the city field.
+
+Here are the rules to understand the left and the right side of the mapping:
+
+ * The left side contains property paths. 
+ * If the violation is generated on a property or method of a class, 
+ its path is simply propertyName. 
+ * If the violation is generated on an entry of an ``array`` 
+ or ``ArrayAccess`` object, the property path is ``[indexName]``. 
+ * You can construct nested property paths by concatenating them, 
+ separating properties by dots, 
+   * for example: ``addresses[work].matchingCityAndZipCode``
+ * The left side of the error mapping also accepts a dot ``.``,
+ which refers to the field itself. 
+ That means that any error added to the field is added to the given 
+ nested field instead.
+ * The right side contains simply the names of fields in the form.
diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst
@@ -18,6 +18,7 @@ The ``password`` field renders an input password text box.
 |             | - `read_only`_                                                         |
 |             | - `disabled`_                                                          |
 |             | - `error_bubbling`_                                                    |
+|             | - `error_mapping`_                                                     |
 |             | - `mapped`_                                                            |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`text</reference/forms/types/text>`                               |
@@ -59,4 +60,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
-.. include:: /reference/forms/types/options/mapped.rst.inc
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
+.. include:: /reference/forms/types/options/mapped.rst.inc
diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst
@@ -23,6 +23,7 @@ This field adds a percentage sign "``%``" after the input box.
 |             | - `read_only`_                                                        |
 |             | - `disabled`_                                                         |
 |             | - `error_bubbling`_                                                   |
+|             | - `error_mapping`_                                                    |
 |             | - `invalid_message`_                                                  |
 |             | - `invalid_message_parameters`_                                       |
 |             | - `mapped`_                                                           |
@@ -78,6 +79,8 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/radio.rst b/reference/forms/types/radio.rst
@@ -22,6 +22,7 @@ If you want to have a Boolean field, use :doc:`checkbox</reference/forms/types/c
 |             | - `read_only`_                                                      |
 |             | - `disabled`_                                                       |
 |             | - `error_bubbling`_                                                 |
+|             | - `error_mapping`_                                                  |
 |             | - `mapped`_                                                         |
 +-------------+---------------------------------------------------------------------+
 | Parent type | :doc:`field</reference/forms/types/form>`                           |
@@ -55,4 +56,6 @@ These options inherit from the :doc:`field</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
 .. include:: /reference/forms/types/options/mapped.rst.inc
diff --git a/reference/forms/types/repeated.rst b/reference/forms/types/repeated.rst
@@ -25,6 +25,7 @@ accuracy.
 | Inherited   | - `invalid_message`_                                                   |
 | options     | - `invalid_message_parameters`_                                        |
 |             | - `mapped`_                                                            |
+|             | - `error_mapping`_                                                     |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`field</reference/forms/types/form>`                              |
 +-------------+------------------------------------------------------------------------+
@@ -189,3 +190,5 @@ These options inherit from the :doc:`date</reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
 
 .. include:: /reference/forms/types/options/mapped.rst.inc
+
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
diff --git a/reference/forms/types/search.rst b/reference/forms/types/search.rst
diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst
diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst
diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst
diff --git a/reference/forms/types/timezone.rst b/reference/forms/types/timezone.rst
diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst
