From 33f6422dbcafcceb362f39582611ec970ac928ae Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@xabbuh.de>
Date: Sun, 3 Aug 2014 10:25:49 +0200
Subject: [PATCH] [Forms] add missing features being new in 2.3

These features are:

* Use the submit() (instead of bind()) method to manually submit a
  form.
* The ability to change a form's action and method.
---
 book/forms.rst                   |  6 +++++
 components/form/introduction.rst | 43 ++++++++++++++++++++++++++++++++
 cookbook/form/direct_submit.rst  |  2 ++
 reference/forms/types/form.rst   |  4 +++
 4 files changed, 55 insertions(+)

diff --git a/book/forms.rst b/book/forms.rst
index 0998408312e..80d19185e94 100644
--- a/book/forms.rst
+++ b/book/forms.rst
@@ -273,6 +273,12 @@ possible paths:
       from being able to hit the "Refresh" button of their browser and re-post
       the data.
 
+.. 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:`in the cookbook <cookbook-form-call-submit-directly>`.
+
 .. index::
    single: Forms; Multiple Submit Buttons
 
diff --git a/components/form/introduction.rst b/components/form/introduction.rst
index c5b47f8fa87..74b47461b65 100644
--- a/components/form/introduction.rst
+++ b/components/form/introduction.rst
@@ -78,6 +78,12 @@ Behind the scenes, this uses a :class:`Symfony\\Component\\Form\\NativeRequestHa
 object to read data off of the correct PHP superglobals (i.e. ``$_POST`` or
 ``$_GET``) based on the HTTP method configured on the form (POST is default).
 
+.. 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:`in the cookbook <cookbook-form-call-submit-directly>`.
+
 .. sidebar:: Integration with the HttpFoundation Component
 
     If you use the HttpFoundation component, then you should add the
@@ -489,6 +495,43 @@ 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.
 
+Changing a Form's Method and Action
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.3
+    The ability to configure the form method and action was introduced in
+    Symfony 2.3.
+
+By default, a form is submitted to the same URI that rendered the form with
+an HTTP POST request. This behavior can be changed using the :ref:`form-option-action`
+and :ref:`form-option-method` options (the ``method`` option is also used
+by ``handleRequest()`` to determine whether a form has been submitted):
+
+.. configuration-block::
+
+    .. code-block:: php-standalone
+
+        $formBuilder = $formFactory->createBuilder('form', null, array(
+            'action' => '/search',
+            'method' => 'GET',
+        );
+
+        // ...
+
+    .. code-block:: php-symfony
+
+        // ...
+
+        public function searchAction()
+        {
+            $formBuilder = $this->createFormBuilder('form', null, array(
+                'action' => '/search',
+                'method' => 'GET',
+            ));
+
+            // ...
+        }
+
 .. _component-form-intro-handling-submission:
 
 Handling Form Submissions
diff --git a/cookbook/form/direct_submit.rst b/cookbook/form/direct_submit.rst
index 5a40a0aec3f..221f7f534d8 100644
--- a/cookbook/form/direct_submit.rst
+++ b/cookbook/form/direct_submit.rst
@@ -37,6 +37,8 @@ submissions::
 
     To see more about this method, read :ref:`book-form-handling-form-submissions`.
 
+.. _cookbook-form-call-submit-directly:
+
 Calling Form::submit() manually
 -------------------------------
 
diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst
index 976f3c3e5d1..7bf4d09df76 100644
--- a/reference/forms/types/form.rst
+++ b/reference/forms/types/form.rst
@@ -48,6 +48,8 @@ on all types for which ``form`` is the parent type.
 Field Options
 -------------
 
+.. _form-option-action:
+
 .. include:: /reference/forms/types/options/action.rst.inc
 
 .. include:: /reference/forms/types/options/by_reference.rst.inc
@@ -96,6 +98,8 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/max_length.rst.inc
 
+.. _form-option-method:
+
 .. include:: /reference/forms/types/options/method.rst.inc
 
 .. _reference-form-option-pattern: