enhanced documentation for forms

doc/providers/form.rst

@@ -52,13 +52,20 @@ Usage
 The FormServiceProvider provides a ``form.factory`` service. Here is a usage
 example::
 
-    $app->get('/hello/{name}', function ($name) use ($app) {
-        return "Hello $name!";
-    })->bind('hello');
-
-    $app->match('/', function (Request $request) use ($app) {
-        $form = $app['form.factory']->createBuilder('form')
-            ->add('name', 'text')
+    $app->match('/form', function (Request $request) use ($app) {
+        // some default data for when the form is displayed the first time
+        $data = array(
+            'name' => 'Your name',
+            'email' => 'Your email',
+        );
+
+        $form = $app['form.factory']->createBuilder('form', $data)
+            ->add('name')
+            ->add('email')
+            ->add('gender', 'choice', array(
+                'choices' => array(1 => 'male', 2 => 'female'),
+                'expanded' => true,
+            ))
             ->getForm();
 
         if ('POST' == $request->getMethod()) {
@@ -69,14 +76,16 @@ example::
 
                 // do something with the data
 
-                return $app->redirect('/hello/{name}');
+                // redirect somewhere
+                return $app->redirect('...');
             }
         }
 
+        // display the form
         return $app['twig']->render('index.twig', array('form' => $form->createView()));
     });
 
-Put this in your template file named ``views/index.twig``:
+And here is the ``index.twig`` form template:
 
 .. code-block:: jinja
 
@@ -100,6 +109,14 @@ form by adding constraints on the fields::
         ->add('name', 'text', array(
             'constraints' => array(new Assert\NotBlank(), new Assert\MinLength(5))
         ))
+        ->add('email', 'text', array(
+            'constraints' => new Assert\Email()
+        ))
+        ->add('gender', 'choice', array(
+            'choices' => array(1 => 'male', 2 => 'female'),
+            'expanded' => true,
+            'constraints' => new Assert\Choice(array(1, 2)),
+        ))
         ->getForm();
 
 For more information, consult the `Symfony2 Forms documentation