Skip to content

Commit b8cda8d

Browse files
wouterjwouterj
committed
feature #4817 Add dateinterval type reference (MisatoTremor)
This PR was merged into the master branch. Discussion ---------- Add dateinterval type reference | Q | A | | --- | --- | | Doc fix? | no | | New docs? | yes | | Applies to | 3.2 | | Fixed tickets | #4816 | Commits ------- 3d55585 Add dateinterval type reference
2 parents 06b4761 + 3d55585 commit b8cda8d

File tree

3 files changed

+320
-0
lines changed

3 files changed

+320
-0
lines changed

‎reference/forms/types.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Form Types Reference
2929
types/currency
3030

3131
types/date
32+
types/dateinterval
3233
types/datetime
3334
types/time
3435
types/birthday

‎reference/forms/types/dateinterval.rst

Lines changed: 318 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
.. index::
2+
single: Forms; Fields; DateIntervalType
3+
4+
DateIntervalType Field
5+
======================
6+
7+
.. versionadded:: 3.2
8+
The DateIntervalType field type was introduced in Symfony 3.2.
9+
10+
This field allows the user to select an *interval* of time. For example, if you want to
11+
allow the user to choose *how often* they receive a status email, they could use this
12+
field to choose intervals like every "10 minutes" or "3 days".
13+
14+
The field can be rendered in a variety of different ways (see `widget`_) and can be configured to
15+
give you a ``DateInterval`` object, an `ISO 8601`_ duration string (e.g. ``P1DT12H``)
16+
or an array (see `input`_).
17+
18+
+----------------------+----------------------------------------------------------------------------------+
19+
| Underlying Data Type | can be ``DateInterval``, string or array (see the ``input`` option) |
20+
+----------------------+----------------------------------------------------------------------------------+
21+
| Rendered as | single text box, multiple text boxes or select fields - see the `widget`_ option |
22+
+----------------------+----------------------------------------------------------------------------------+
23+
| Options | - `days`_ |
24+
| | - `hours`_ |
25+
| | - `minutes`_ |
26+
| | - `months`_ |
27+
| | - `seconds`_ |
28+
| | - `weeks`_ |
29+
| | - `input`_ |
30+
| | - `placeholder`_ |
31+
| | - `widget`_ |
32+
| | - `with_days`_ |
33+
| | - `with_hours`_ |
34+
| | - `with_invert`_ |
35+
| | - `with_minutes`_ |
36+
| | - `with_months`_ |
37+
| | - `with_seconds`_ |
38+
| | - `with_weeks`_ |
39+
| | - `with_years`_ |
40+
| | - `years`_ |
41+
+----------------------+----------------------------------------------------------------------------------+
42+
| Inherited | - `data`_ |
43+
| options | - `disabled`_ |
44+
| | - `inherit_data`_ |
45+
| | - `invalid_message`_ |
46+
| | - `invalid_message_parameters`_ |
47+
| | - `mapped`_ |
48+
+----------------------+----------------------------------------------------------------------------------+
49+
| Parent type | :doc:`FormType </reference/forms/types/form>` |
50+
+----------------------+----------------------------------------------------------------------------------+
51+
| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\DateIntervalType` |
52+
+----------------------+----------------------------------------------------------------------------------+
53+
54+
Basic Usage
55+
-----------
56+
57+
This field type is highly configurable, but easy to use. The most important
58+
options are `input`_ and `widget`_.
59+
60+
You can configure *a lot* of different options, including exactly *which* range
61+
options to show (e.g. don't show "months", but *do* show "days")::
62+
63+
$builder->add('remindEvery', DateIntervalType::class, array(
64+
'widget' => 'integer', // render a text field for each part
65+
// 'input' => 'string', // if you want the field to return a ISO 8601 string back to you
66+
67+
// customize which text boxes are shown
68+
'with_years' => false,
69+
'with_months' => false,
70+
'with_days' => true,
71+
'with_hours' => true,
72+
));
73+
74+
Field Options
75+
-------------
76+
77+
days
78+
~~~~
79+
80+
**type**: ``array`` **default**: 0 to 31
81+
82+
List of days available to the days field type. This option is only relevant
83+
when the ``widget`` option is set to ``choice``::
84+
85+
'days' => range(1, 31)
86+
87+
placeholder
88+
~~~~~~~~~~~
89+
90+
**type**: ``string`` or ``array``
91+
92+
If your widget option is set to ``choice``, then this field will be represented
93+
as a series of ``select`` boxes. The ``placeholder`` option can be used to
94+
add a "blank" entry to the top of each select box::
95+
96+
$builder->add('remindEvery', DateIntervalType::class, array(
97+
'placeholder' => '',
98+
));
99+
100+
Alternatively, you can specify a string to be displayed for the "blank" value::
101+
102+
$builder->add('remindEvery', DateIntervalType::class, array(
103+
'placeholder' => array('years' => 'Years', 'months' => 'Months', 'days' => 'Days')
104+
));
105+
106+
hours
107+
~~~~~
108+
109+
**type**: ``array`` **default**: 0 to 24
110+
111+
List of hours available to the hours field type. This option is only relevant
112+
when the ``widget`` option is set to ``choice``::
113+
114+
'hours' => range(1, 24)
115+
116+
input
117+
~~~~~
118+
119+
**type**: ``string`` **default**: ``dateinterval``
120+
121+
The format of the *input* data - i.e. the format that the interval is stored on
122+
your underlying object. Valid values are:
123+
124+
* ``string`` (a string formatted with `ISO 8601`_ standard, e.g. ``P7Y6M5DT12H15M30S``)
125+
* ``dateinterval`` (a ``DateInterval`` object)
126+
* ``array`` (e.g. ``array('days' => '1', 'hours' => '12',)``)
127+
128+
The value that comes back from the form will also be normalized back into
129+
this format.
130+
131+
minutes
132+
~~~~~~~
133+
134+
**type**: ``array`` **default**: 0 to 60
135+
136+
List of minutes available to the minutes field type. This option is only relevant
137+
when the ``widget`` option is set to ``choice``::
138+
139+
'minutes' => range(1, 60)
140+
141+
months
142+
~~~~~~
143+
144+
**type**: ``array`` **default**: 0 to 12
145+
146+
List of months available to the months field type. This option is only relevant
147+
when the ``widget`` option is set to ``choice``::
148+
149+
'months' => range(1, 12)
150+
151+
seconds
152+
~~~~~~~
153+
154+
**type**: ``array`` **default**: 0 to 60
155+
156+
List of seconds available to the seconds field type. This option is only relevant
157+
when the ``widget`` option is set to ``choice``::
158+
159+
'seconds' => range(1, 60)
160+
161+
weeks
162+
~~~~~
163+
164+
**type**: ``array`` **default**: 0 to 52
165+
166+
List of weeks available to the weeks field type. This option is only relevant
167+
when the ``widget`` option is set to ``choice``::
168+
169+
'weeks' => range(1, 52)
170+
171+
widget
172+
~~~~~~
173+
174+
**type**: ``string`` **default**: ``choice``
175+
176+
The basic way in which this field should be rendered. Can be one of the
177+
following:
178+
179+
* ``choice``: renders one to six select inputs for years, months, weeks, days,
180+
hours, minutes and/or seconds, depending on the `with_years`_, `with_months`_,
181+
`with_weeks`_, `with_days`_, `with_hours`_, `with_minutes`_ and `with_seconds`_
182+
options.
183+
Default: Three fields for years, months and days.
184+
185+
* ``text``: renders one to six text inputs for years, months, weeks, days,
186+
hours, minutes and/or seconds, depending on the `with_years`_, `with_months`_,
187+
`with_weeks`_, `with_days`_, `with_hours`_, `with_minutes`_ and `with_seconds`_
188+
options.
189+
Default: Three fields for years, months and days.
190+
191+
* ``integer``: renders one to six integer inputs for years, months, weeks, days,
192+
hours, minutes and/or seconds, depending on the `with_years`_, `with_months`_,
193+
`with_weeks`_, `with_days`_, `with_hours`_, `with_minutes`_ and `with_seconds`_
194+
options.
195+
Default: Three fields for years, months and days.
196+
197+
* ``single_text``: renders a single input of type ``text``. User's input
198+
will be validated against the form ``PnYnMnDTnHnMnS`` (or ``PnW`` if using
199+
only weeks).
200+
201+
with_days
202+
~~~~~~~~~
203+
204+
**type**: ``Boolean`` **default**: ``true``
205+
206+
Whether or not to include days in the input. This will result in an additional
207+
input to capture days.
208+
209+
.. caution::
210+
211+
This can not be used when `with_weeks`_ is enabled.
212+
213+
with_hours
214+
~~~~~~~~~~
215+
216+
**type**: ``Boolean`` **default**: ``false``
217+
218+
Whether or not to include hours in the input. This will result in an additional
219+
input to capture hours.
220+
221+
with_invert
222+
~~~~~~~~~~~
223+
224+
**type**: ``Boolean`` **default**: ``false``
225+
226+
Whether or not to include invert in the input. This will result in an additional
227+
checkbox.
228+
This can not be used when the `widget`_ option is set to ``single_text``.
229+
230+
with_minutes
231+
~~~~~~~~~~~~
232+
233+
**type**: ``Boolean`` **default**: ``false``
234+
235+
Whether or not to include minutes in the input. This will result in an additional
236+
input to capture minutes.
237+
238+
with_months
239+
~~~~~~~~~~~
240+
241+
**type**: ``Boolean`` **default**: ``true``
242+
243+
Whether or not to include months in the input. This will result in an additional
244+
input to capture months.
245+
246+
with_seconds
247+
~~~~~~~~~~~~
248+
249+
**type**: ``Boolean`` **default**: ``false``
250+
251+
Whether or not to include seconds in the input. This will result in an additional
252+
input to capture seconds.
253+
254+
with_weeks
255+
~~~~~~~~~~
256+
257+
**type**: ``Boolean`` **default**: ``false``
258+
259+
Whether or not to include weeks in the input. This will result in an additional
260+
input to capture weeks.
261+
262+
.. caution::
263+
264+
This can not be used when `with_days`_ is enabled.
265+
266+
with_years
267+
~~~~~~~~~~
268+
269+
**type**: ``Boolean`` **default**: ``true``
270+
271+
Whether or not to include years in the input. This will result in an additional
272+
input to capture years.
273+
274+
years
275+
~~~~~
276+
277+
**type**: ``array`` **default**: 0 to 100
278+
279+
List of years available to the years field type. This option is only relevant
280+
when the ``widget`` option is set to ``choice``::
281+
282+
'years' => range(1, 100)
283+
284+
Inherited Options
285+
-----------------
286+
287+
These options inherit from the :doc:`form </reference/forms/types/form>` type:
288+
289+
.. include:: /reference/forms/types/options/data.rst.inc
290+
291+
.. include:: /reference/forms/types/options/disabled.rst.inc
292+
293+
.. include:: /reference/forms/types/options/inherit_data.rst.inc
294+
295+
.. include:: /reference/forms/types/options/invalid_message.rst.inc
296+
297+
.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
298+
299+
.. include:: /reference/forms/types/options/mapped.rst.inc
300+
301+
Field Variables
302+
---------------
303+
304+
============ =========== ========================================
305+
Variable Type Usage
306+
============ =========== ========================================
307+
widget ``mixed`` The value of the `widget`_ option.
308+
with_days ``Boolean`` The value of the `with_days`_ option.
309+
with_invert ``Boolean`` The value of the `with_invert`_ option.
310+
with_hours ``Boolean`` The value of the `with_hours`_ option.
311+
with_minutes ``Boolean`` The value of the `with_minutes`_ option.
312+
with_months ``Boolean`` The value of the `with_months`_ option.
313+
with_seconds ``Boolean`` The value of the `with_seconds`_ option.
314+
with_weeks ``Boolean`` The value of the `with_weeks`_ option.
315+
with_years ``Boolean`` The value of the `with_years`_ option.
316+
============ =========== ========================================
317+
318+
.. _`ISO 8601`: https://en.wikipedia.org/wiki/ISO_8601

‎reference/forms/types/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Date and Time Fields
2828
~~~~~~~~~~~~~~~~~~~~
2929

3030
* :doc:`DateType </reference/forms/types/date>`
31+
* :doc:`DateIntervalType </reference/forms/types/dateinterval>`
3132
* :doc:`DateTimeType </reference/forms/types/datetime>`
3233
* :doc:`TimeType </reference/forms/types/time>`
3334
* :doc:`BirthdayType </reference/forms/types/birthday>`

0 commit comments

Comments
 (0)