From 1bf3ce0350527de5571ecc9d56440da79ee128f6 Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Mon, 6 Jan 2014 22:46:07 +0100 Subject: [PATCH 1/7] [Reference][Form Types] Add missing docs for "action" and "method" option --- reference/forms/types/form.rst | 3 +++ reference/forms/types/options/action.rst.inc | 11 +++++++++++ reference/forms/types/options/method.rst.inc | 20 ++++++++++++++++++++ 3 files changed, 34 insertions(+) create mode 100644 reference/forms/types/options/action.rst.inc create mode 100644 reference/forms/types/options/method.rst.inc diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst index dfe67119f6c..14200097904 100644 --- a/reference/forms/types/form.rst +++ b/reference/forms/types/form.rst @@ -59,3 +59,6 @@ on all fields. .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc +.. include:: /reference/forms/types/options/action.rst.inc + +.. include:: /reference/forms/types/options/method.rst.inc diff --git a/reference/forms/types/options/action.rst.inc b/reference/forms/types/options/action.rst.inc new file mode 100644 index 00000000000..821197ae24f --- /dev/null +++ b/reference/forms/types/options/action.rst.inc @@ -0,0 +1,11 @@ +.. versionadded:: 2.3 + The ``action`` option was introduced in Symfony 2.3. + +action +~~~~~~ + +**type**: ``string`` **default**: empty string + +This option specifies where to send the form's data on submission (usually an +URI). An empty value is considered a same-document references, i.e. the form +will be submitted to the same URI that rendered the form. diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc new file mode 100644 index 00000000000..7744367205d --- /dev/null +++ b/reference/forms/types/options/method.rst.inc @@ -0,0 +1,20 @@ +.. versionadded:: 2.3 + The ``method`` option was introduced in Symfony 2.3. + +method +~~~~~~ + +**type**: ``string`` **default**: ``POST`` + +This option specifies the HTTP method used to submit the form's data. Possible +values are: + +* POST +* GET +* PUT +* DELETE +* PATCH + +.. note:: + Using ``PUT``, ``PATCH`` and ``DELETE`` is only allowed if + :ref:`configuration-framework-http_method_override` is enabled. From 83ff4b1843f3f82369f494ffa3d17278a98b29fd Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Tue, 7 Jan 2014 07:31:18 +0100 Subject: [PATCH 2/7] Improve descriptions --- reference/forms/types/options/action.rst.inc | 3 ++- reference/forms/types/options/method.rst.inc | 8 ++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/reference/forms/types/options/action.rst.inc b/reference/forms/types/options/action.rst.inc index 821197ae24f..bd1bfa10e6f 100644 --- a/reference/forms/types/options/action.rst.inc +++ b/reference/forms/types/options/action.rst.inc @@ -7,5 +7,6 @@ action **type**: ``string`` **default**: empty string This option specifies where to send the form's data on submission (usually an -URI). An empty value is considered a same-document references, i.e. the form +URI). It's value is rendered as the ``action`` attribute of the ``form`` +element. An empty value is considered a same-document reference, i.e. the form will be submitted to the same URI that rendered the form. diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc index 7744367205d..27efd4840ff 100644 --- a/reference/forms/types/options/method.rst.inc +++ b/reference/forms/types/options/method.rst.inc @@ -6,8 +6,9 @@ method **type**: ``string`` **default**: ``POST`` -This option specifies the HTTP method used to submit the form's data. Possible -values are: +This option specifies the HTTP method used to submit the form's data. It's +value is rendered as the ``method`` attribute of the ``form`` element. +Possible values are: * POST * GET @@ -15,6 +16,9 @@ values are: * DELETE * PATCH +As PUT, DELETE and PATCH are not nativly supported by most clients, Symfony +simulates them, see :doc:`/cookbook/routing/method_parameters`. + .. note:: Using ``PUT``, ``PATCH`` and ``DELETE`` is only allowed if :ref:`configuration-framework-http_method_override` is enabled. From a63694532a62e4f6232b95c3d4dcfa2f6ac74b98 Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Tue, 7 Jan 2014 12:10:42 +0100 Subject: [PATCH 3/7] Fixes after review --- reference/forms/types/options/method.rst.inc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc index 27efd4840ff..91c5a99ba2f 100644 --- a/reference/forms/types/options/method.rst.inc +++ b/reference/forms/types/options/method.rst.inc @@ -17,8 +17,10 @@ Possible values are: * PATCH As PUT, DELETE and PATCH are not nativly supported by most clients, Symfony -simulates them, see :doc:`/cookbook/routing/method_parameters`. +simulates them. For more information see +:doc:`/cookbook/routing/method_parameters`. .. note:: + Using ``PUT``, ``PATCH`` and ``DELETE`` is only allowed if :ref:`configuration-framework-http_method_override` is enabled. From cecc762018ce808e65bf2bc68764bc2c102aceeb Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Tue, 7 Jan 2014 22:27:06 +0100 Subject: [PATCH 4/7] Update "method" description --- reference/forms/types/options/method.rst.inc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc index 91c5a99ba2f..b6df4c74374 100644 --- a/reference/forms/types/options/method.rst.inc +++ b/reference/forms/types/options/method.rst.inc @@ -7,7 +7,8 @@ method **type**: ``string`` **default**: ``POST`` This option specifies the HTTP method used to submit the form's data. It's -value is rendered as the ``method`` attribute of the ``form`` element. +value is rendered as the ``method`` attribute of the ``form`` element and to +perform some consistency checks when evaluating the form after submission. Possible values are: * POST @@ -16,11 +17,10 @@ Possible values are: * DELETE * PATCH -As PUT, DELETE and PATCH are not nativly supported by most clients, Symfony -simulates them. For more information see -:doc:`/cookbook/routing/method_parameters`. +.. note: -.. note:: - - Using ``PUT``, ``PATCH`` and ``DELETE`` is only allowed if - :ref:`configuration-framework-http_method_override` is enabled. + If not natively supported by a client, Symfony allows to simulate PUT, + DELETE and PATCH requests by using a POST request instead and passing the + intended "real" method by either using a ``X-HTTP-Method-Override`` + request header or by passing it via the special ``_method`` data field. + For more information see :doc:`/cookbook/routing/method_parameters`. From 70ca6dad2f7fec42ea6e3f80435016ad3366b616 Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Sat, 11 Jan 2014 06:55:36 +0100 Subject: [PATCH 5/7] Improvements after review --- reference/forms/types/options/action.rst.inc | 2 +- reference/forms/types/options/method.rst.inc | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/forms/types/options/action.rst.inc b/reference/forms/types/options/action.rst.inc index bd1bfa10e6f..70977722000 100644 --- a/reference/forms/types/options/action.rst.inc +++ b/reference/forms/types/options/action.rst.inc @@ -7,6 +7,6 @@ action **type**: ``string`` **default**: empty string This option specifies where to send the form's data on submission (usually an -URI). It's value is rendered as the ``action`` attribute of the ``form`` +URI). Its value is rendered as the ``action`` attribute of the ``form`` element. An empty value is considered a same-document reference, i.e. the form will be submitted to the same URI that rendered the form. diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc index b6df4c74374..00da8e316c6 100644 --- a/reference/forms/types/options/method.rst.inc +++ b/reference/forms/types/options/method.rst.inc @@ -6,10 +6,10 @@ method **type**: ``string`` **default**: ``POST`` -This option specifies the HTTP method used to submit the form's data. It's -value is rendered as the ``method`` attribute of the ``form`` element and to -perform some consistency checks when evaluating the form after submission. -Possible values are: +This option specifies the HTTP method used to submit the form's data. Its +value is rendered as the ``method`` attribute of the ``form`` element and is +used to decide whether to process the form submission in the +``handleRequest()`` method after submission. Possible values are: * POST * GET From 455549502d341d5ba01554f545be11495c00f999 Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Sat, 11 Jan 2014 07:04:46 +0100 Subject: [PATCH 6/7] Update note wording for "method" option --- reference/forms/types/options/method.rst.inc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc index 00da8e316c6..fbcc7519e3e 100644 --- a/reference/forms/types/options/method.rst.inc +++ b/reference/forms/types/options/method.rst.inc @@ -19,8 +19,7 @@ used to decide whether to process the form submission in the .. note: - If not natively supported by a client, Symfony allows to simulate PUT, - DELETE and PATCH requests by using a POST request instead and passing the - intended "real" method by either using a ``X-HTTP-Method-Override`` - request header or by passing it via the special ``_method`` data field. - For more information see :doc:`/cookbook/routing/method_parameters`. + When the method is PUT, PATCH, or DELETE, Symfony will automatically + render a ``_method`` hidden field in your form. This is used to "fake" + these HTTP methods, as they're not supported on standard browsers. For + more information, see :doc:`/cookbook/routing/method_parameters`. From 793c8a046252ec815d0e39c2a984b4a93bb813df Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Fri, 24 Jan 2014 21:31:59 +0100 Subject: [PATCH 7/7] Add note about the PATCH method --- reference/forms/types/options/method.rst.inc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc index fbcc7519e3e..d1d6c84b1ce 100644 --- a/reference/forms/types/options/method.rst.inc +++ b/reference/forms/types/options/method.rst.inc @@ -23,3 +23,9 @@ used to decide whether to process the form submission in the render a ``_method`` hidden field in your form. This is used to "fake" these HTTP methods, as they're not supported on standard browsers. For more information, see :doc:`/cookbook/routing/method_parameters`. + +.. note: + + Only the PATCH method allows submitting partial data without that missing + fields are set to ``null`` in the underlying data (preserving default + values, if any).