@@ -7,12 +7,8 @@ DateType Field
77A field that allows the user to modify date information via a variety of
88different HTML elements.
99
10- The underlying data used for this field type can be a ``DateTime `` object,
11- a string, a timestamp or an array. As long as the `input `_ option is set
12- correctly, the field will take care of all of the details.
13-
14- The field can be rendered as a single text box, three text boxes (month,
15- day and year) or three select boxes (see the `widget `_ option).
10+ This field can be rendered in a variety of different ways via the `widget `_ option
11+ and can understand a number of different input formats via the `input `_ option.
1612
1713+----------------------+-----------------------------------------------------------------------------+
1814| Underlying Data Type | can be ``DateTime ``, string, timestamp, or array (see the ``input `` option) |
@@ -56,31 +52,78 @@ This field type is highly configurable, but easy to use. The most important
5652options are ``input `` and ``widget ``.
5753
5854Suppose that you have a ``publishedAt `` field whose underlying date is a
59- ``DateTime `` object. The following configures the ``DateType `` type for that
60- field as three different choice fields::
55+ ``DateTime `` object. The following configures the ``date `` type for that
56+ field as ** three different choice fields ** ::
6157
6258 use Symfony\Component\Form\Extension\Core\Type\DateType;
6359 // ...
6460
6561 $builder->add('publishedAt', DateType::class, array(
66- 'input' => 'datetime',
6762 'widget' => 'choice',
6863 ));
6964
70- The ``input `` option *must * be changed to match the type of the underlying
71- date data. For example, if the ``publishedAt `` field's data were a unix
72- timestamp, you'd need to set ``input `` to ``timestamp ``::
65+ If your underlying date is *not * a ``DateTime `` object (e.g. it's a unix timestamp),
66+ configure the `input `_ option.
67+
68+ Rendering a single HTML5 Textbox
69+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70+
71+ For a better user experience, you may want to render a single text field and use
72+ some kind of "date picker" to help your user fill in the right format. To do that,
73+ use the ``single_text `` widget::
7374
7475 use Symfony\Component\Form\Extension\Core\Type\DateType;
7576 // ...
7677
7778 $builder->add('publishedAt', DateType::class, array(
78- 'input' => 'timestamp',
79- 'widget' => 'choice',
79+ // render as a single text box
80+ 'widget' => 'single_text',
81+ ));
82+
83+ This will render as an ``input type="date" `` HTML5 field, which means that **some -
84+ but not all - browsers will add nice date picker functionality to the field **. If you
85+ want to be absolutely sure that *every * user has a consistent date picker, use an
86+ external JavaScript library.
87+
88+ For example, suppose you want to use the `Bootstrap Datepicker `_ library. First,
89+ make the following changes::
90+
91+ use Symfony\Component\Form\Extension\Core\Type\DateType;
92+ // ...
93+
94+ $builder->add('publishedAt', DateType::class, array(
95+ 'widget' => 'single_text',
96+
97+ // do not render as type="date", to avoid HTML5 date pickers
98+ 'html5' => false,
99+
100+ // add a class that can eb selected in JavaScript
101+ 'attr' => ['class' => 'js-datepicker'],
80102 ));
81103
82- The field also supports an ``array `` and ``string `` as valid ``input `` option
83- values.
104+ Assuming you're using jQuery, you can initialize the date picker via:
105+
106+ .. code-block :: html
107+
108+ <script >
109+ $ (document ).ready (function () {
110+ $ (' .js-datepicker' datepicker ({
111+ format: ' yyyy-mm-dd'
112+ });
113+ });
114+ </script >
115+
116+ This ``format `` key tells the date picker to use the date format that Symfony expects.
117+ This can be tricky: if the date picker is misconfigured, Symfony won't understand
118+ the format and will throw a validation error. You can also configure the format
119+ that Symfony should expect via the `format `_ option.
120+
121+ .. caution ::
122+
123+ The string used by a JavaScript date picker to describe its format (e.g. ``yyyy-mm-dd ``)
124+ may not match the string that Symfony uses (e.g. ``yyyy-MM-dd ``). This is because
125+ different libraries use different formatting rules to describe the date format.
126+ Be aware of this - it can be tricky to make the formats truly match!
84127
85128Field Options
86129-------------
@@ -182,3 +225,5 @@ Field Variables
182225+--------------+------------+----------------------------------------------------------------------+
183226| date_pattern | ``string `` | A string with the date format to use. |
184227+--------------+------------+----------------------------------------------------------------------+
228+
229+ .. _`Bootstrap Datepicker` : https://github.com/eternicode/bootstrap-datepicker
0 commit comments