minor symfony#12145 Updated the main Form article (javiereguiluz)

This PR was squashed before being merged into the 4.3 branch (closes symfony#12145).

Discussion
----------

Updated the main Form article

Following the recent trend of updating the most popular articles, this PR updates the main forms article a bit.

Commits
-------

3f0406f Updated the main Form article

Author: javiereguiluz

_build/redirection_map

@@ -443,3 +443,4 @@
 /routing/hostname_pattern /routing
 /routing/extra_information /routing
 /console/request_context /routing
+/form/action_method /forms

best_practices/forms.rst

@@ -212,6 +212,8 @@ Handling a form submit usually follows a similar template::
         // render the template
     }
 
+.. _best-practice-handle-form:
+
 We recommend that you use a single action for both rendering the form and
 handling the form submit. For example, you *could* have a ``new()`` action that
 *only* renders the form and a ``create()`` action that *only* processes the form

components/form.rst

@@ -80,8 +80,8 @@ object to read data off of the correct PHP superglobals (i.e. ``$_POST`` or
 .. seealso::
 
     If you need more control over exactly when your form is submitted or which
-    data is passed to it, you can use the :method:`Symfony\\Component\\Form\\FormInterface::submit`
-    for this. Read more about it :ref:`form-call-submit-directly`.
+    data is passed to it,
+    :doc:`use the submit() method to handle form submissions </form/direct_submit>`.
 
 .. sidebar:: Integration with the HttpFoundation Component
 

doctrine.rst

@@ -418,6 +418,8 @@ Take a look at the previous example in more detail:
 Whether you're creating or updating objects, the workflow is always the same: Doctrine
 is smart enough to know if it should INSERT or UPDATE your entity.
 
+.. _automatic_object_validation:
+
 Validating Objects
 ------------------
 

form/action_method.rst

@@ -137,7 +137,7 @@ These are the most important methods that a form type class can define:
 
 ``buildForm()``
     It adds and configures other types into this type. It's the same method used
-    when :ref:`creating Symfony form classes <form-creating-form-classes>`.
+    when :ref:`creating Symfony form classes <creating-forms-in-classes>`.
 
 ``buildView()``
     It sets any extra variables you'll need when rendering the field in a template.

form/create_custom_field_type.rst

@@ -4,53 +4,18 @@
 How to Use the submit() Function to Handle Form Submissions
 ===========================================================
 
-Handle the form submission with the ``handleRequest()`` method::
+The recommended way of :ref:`processing Symfony forms <processing-forms>` is to
+use the :method:`Symfony\\Component\\Form\\FormInterface::handleRequest` method
+to detect when the form has been submitted. However, you can also use the
+:method:`Symfony\\Component\\Form\\FormInterface::submit` method to have better
+control over when exactly your form is submitted and what data is passed to it::
 
     use Symfony\Component\HttpFoundation\Request;
     // ...
 
     public function new(Request $request)
     {
-        $form = $this->createFormBuilder()
-            // ...
-            ->getForm();
-
-        $form->handleRequest($request);
-
-        if ($form->isSubmitted() && $form->isValid()) {
-            // perform some action...
-
-            return $this->redirectToRoute('task_success');
-        }
-
-        return $this->render('product/new.html.twig', [
-            'form' => $form->createView(),
-        ]);
-    }
-
-.. tip::
-
-    To see more about this method, read :ref:`form-handling-form-submissions`.
-
-.. _form-call-submit-directly:
-
-Calling Form::submit() manually
--------------------------------
-
-In some cases, you want better control over when exactly your form is submitted
-and what data is passed to it. Instead of using the
-:method:`Symfony\\Component\\Form\\FormInterface::handleRequest`
-method, pass the submitted data directly to
-:method:`Symfony\\Component\\Form\\FormInterface::submit`::
-
-    use Symfony\Component\HttpFoundation\Request;
-    // ...
-
-    public function new(Request $request)
-    {
-        $form = $this->createFormBuilder()
-            // ...
-            ->getForm();
+        $form = $this->createForm(TaskType::class, $task);
 
         if ($request->isMethod('POST')) {
             $form->submit($request->request->get($form->getName()));
@@ -62,7 +27,7 @@ method, pass the submitted data directly to
             }
         }
 
-        return $this->render('product/new.html.twig', [
+        return $this->render('task/new.html.twig', [
             'form' => $form->createView(),
         ]);
     }

form/direct_submit.rst

@@ -15,7 +15,8 @@ Symfony Built-In Form Themes
 
 Symfony comes with several **built-in form themes** that make your forms look
 great when using some of the most popular CSS frameworks. Each theme is defined
-in a single Twig template:
+in a single Twig template and they are enabled in the
+:ref:`twig.form_themes <config-twig-form-themes>` option:
 
 * `form_div_layout.html.twig`_, wraps each form field inside a ``<div>`` element
   and it's the theme used by default in Symfony applications unless you configure
@@ -182,6 +183,8 @@ of form themes:
 
         {# ... #}
 
+.. _create-your-own-form-theme:
+
 Creating your Own Form Theme
 ----------------------------
 

form/form_themes.rst

@@ -8,21 +8,22 @@ Validation Groups
 -----------------
 
 If your object takes advantage of :doc:`validation groups </validation/groups>`,
-you'll need to specify which validation group(s) your form should use::
+you'll need to specify which validation group(s) your form should use. Pass
+this as an option when :ref:`creating forms in controllers <creating-forms-in-controllers>`::
 
     $form = $this->createFormBuilder($user, [
         'validation_groups' => ['registration'],
     ])->add(...);
 
-If you're creating :ref:`form classes <form-creating-form-classes>` (a good
-practice), then you'll need to add the following to the ``configureOptions()``
-method::
+When :ref:`creating forms in classes <creating-forms-in-classes>`, add the
+following to the ``configureOptions()`` method::
 
     use Symfony\Component\OptionsResolver\OptionsResolver;
 
     public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults([
+            // ...
             'validation_groups' => ['registration'],
         ]);
     }