Skip to content

Commit 6ed9ed7

Browse files
MisatoTremorMisatoTremor
committed
Add dateinterval type reference
1 parent f91f0b1 commit 6ed9ed7

File tree

3 files changed

+327
-0
lines changed

3 files changed

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