feature #4246 [Reference] add description for the validation_groups option (xabbuh)

weaverryan · weaverryan · commit 62bafad2a1cb · 2014-10-03T10:39:35.000-04:00
This PR was merged into the 2.3 branch. Discussion ---------- [Reference] add description for the `validation_groups` option | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes (symfony/symfony#6528) | Applies to | all | Fixed tickets | #3358 Commits ------- c41b17c 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/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
 --------------
 
