Skip to content

Commit af3ae3b

Browse files
MisatoTremorMisatoTremor
committed
Add dateinterval type reference
1 parent ca54d55 commit af3ae3b

File tree

3 files changed

+314
-0
lines changed

3 files changed

+314
-0
lines changed

‎reference/forms/types.rst

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

3030
types/date
31+
types/dateinterval
3132
types/datetime
3233
types/time
3334
types/birthday

‎reference/forms/types/dateinterval.rst

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

2929
* :doc:`date </reference/forms/types/date>`
30+
* :doc:`dateinterval </reference/forms/types/dateinterval>`
3031
* :doc:`datetime </reference/forms/types/datetime>`
3132
* :doc:`time </reference/forms/types/time>`
3233
* :doc:`birthday </reference/forms/types/birthday>`

0 commit comments

Comments
 (0)