More changes for forms

symfony · javiereguiluz · Sep 23, 2021 · Mar 14, 2021 · Apr 9, 2021 · Sep 23, 2021
commit 773e81648adc917f5d97f0cc332c5deb5355b40c
@@ -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>`,

@@ -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