diff --git a/components/form.rst b/components/form.rst index 2b387ef326e..64551b72041 100644 --- 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 `, 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 index edd17ed50dc..2abf1dc34c0 100644 --- a/controller/upload_file.rst +++ b/controller/upload_file.rst @@ -174,8 +174,8 @@ 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' => $form, ]); } } diff --git a/form/direct_submit.rst b/form/direct_submit.rst index 92dc09c5de5..a7c623dad19 100644 --- a/form/direct_submit.rst +++ b/form/direct_submit.rst @@ -29,8 +29,8 @@ control over when exactly your form is submitted and what data is passed to it:: } } - return $this->render('task/new.html.twig', [ - 'form' => $form->createView(), + return $this->renderForm('task/new.html.twig', [ + 'form' => $form, ]); } diff --git a/form/dynamic_form_modification.rst b/form/dynamic_form_modification.rst index 7c52e5f3abd..afc1b48236a 100644 --- a/form/dynamic_form_modification.rst +++ b/form/dynamic_form_modification.rst @@ -534,10 +534,9 @@ your application. Assume that you have a sport meetup creation controller:: // ... save the meetup, redirect etc. } - return $this->render( - 'meetup/create.html.twig', - ['form' => $form->createView()] - ); + return $this->renderForm('meetup/create.html.twig', [ + 'form' => $form, + ]); } // ... diff --git a/form/form_collections.rst b/form/form_collections.rst index e35e1d8be67..c58bf996235 100644 --- a/form/form_collections.rst +++ b/form/form_collections.rst @@ -164,8 +164,8 @@ In your controller, you'll create a new form from the ``TaskType``:: // ... do your form processing, like saving the Task and Tag entities } - return $this->render('task/new.html.twig', [ - 'form' => $form->createView(), + return $this->renderForm('task/new.html.twig', [ + 'form' => $form, ]); } } diff --git a/form/form_customization.rst b/form/form_customization.rst index 69d0a97e61d..98f8d433ce8 100644 --- 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' => $form]) + or $this->render('...', ['form' => $form->createView()]) #} {{ form(form) }} The next step is to use the :ref:`form_start() `, diff --git a/forms.rst b/forms.rst index 3814caa0646..74fef0b6600 100644 --- 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; @@ -277,12 +275,21 @@ to build another object with the visual representation of the form:: $form = $this->createForm(TaskType::class, $task); - return $this->render('task/new.html.twig', [ - 'form' => $form->createView(), + return $this->renderForm('task/new.html.twig', [ + 'form' => $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. + Then, use some :ref:`form helper functions ` to render the form contents: @@ -405,8 +412,8 @@ written into the form object:: return $this->redirectToRoute('task_success'); } - return $this->render('task/new.html.twig', [ - 'form' => $form->createView(), + return $this->renderForm('task/new.html.twig', [ + 'form' => $form, ]); } } @@ -437,12 +444,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 `, 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