More changes for forms

javiereguiluz · javiereguiluz · commit 773e81648adc · 2021-09-23T11:57:30.000+02:00
diff --git a/components/form.rst b/components/form.rst
@@ -647,6 +647,12 @@ method:
             }
         }
 
+.. caution::
+
+    The form's ``createView()`` method should be called *after* ``handleRequest()`` is
+    called. Otherwise, when using :doc:`form events </form/events>`, changes done
+    in the ``*_SUBMIT`` events won't be applied to the view (like validation errors).
+
 This defines a common form "workflow", which contains 3 different possibilities:
 
 1) On the initial GET request (i.e. when the user "surfs" to your page),
diff --git a/controller/upload_file.rst b/controller/upload_file.rst
@@ -174,9 +174,7 @@ Finally, you need to update the code of the controller that handles the form::
                 return $this->redirectToRoute('app_product_list');
             }
 
-            return $this->render('product/new.html.twig', [
-                'form' => $form->createView(),
-            ]);
+            return $this->renderForm('product/new.html.twig', $form);
         }
     }
 
diff --git a/form/form_customization.rst b/form/form_customization.rst
@@ -20,8 +20,9 @@ enough to render an entire form, including all its fields and error messages:
 
 .. code-block:: twig
 
-    {# form is a variable passed from the controller and created
-      by calling to the $form->createView() method #}
+    {# form is a variable passed from the controller via either
+      $this->renderForm('...', $form)
+      or $this->render('...', ['form' => $form->createView()]) #}
     {{ form(form) }}
 
 The next step is to use the :ref:`form_start() <reference-forms-twig-start>`,
diff --git a/forms.rst b/forms.rst
@@ -255,9 +255,7 @@ the ``data_class`` option by adding the following to your form type class::
 Rendering Forms
 ---------------
 
-Now that the form has been created, the next step is to render it. Instead of
-passing the entire form object to the template, use the ``createView()`` method
-to build another object with the visual representation of the form::
+Now that the form has been created, the next step is to render it::
 
     // src/Controller/TaskController.php
     namespace App\Controller;
@@ -281,10 +279,14 @@ to build another object with the visual representation of the form::
         }
     }
 
+In versions prior to Symfony 5.3, controllers used the method
+``$this->render('...', ['form' => $form->createView()])`` to render the form.
+The ``renderForm()`` method abstracts this logic and it also sets the 422 HTTP
+status code in the response automatically when the submitted form is not valid.
+
 .. versionadded:: 5.3
 
-    The ``renderForm`` method was introduced in Symfony 5.3, allowing to
-    return 422 HTTP status code if an invalid form is submitted.
+    The ``renderForm()`` method was introduced in Symfony 5.3.
 
 Then, use some :ref:`form helper functions <reference-form-twig-functions>` to
 render the form contents:
@@ -438,12 +440,6 @@ possible paths:
     that prevents the user from being able to hit the "Refresh" button of
     their browser and re-post the data.
 
-.. caution::
-
-    The ``createView()`` method should be called *after* ``handleRequest()`` is
-    called. Otherwise, when using :doc:`form events </form/events>`, changes done
-    in the ``*_SUBMIT`` events won't be applied to the view (like validation errors).
-
 .. seealso::
 
     If you need more control over exactly when your form is submitted or which

Original file line number	Diff line number	Diff line change
`@@ -647,6 +647,12 @@ method:`
`647`	`647`	`}`
`648`	`648`	`}`
`649`	`649`
	`650`	`+.. caution::`
	`651`	`+`
	`652`	+ The form's ``createView()`` method should be called after ``handleRequest()`` is
	`653`	+ called. Otherwise, when using :doc:`form events </form/events>`, changes done
	`654`	+ in the ``*_SUBMIT`` events won't be applied to the view (like validation errors).
	`655`	`+`
`650`	`656`	`This defines a common form "workflow", which contains 3 different possibilities:`
`651`	`657`
`652`	`658`	`1) On the initial GET request (i.e. when the user "surfs" to your page),`
Original file line number	Diff line number	Diff line change
`@@ -174,9 +174,7 @@ Finally, you need to update the code of the controller that handles the form::`
`174`	`174`	`return $this->redirectToRoute('app_product_list');`
`175`	`175`	`}`
`176`	`176`
`177`		`- return $this->render('product/new.html.twig', [`
`178`		`- 'form' => $form->createView(),`
`179`		`- ]);`
	`177`	`+ return $this->renderForm('product/new.html.twig', $form);`
`180`	`178`	`}`
`181`	`179`	`}`
`182`	`180`