minor symfony#3429 [Reference][Form Types] Document "with_minutes" time/datetime option (bicpi)

weaverryan · weaverryan · commit e255de9bfec2 · 2014-01-07T15:34:41.000-06:00
This PR was merged into the 2.3 branch. Discussion ---------- [Reference][Form Types] Document "with_minutes" time/datetime option | Q | A | ------------- | --- | Doc fix? | yes | New docs? | yes | Applies to | 2.3+ | Fixed tickets | symfony#3410 (task `time > with_minutes`) The `datetime` field also has a `with_minutes` option. Using the `single_text` widget type might not work as expected using `with_minutes=false` if the browser supports HTML5's `time` input type. Most browsers seem to only support `hh:mm` or `hh:mm:ss` formats for the value attribute (resetting the value to `--:--` if using an hour value only). This might not be the case for every browser because I couldn't find anything in the HTML5 spec that says a partial time cannot be an hour only. I've added a `caution` box for this. Commits ------- 1e88b9d Fix "versionadded" position 8cfb850 [Reference][Form Types] Document "with_minutes" time/datetime option
diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst
@@ -26,6 +26,7 @@ data can be a ``DateTime`` object, a string, a timestamp or an array.
 |                      | - `years`_                                                                  |
 |                      | - `months`_                                                                 |
 |                      | - `days`_                                                                   |
+|                      | - `with_minutes`_                                                           |
 |                      | - `with_seconds`_                                                           |
 |                      | - `model_timezone`_                                                         |
 |                      | - `view_timezone`_                                                          |
@@ -109,6 +110,8 @@ for more details.
 
 .. include:: /reference/forms/types/options/days.rst.inc
 
+.. include:: /reference/forms/types/options/with_minutes.rst.inc
+
 .. include:: /reference/forms/types/options/with_seconds.rst.inc
 
 .. include:: /reference/forms/types/options/model_timezone.rst.inc
diff --git a/reference/forms/types/options/with_minutes.rst.inc b/reference/forms/types/options/with_minutes.rst.inc
@@ -0,0 +1,10 @@
+.. versionadded:: 2.2
+    The ``with_minutes`` option was introduced in Symfony 2.2.
+
+with_minutes
+~~~~~~~~~~~~
+
+**type**: ``Boolean`` **default**: ``true``
+
+Whether or not to include minutes in the input. This will result in an additional
+input to capture minutes.
diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst
@@ -17,6 +17,7 @@ as a ``DateTime`` object, a string, a timestamp or an array.
 +----------------------+-----------------------------------------------------------------------------+
 | Options              | - `widget`_                                                                 |
 |                      | - `input`_                                                                  |
+|                      | - `with_minutes`_                                                           |
 |                      | - `with_seconds`_                                                           |
 |                      | - `hours`_                                                                  |
 |                      | - `minutes`_                                                                |
@@ -83,13 +84,21 @@ widget
 
 The basic way in which this field should be rendered. Can be one of the following:
 
-* ``choice``: renders two (or three if `with_seconds`_ is true) select inputs.
+* ``choice``: renders one, two (default) or three select inputs (hour, minute,
+  second), depending on the `with_minutes`_ and `with_seconds`_ options.
 
-* ``text``: renders a two or three text inputs (hour, minute, second).
+* ``text``: renders one, two (default) or three text inputs (hour, minute,
+  second), depending on the `with_minutes`_ and `with_seconds`_ options.
 
-* ``single_text``: renders a single input of type text. User's input will
+* ``single_text``: renders a single input of type ``time``. User's input will
   be validated against the form ``hh:mm`` (or ``hh:mm:ss`` if using seconds).
 
+.. caution::
+
+    Combining the widget type ``single_text`` and the `with_minutes`_ option
+    set to ``false`` can cause unexpected behavior in the client as the input
+    type ``time`` might not support selecting an hour only.
+
 input
 ~~~~~
 
@@ -106,6 +115,8 @@ your underlying object. Valid values are:
 The value that comes back from the form will also be normalized back into
 this format.
 
+.. include:: /reference/forms/types/options/with_minutes.rst.inc
+
 .. include:: /reference/forms/types/options/with_seconds.rst.inc
 
 .. include:: /reference/forms/types/options/hours.rst.inc
