Skip to content

Commit 1883265

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

File tree

3 files changed

+295
-0
lines changed

3 files changed

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

‎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)