feature #4085 [Component][Forms] add missing features introduced in 2.3 (xabbuh)

weaverryan · weaverryan · commit d3b5ba29f42b · 2014-10-19T14:04:26.000-04:00
This PR was merged into the 2.3 branch. Discussion ---------- [Component][Forms] add missing features introduced in 2.3 | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes (symfony/symfony#6522) | Applies to | all | Fixed tickets | #2969 - [x] use ``submit()`` instead of ``bind()`` to manually submit a form - [x] configure method and action of a form - [ ] ~~render a form's start and its end separately~~ (see [the comment](#4085 (comment))) - [ ] configure buttons Commits ------- 33f6422 [Forms] add missing features being new in 2.3
diff --git 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
@@ -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
@@ -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
@@ -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:
