[#2092] Minor tweaks to new form request handlers and corresponding twig functions

weaverryan · weaverryan · commit adf898937ef5 · 2013-04-21T12:17:45.000-04:00
diff --git a/book/forms.rst b/book/forms.rst
@@ -162,10 +162,11 @@ helper functions:
     change the request method and the target URL of the form.
 
 That's it! By printing ``form(form)``, each field in the form is rendered, along
-with a label and error message (if there is one). As easy as this is, it's not
-very flexible (yet). Usually, you'll want to render each form field individually
-so you can control how the form looks. You'll learn how to do that in the
-":ref:`form-rendering-template`" section.
+with a label and error message (if there is one). The ``form`` function also
+surrounds everything in the necessary HTML ``form`` tag. As easy as this is,
+it's not very flexible (yet). Usually, you'll want to render each form field
+individually so you can control how the form looks. You'll learn how to do
+that in the ":ref:`form-rendering-template`" section.
 
 Before moving on, notice how the rendered ``task`` input field has the value
 of the ``task`` property from the ``$task`` object (i.e. "Write a blog post").
@@ -188,6 +189,8 @@ it into a format that's suitable for being rendered in an HTML form.
 .. index::
   single: Forms; Handling form submission
 
+.. _book-form-handling-form-submissions:
+
 Handling Form Submissions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -222,8 +225,8 @@ controller::
 
 .. versionadded:: 2.3
     The :method:`Symfony\Component\Form\FormInterface::handleRequest` method was
-    added in Symfony 2.3. Before you had to do some manual work to achieve the
-    same result.
+    added in Symfony 2.3. Previously, the now-deprecated ``bind`` function
+    was used. For details on that method, see :doc:`/cookbook/form/deprecated_bind`.
 
 This controller follows a common pattern for handling forms, and has three
 possible paths:
@@ -669,39 +672,46 @@ used the ``form_row`` helper:
 
     .. code-block:: html+jinja
 
-        {{ form_errors(form) }}
+        {{ form_start(form) }}
+            {{ form_errors(form) }}
 
-        <div>
-            {{ form_label(form.task) }}
-            {{ form_errors(form.task) }}
-            {{ form_widget(form.task) }}
-        </div>
+            <div>
+                {{ form_label(form.task) }}
+                {{ form_errors(form.task) }}
+                {{ form_widget(form.task) }}
+            </div>
 
-        <div>
-            {{ form_label(form.dueDate) }}
-            {{ form_errors(form.dueDate) }}
-            {{ form_widget(form.dueDate) }}
-        </div>
+            <div>
+                {{ form_label(form.dueDate) }}
+                {{ form_errors(form.dueDate) }}
+                {{ form_widget(form.dueDate) }}
+            </div>
 
-        {{ form_rest(form) }}
+        <input type="submit" />
+
+        {{ form_end(form) }}
 
     .. code-block:: html+php
 
-        <?php echo $view['form']->errors($form) ?>
+        <?php echo $view['form']->start($form) ?>
+
+            <?php echo $view['form']->errors($form) ?>
 
-        <div>
-            <?php echo $view['form']->label($form['task']) ?>
-            <?php echo $view['form']->errors($form['task']) ?>
-            <?php echo $view['form']->widget($form['task']) ?>
-        </div>
+            <div>
+                <?php echo $view['form']->label($form['task']) ?>
+                <?php echo $view['form']->errors($form['task']) ?>
+                <?php echo $view['form']->widget($form['task']) ?>
+            </div>
 
-        <div>
-            <?php echo $view['form']->label($form['dueDate']) ?>
-            <?php echo $view['form']->errors($form['dueDate']) ?>
-            <?php echo $view['form']->widget($form['dueDate']) ?>
-        </div>
+            <div>
+                <?php echo $view['form']->label($form['dueDate']) ?>
+                <?php echo $view['form']->errors($form['dueDate']) ?>
+                <?php echo $view['form']->widget($form['dueDate']) ?>
+            </div>
 
-        <?php echo $view['form']->rest($form) ?>
+            <input type="submit" />
+
+        <?php echo $view['form']->end($form) ?>
 
 If the auto-generated label for a field isn't quite right, you can explicitly
 specify it:
@@ -777,8 +787,8 @@ that can be used with each.
 Changing the Action and Method of a Form
 ----------------------------------------
 
-So far, we have used the ``form_start()`` helper to render the form's start tag
-and assumed that each form is submitted to the same URL in a POST request.
+So far, the ``form_start()`` helper has been used to render the form's start
+tag and we assumed that each form is submitted to the same URL in a POST request.
 Sometimes you want to change these parameters. You can do so in a few different
 ways. If you build your form in the controller, you can use ``setAction()`` and
 ``setMethod()``::
@@ -795,16 +805,16 @@ ways. If you build your form in the controller, you can use ``setAction()`` and
     This example assumes that you've created a route called ``target_route``
     that points to the controller that processes the form.
 
-In :ref:`book-form-creating-form-classes` you will learn how to outsource the
-form building code into separate classes. When using such a form class in the
-controller, you can pass the action and method as form options::
+In :ref:`book-form-creating-form-classes` you will learn how to move the
+form building code into separate classes. When using an external form class
+in the controller, you can pass the action and method as form options::
 
     $form = $this->createForm(new TaskType(), $task, array(
         'action' => $this->generateUrl('target_route'),
         'method' => 'GET',
     ));
 
-At last, you can override the action and method in the template by passing them
+Finally, you can override the action and method in the template by passing them
 to the ``form()`` or the ``form_start()`` helper:
 
 .. configuration-block::
@@ -1100,7 +1110,6 @@ as the original ``Task`` fields:
             {{ form_row(form.category.name) }}
         </div>
 
-        {{ form_rest(form) }}
         {# ... #}
 
     .. code-block:: html+php
@@ -1112,7 +1121,6 @@ as the original ``Task`` fields:
             <?php echo $view['form']->row($form['category']['name']) ?>
         </div>
 
-        <?php echo $view['form']->rest($form) ?>
         <!-- ... -->
 
 When the user submits the form, the submitted data for the ``Category`` fields
@@ -1480,7 +1488,7 @@ ensures that the user - not some other entity - is submitting the given data.
 Symfony automatically validates the presence and accuracy of this token.
 
 The ``_token`` field is a hidden field and will be automatically rendered
-if you include the ``form_rest()`` function in your template, which ensures
+if you include the ``form_end()`` function in your template, which ensures
 that all un-rendered fields are output.
 
 The CSRF token can be customized on a form-by-form basis. For example::
@@ -1543,7 +1551,7 @@ an array of the submitted data. This is actually really easy::
 
         $form->handleRequest($request);
 
-        if ($form->isBound()) {
+        if ($form->isValid()) {
             // data is an array with "name", "email", and "message" keys
             $data = $form->getData();
         }
diff --git a/cookbook/doctrine/file_uploads.rst b/cookbook/doctrine/file_uploads.rst
@@ -222,6 +222,7 @@ The following controller shows you how to handle the entire process::
     // ...
     use Acme\DemoBundle\Entity\Document;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
+    use Symfony\Component\HttpFoundation\Request;
     // ...
 
     /**
diff --git a/cookbook/doctrine/registration_form.rst b/cookbook/doctrine/registration_form.rst
@@ -234,7 +234,7 @@ controller for displaying the registration form::
         {
             $registration = new Registration();
             $form = $this->createForm(new RegistrationType(), $registration, array(
-                'action' => $this->generateUrl('create'),
+                'action' => $this->generateUrl('account_create'),
             ));
 
             return $this->render(
@@ -251,8 +251,9 @@ and its template:
     {# src/Acme/AccountBundle/Resources/views/Account/register.html.twig #}
     {{ form(form) }}
 
-Finally, create the controller which handles the form submission.  This performs
-the validation and saves the data into the database::
+Finally, create the controller (and corresponding ``account_create``) which
+handles the form submission.  This performs the validation and saves the data
+into the database::
 
     public function createAction(Request $request)
     {
diff --git a/cookbook/form/deprecated_bind.rst b/cookbook/form/deprecated_bind.rst
@@ -0,0 +1,63 @@
+.. index::
+   single: Form; Form testing
+
+How to use the (deprecated) bind Function to handle Form Submissions
+====================================================================
+
+In Symfony 2.3, a new :method:`Symfony\Component\Form\FormInterface::handleRequest`
+method was added, which makes handling form submissions easier than ever::
+
+    use Symfony\Component\HttpFoundation\Request;
+    // ...
+
+    public function newAction(Request $request)
+    {
+        $form = $this->createFormBuilder()
+            // ...
+            ->getForm();
+
+        $form->handleRequest($request);
+
+        if ($form->isValid()) {
+            // perform some action...
+
+            return $this->redirect($this->generateUrl('task_success'));
+        }
+        
+        return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
+            'form' => $form->createView(),
+        ));
+    }
+
+.. tip::
+
+    To see more about this method, read :ref:`book-form-handling-form-submissions`.
+
+Prior to this, the :method:`Symfony\Component\Form\FormInterface::bind` method
+was used instead::
+
+    use Symfony\Component\HttpFoundation\Request;
+    // ...
+
+    public function newAction(Request $request)
+    {
+        $form = $this->createFormBuilder()
+            // ...
+            ->getForm();
+
+        if ($request->isMethod('POST')) {
+            $form->bind($request);
+
+            if ($form->isValid()) {
+                // perform some action...
+
+                return $this->redirect($this->generateUrl('task_success'));
+            }
+        }
+
+        return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
+            'form' => $form->createView(),
+        ));
+    }
+
+This still works, but is deprecated and will be removed in Symfony 3.0.
diff --git a/cookbook/form/index.rst b/cookbook/form/index.rst
@@ -13,3 +13,4 @@ Form
     use_virtuals_forms
     unit_testing
     use_empty_data
+    deprecated_bind
diff --git a/cookbook/form/unit_testing.rst b/cookbook/form/unit_testing.rst
@@ -53,6 +53,7 @@ The simplest ``TypeTestCase`` implementation looks like the following::
             $object = new TestObject();
             $object->fromArray($formData);
 
+            // bind the data to the form directly
             $form->bind($formData);
 
             $this->assertTrue($form->isSynchronized());
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -87,6 +87,7 @@
   * :doc:`/cookbook/form/use_virtuals_forms`
   * :doc:`/cookbook/form/unit_testing`
   * :doc:`/cookbook/form/use_empty_data`
+  * :doc:`/cookbook/form/deprecated_bind`
   * (validation) :doc:`/cookbook/validation/custom_constraint`
   * (doctrine) :doc:`/cookbook/doctrine/file_uploads`
 
diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst
@@ -36,7 +36,7 @@ Renders the HTML of a complete form.
     {# render the form and change the submission method #}
     {{ form(form, {'method': 'GET'}) }}
 
-You will mostly use this helper for prototyping and if you use custom form
+You will mostly use this helper for prototyping or if you use custom form
 themes. If you need more flexibility in rendering the form, you should use
 the other helpers to render individual parts of the form instead:
 
@@ -51,9 +51,6 @@ the other helpers to render individual parts of the form instead:
         <input type="submit" value="Submit me"/>
     {{ form_end(form) }}
 
-See ":ref:`twig-reference-form-variables`" to learn more about the ``variables``
-argument.
-
 .. _reference-forms-twig-start:
 
 form_start(view, variables)
@@ -68,9 +65,6 @@ correct ``enctype`` property if the form contains upload fields.
     {# render the start tag and change the submission method #}
     {{ form_start(form, {'method': 'GET'}) }}
 
-See ":ref:`twig-reference-form-variables`" to learn more about the ``variables``
-argument.
-
 .. _reference-forms-twig-end:
 
 form_end(view, variables)
@@ -90,9 +84,6 @@ false:
     {# don't render unrendered fields #}
     {{ form_end(form, {'render_rest': false}) }}
 
-See ":ref:`twig-reference-form-variables`" to learn more about the ``variables``
-argument.
-
 .. _reference-forms-twig-label:
 
 form_label(view, label, variables)
