Skip to content

Commit f9128ee

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

File tree

3 files changed

+292
-0
lines changed

3 files changed

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