Merge branch '2.5'

weaverryan · weaverryan · commit b6286fd8a0d2 · 2014-10-03T10:40:41.000-04:00
* 2.5:
  formatting to follow 72 characters line limit
  changed dash to underscore
  change misleading language identifier
  add description for the `validation_groups` option
diff --git a/book/forms.rst b/book/forms.rst
@@ -504,6 +504,8 @@ fields were submitted. If you want to suppress validation, you can use the
 .. index::
    single: Forms; Validation groups based on submitted data
 
+.. _book-form-validation-groups:
+
 Groups based on the Submitted Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst
@@ -8,8 +8,8 @@ The ``language`` type is a subset of the ``ChoiceType`` that allows the user
 to select from a large list of languages. As an added bonus, the language names
 are displayed in the language of the user.
 
-The "value" for each language is the *Unicode language identifier*
-(e.g. ``fr`` or ``zh-Hant``).
+The "value" for each language is the *Unicode language identifier* used in 
+the `International Components for Unicode`_ (e.g. ``fr`` or ``zh_Hant``).
 
 .. note::
 
@@ -106,3 +106,5 @@ The actual default value of this option depends on other field options:
 .. include:: /reference/forms/types/options/read_only.rst.inc
 
 .. include:: /reference/forms/types/options/required.rst.inc
+
+.. _`International Components for Unicode`: http://site.icu-project.org
diff --git a/reference/forms/types/submit.rst b/reference/forms/types/submit.rst
@@ -17,6 +17,7 @@ A submit button.
 |                      | - `label`_                                                           |
 |                      | - `label_attr`_                                                      |
 |                      | - `translation_domain`_                                              |
+|                      | - `validation_groups`_                                               |
 +----------------------+----------------------------------------------------------------------+
 | Parent type          | :doc:`button</reference/forms/types/button>`                         |
 +----------------------+----------------------------------------------------------------------+
@@ -45,6 +46,33 @@ Inherited Options
 
 .. include:: /reference/forms/types/options/button_translation_domain.rst.inc
 
+validation_groups
+~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``null``
+
+When your form contains multiple submit buttons, you can change the validation
+group based on the button which was used to submit the form. Imagine a registration
+form wizard with buttons to go to the previous or the next step::
+
+    $form = $this->createFormBuilder($user)
+        ->add('previousStep', 'submit', array(
+            'validation_groups' => false,
+        ))
+        ->add('nextStep', 'submit', array(
+            'validation_groups' => array('Registration'),
+        ))
+        ->getForm();
+
+The special ``false`` ensures that no validation is performed when the previous
+step button is clicked. When the second button is clicked, all constraints
+from the "Registration" are validated.
+
+.. seealso::
+
+    You can read more about this in :ref:`the Form chapter <book-form-validation-groups>`
+    of the book.
+
 Form Variables
 --------------
 
