merged branch alOneh/form-docs (PR #77)

Commits
-------

256859b6 [docs] Documentation for FormExtension

Discussion
----------

Form docs

[docs] FormExtension docs

---------------------------------------------------------------------------

by alOneh at 2011-05-11T17:58:13Z

I think the form doc is now clean, isnt'it ?

---------------------------------------------------------------------------

by brikou at 2011-06-27T19:19:46Z

👍

---------------------------------------------------------------------------

by rkmax at 2011-07-29T19:30:28Z

thanks, i'm looking for this

---------------------------------------------------------------------------

by alOneh at 2011-07-29T19:32:29Z

@fabpot can you merge this if you are agree with that pull ?

---------------------------------------------------------------------------

by rkmax at 2011-07-30T14:27:09Z

can you explain what /vendor/symfony/src need exactly

---------------------------------------------------------------------------

by alOneh at 2011-07-31T13:27:39Z

/vendor/symfony/src is use to load the Symfony Form component, the [Symfony Bridge](http://api.symfony.com/2.0/Symfony/Bridge/Twig/Extension.html) who provide extensions for Form and Translation in Twig

---------------------------------------------------------------------------

by rkmax at 2011-08-01T09:51:30Z

thanks @alOneh

---------------------------------------------------------------------------

by igorw at 2011-09-18T15:06:44Z

@fabpot is there anything missing? Would be nice to get this merged finally.

---------------------------------------------------------------------------

by alOneh at 2011-09-20T08:42:49Z

@fabpot are you agree with that PR ?

---------------------------------------------------------------------------

by alOneh at 2011-09-22T10:39:23Z

I just updated the form provider documenation

---------------------------------------------------------------------------

by igorw at 2011-10-07T14:41:17Z

Keep an eye on #182.

---------------------------------------------------------------------------

by alOneh at 2011-10-07T15:00:28Z

Seems good to me. I will update the doc when it will be merged.

---------------------------------------------------------------------------

by alOneh at 2011-10-09T12:57:51Z

@fabpot : I updated my proposal PR for the FormServiceProvider. Can you check if there is anything missing ? /cc igorw

---------------------------------------------------------------------------

by igorw at 2011-10-09T13:05:49Z

Looks good to me.

Might be interesting to add another section about validation using the `validation_constraint` form option, see also http://knplabs.com/en/blog-csi/symfony-validators-standalone

---------------------------------------------------------------------------

by alOneh at 2011-10-09T14:02:38Z

I updated the example with the validation_constraint, I think now its good.

---------------------------------------------------------------------------

by alOneh at 2011-10-10T19:51:56Z

poke @fabpot

---------------------------------------------------------------------------

by igorw at 2011-10-10T19:55:05Z

Looks good to me.

---------------------------------------------------------------------------

by igorw at 2011-10-16T23:53:48Z

Hm, maybe validation_constraint should be a separate example. Also we should not use the UrlGenerator.

IMO it needs to be clear that those things are optional.

---------------------------------------------------------------------------

by alOneh at 2011-10-18T09:01:48Z

@igorw, I use the UrlGenerator because I can't get a fully working example without it.

---------------------------------------------------------------------------

by netzhuffle at 2011-11-28T17:15:12Z

@alOneh You could try $request->getUriForPath() instead of the UrlGenerator.

---------------------------------------------------------------------------

by alOneh at 2012-01-16T14:47:20Z

is this PR is ready for merge after the latest change ?

---------------------------------------------------------------------------

by igorw at 2012-01-16T15:02:12Z

It introduces extensions.rst which was renamed to providers.rst. You need to merge upstream master into your branch and then make sure everything is correct.

---------------------------------------------------------------------------

by alOneh at 2012-01-16T15:52:00Z

My mistake. I fix this.

---------------------------------------------------------------------------

by alOneh at 2012-02-12T23:00:03Z

poke @igorw @fabpot

---------------------------------------------------------------------------

by igorw at 2012-02-12T23:04:01Z

This (still) looks good to me.

Minor thing: API docs links should probably be changed to 2.1 now. Not sure if others are also affected.

---------------------------------------------------------------------------

by alOneh at 2012-02-12T23:08:06Z

Others are not yet affected. Maybe in a single PR for all API docs links

---------------------------------------------------------------------------

by alOneh at 2012-02-22T11:03:39Z

poke @igorw , @fabpot

---------------------------------------------------------------------------

by alOneh at 2012-03-02T14:01:17Z

@igorw I updated the docs references to 2.1, ready for merge now ? /cc @fabpot

---------------------------------------------------------------------------

by igorw at 2012-03-02T15:30:52Z

👍

---------------------------------------------------------------------------

by fabpot at 2012-06-13T18:59:12Z

Can you squash your commits. I will then merge and made some changes due to some recent updates to Silex. Thanks.

doc/providers.rst

@@ -58,6 +58,7 @@ the ``Silex\Provider`` namespace:
 * :doc:`UrlGeneratorServiceProvider <providers/url_generator>`
 * :doc:`ValidatorServiceProvider <providers/validator>`
 * :doc:`HttpCacheServiceProvider <providers/http_cache>`
+* :doc:`FormServiceProvider <providers/form>`
 
 Third party providers
 ~~~~~~~~~~~~~~~~~~~~~

doc/providers/form.rst

+FormServiceProvider
+=================
+
+The *FormServiceProvider* provides a service for building forms in
+your application with the Symfony2 Form component.
+
+Parameters
+----------
+
+* **form.secret**: This secret value is used for generating and validating the CSRF token
+  for a specific page. It is very important for you to set this value to a static randomly
+  generated value, to prevent hijacking of your forms.
+  Defaults to md5(__DIR__).
+
+* **form.class_path** (optional): Path to where
+  Symfony2 Form component is located.
+
+Services
+--------
+
+* **form.factory**: An instance of `FormFactory
+  <http://api.symfony.com/master/Symfony/Component/Form/FormFactory.html>`_,
+  that is used for build a form.
+
+* **form.csrf_provider**: An instance of an implementation of the `CsrfProviderInterface
+  <http://api.symfony.com/master/Symfony/Component/Form/Extension/Csrf/CsrfProvider/CsrfProviderInterface.html>`_,
+  defaults to a `DefaultCsrfProvider
+  <http://api.symfony.com/master/Symfony/Component/Form/Extension/Csrf/CsrfProvider/DefaultCsrfProvider.html>`_.
+
+Registering
+-----------
+
+Make sure you place a copy of the Symfony2 Form component in
+``vendor/symfony/src``. You can simply clone the whole Symfony2 into vendor::
+
+    use Silex\Provider\SymfonyBridgesServiceProvider;
+    use Silex\Provider\TranslationServiceProvider;
+    use Silex\Provider\FormServiceProvider;
+
+    $app->register(new SymfonyBridgesServiceProvider(), array(
+        'symfony_bridges.class_path' => __DIR__.'/vendor/symfony/src'
+    ));
+
+    $app->register(new TranslationServiceProvider(), array(
+        'translation.class_path' => __DIR__.'/vendor/symfony/src',
+        'translator.messages'    => array()
+    ));
+
+    $app->register(new FormServiceProvider(), array(
+        'form.class_path' => __DIR__.'/vendor/symfony/src'
+    ));
+
+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 () use ($app) {
+
+        $validation_constraint = new Collection(array(
+            'name' => new NotBlank(),
+        ));
+
+        $form = $app['form.factory']->createBuilder('form')
+            ->add('name', 'text')
+            ->getForm();
+
+        $request = $app['request'];
+
+        if ('POST' == $request->getMethod()) {
+            $form->bindRequest($request);
+
+            if ($form->isValid()) {
+                $data = $form->getData();
+
+                return $app->redirect('/hello/{name}');
+            }
+        }
+
+        return $app['twig']->render('index.twig', array('form' => $form->createView()));
+    })
+    ->method('GET|POST')
+    ->bind('index');
+
+Put this in your template file named ``views/index.twig``:
+
+.. code-block:: jinja
+
+    <form action="{{ app.request.requestUri }}" method="post">
+        {{ form_widget(form) }}
+        <input type="submit" name="submit" />
+    </form>
+
+You can also add validation to your form by creating a constraint and pass it as the
+`validation_constraint` option::
+
+    $validation_constraint = new Collection(array(
+            'name' => new NotBlank(),
+    ));
+
+    $form = $app['form.factory']->createBuilder('form', null, array(
+        'validation_constraint' => $validation_constraint,
+    ));
+
+For more information, consult the `Symfony2 Forms documentation
+<http://symfony.com/doc/2.0/book/forms.html>`_.