@@ -7,12 +7,8 @@ date Field Type
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,24 +52,68 @@ options are ``input`` and ``widget``.
5652
5753Suppose that you have a ``publishedAt `` field whose underlying date is a
5854``DateTime `` object. The following configures the ``date `` type for that
59- field as three different choice fields::
55+ field as** three different choice fields ** ::
6056
6157 $builder->add('publishedAt', 'date', array(
62- 'input' => 'datetime',
6358 'widget' => 'choice',
6459 ));
6560
66- The ``input `` option *must * be changed to match the type of the underlying
67- date data. For example, if the ``publishedAt `` field's data were a unix
68- timestamp, you'd need to set ``input `` to ``timestamp ``::
61+ If your underlying date is *not * a ``DateTime `` object (e.g. it's a unix timestamp),
62+ configure the `input `_ option.
63+
64+ Rendering a single HTML5 Textbox
65+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66+
67+ For a better user experience, you may want to render a single text field and use
68+ some kind of "date picker" to help your user fill in the right format. To do that,
69+ use the ``single_text `` widget::
6970
7071 $builder->add('publishedAt', 'date', array(
71- 'input' => 'timestamp',
72- 'widget' => 'choice ',
72+ // render as a single text box
73+ 'widget' => 'single_text ',
7374 ));
7475
75- The field also supports an ``array `` and ``string `` as valid ``input `` option
76- values.
76+ This will render as an ``input type="date" `` HTML5 field, which means that **some -
77+ but not all - browsers will add nice date picker functionality to the field **. If you
78+ want to be absolutely sure that *every * user has a consistent date picker, use an
79+ external JavaScript library.
80+
81+ For example, suppose you want to use the `Bootstrap Datepicker `_ library. First,
82+ make the following changes::
83+
84+ $builder->add('publishedAt', 'date', array(
85+ 'widget' => 'single_text',
86+
87+ // do not render as type="date", to avoid HTML5 date pickers
88+ 'html5' => false,
89+
90+ // add a class that can eb selected in JavaScript
91+ 'attr' => ['class' => 'js-datepicker'],
92+ ));
93+
94+ Assuming you're using jQuery, you can initialize the date picker via:
95+
96+ ..code-block ::html
97+
98+ <script >
99+ $ (document ).ready (function () {
100+ $ (' .js-datepicker' datepicker ({
101+ format: ' yyyy-mm-dd'
102+ });
103+ });
104+ script >
105+
106+ This ``format `` key tells the date picker to use the date format that Symfony expects.
107+ This can be tricky: if the date picker is misconfigured, Symfony won't understand
108+ the format and will throw a validation error. You can also configure the format
109+ that Symfony should expect via the `format `_ option.
110+
111+ ..caution ::
112+
113+ The string used by a JavaScript date picker to describe its format (e.g. ``yyyy-mm-dd ``)
114+ may not match the string that Symfony uses (e.g. ``yyyy-MM-dd ``). This is because
115+ different libraries use different formatting rules to describe the date format.
116+ Be aware of this - it can be tricky to make the formats truly match!
77117
78118Field Options
79119-------------
@@ -171,3 +211,5 @@ Field Variables
171211+--------------+------------+----------------------------------------------------------------------+
172212| date_pattern| ``string ``| A string with the date format to use.|
173213+--------------+------------+----------------------------------------------------------------------+
214+
215+ .. _`Bootstrap Datepicker` :https://github.com/eternicode/bootstrap-datepicker