From 8cd2e65a7372cc1d75d7c2dd9d690bb3cdc94352 Mon Sep 17 00:00:00 2001 From: dFayet Date: Sun, 3 Nov 2019 15:40:56 +0100 Subject: [PATCH] Add WeekType Documentation --- reference/forms/types.rst | 1 + reference/forms/types/map.rst.inc | 1 + reference/forms/types/options/weeks.rst.inc | 7 + reference/forms/types/week.rst | 188 ++++++++++++++++++++ 4 files changed, 197 insertions(+) create mode 100644 reference/forms/types/options/weeks.rst.inc create mode 100644 reference/forms/types/week.rst diff --git a/reference/forms/types.rst b/reference/forms/types.rst index 54cb8656707..49d769c8967 100644 --- a/reference/forms/types.rst +++ b/reference/forms/types.rst @@ -35,6 +35,7 @@ Form Types Reference types/datetime types/time types/birthday + types/week types/checkbox types/file diff --git a/reference/forms/types/map.rst.inc b/reference/forms/types/map.rst.inc index b6ef2728ff9..4036f2f7dce 100644 --- a/reference/forms/types/map.rst.inc +++ b/reference/forms/types/map.rst.inc @@ -34,6 +34,7 @@ Date and Time Fields * :doc:`DateTimeType ` * :doc:`TimeType ` * :doc:`BirthdayType ` +* :doc:`WeekType ` Other Fields ~~~~~~~~~~~~ diff --git a/reference/forms/types/options/weeks.rst.inc b/reference/forms/types/options/weeks.rst.inc new file mode 100644 index 00000000000..fb9e2d8d9b5 --- /dev/null +++ b/reference/forms/types/options/weeks.rst.inc @@ -0,0 +1,7 @@ +weeks +~~~~~ + +**type**: ``array`` **default**: 1 to 53 + +List of weeks available to the week field type. This option is only relevant +when the ``widget`` option is set to ``choice``. diff --git a/reference/forms/types/week.rst b/reference/forms/types/week.rst new file mode 100644 index 00000000000..ae245d7ad52 --- /dev/null +++ b/reference/forms/types/week.rst @@ -0,0 +1,188 @@ +.. index:: + single: Forms; Fields; WeekType + +WeekType Field +============== + +.. versionadded:: 4.4 + + The ``WeekType`` type was introduced in Symfony 4.4. + +This field type allows the user to modify data that represents a specific +`ISO 8601`_ week number (e.g. ``1984-W05``). + +Can be rendered as a text input or select tags. The underlying format of +the data can be a string or an array. + ++----------------------+-----------------------------------------------------------------------------+ +| Underlying Data Type | can be a string, or array (see the ``input`` option) | ++----------------------+-----------------------------------------------------------------------------+ +| Rendered as | single text box, two text boxes or two select fields | ++----------------------+-----------------------------------------------------------------------------+ +| Options | - `choice_translation_domain`_ | +| | - `placeholder`_ | +| | - `html5`_ | +| | - `input`_ | +| | - `widget`_ | +| | - `weeks`_ | +| | - `years`_ | ++----------------------+-----------------------------------------------------------------------------+ +| Overridden options | - `compound`_ | +| | - `empty_data`_ | +| | - `error_bubbling`_ | ++----------------------+-----------------------------------------------------------------------------+ +| Inherited | - `attr`_ | +| options | - `data`_ | +| | - `disabled`_ | +| | - `help`_ | +| | - `help_attr`_ | +| | - `help_html`_ | +| | - `inherit_data`_ | +| | - `invalid_message`_ | +| | - `invalid_message_parameters`_ | +| | - `mapped`_ | +| | - `row_attr`_ | ++----------------------+-----------------------------------------------------------------------------+ +| Parent type | :doc:`FormType ` | ++----------------------+-----------------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\WeekType` | ++----------------------+-----------------------------------------------------------------------------+ + +.. include:: /reference/forms/types/options/_debug_form.rst.inc + +Field Options +------------- + +.. include:: /reference/forms/types/options/choice_translation_domain.rst.inc + +placeholder +~~~~~~~~~~~ + +**type**: ``string`` | ``array`` + +If your widget option is set to ``choice``, then this field will be represented +as a series of ``select`` boxes. When the placeholder value is a string, +it will be used as the **blank value** of all select boxes:: + + use Symfony\Component\Form\Extension\Core\Type\WeekType; + + $builder->add('startWeek', WeekType::class, [ + 'placeholder' => 'Select a value', + ]); + +Alternatively, you can use an array that configures different placeholder +values for the year and week fields:: + + use Symfony\Component\Form\Extension\Core\Type\WeekType; + + $builder->add('startDateTime', WeekType::class, [ + 'placeholder' => [ + 'year' => 'Year', 'week' => 'Week', + ] + ]); + + +.. include:: /reference/forms/types/options/html5.rst.inc + +input +~~~~~ + +**type**: ``string`` **default**: ``array`` + +The format of the *input* data - i.e. the format that the date is stored +on your underlying object. Valid values are: + +* ``string`` (e.g. ``2011-W17``) +* ``array`` (e.g. ``[2011, 17]``) + +The value that comes back from the form will also be normalized back into +this format. + +widget +~~~~~~ + +**type**: ``string`` **default**: ``choice`` + +The basic way in which this field should be rendered. Can be one of the +following: + +* ``choice``: renders two select inputs. + +* ``text``: renders a two field input of type ``text`` (year, week). + +* ``single_text``: renders a single input of type ``week``. + +years +~~~~~ + +**type**: ``array`` **default**: ten years before to ten years after the +current year + +List of years available to the year field type. This option is only relevant +when the ``widget`` option is set to ``choice``. + + +.. include:: /reference/forms/types/options/weeks.rst.inc + +Overridden Options +------------------ + +.. include:: /reference/forms/types/options/compound_type.rst.inc + +.. include:: /reference/forms/types/options/empty_data.rst.inc + :end-before: DEFAULT_PLACEHOLDER + +The actual default value of this option depends on other field options: + +* If ``widget`` is ``single_text``, then ``''`` + (empty string); +* Otherwise ``[]`` (empty array). + +.. include:: /reference/forms/types/options/empty_data.rst.inc + :start-after: DEFAULT_PLACEHOLDER + +error_bubbling +~~~~~~~~~~~~~~ + +**default**: ``false`` + +Inherited Options +----------------- + +These options inherit from the :doc:`FormType `: + +.. include:: /reference/forms/types/options/attr.rst.inc + +.. include:: /reference/forms/types/options/data.rst.inc + +.. include:: /reference/forms/types/options/disabled.rst.inc + +.. include:: /reference/forms/types/options/help.rst.inc + +.. include:: /reference/forms/types/options/help_attr.rst.inc + +.. include:: /reference/forms/types/options/help_html.rst.inc + +.. include:: /reference/forms/types/options/inherit_data.rst.inc + +.. include:: /reference/forms/types/options/invalid_message.rst.inc + +.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc + +.. include:: /reference/forms/types/options/mapped.rst.inc + +.. include:: /reference/forms/types/options/row_attr.rst.inc + +Field Variables +--------------- + ++----------+------------+----------------------------------------------------------------------+ +| Variable | Type | Usage | ++==========+============+======================================================================+ +| widget | ``mixed`` | The value of the `widget`_ option. | ++----------+------------+----------------------------------------------------------------------+ +| type | ``string`` | Only present when widget is ``single_text`` and HTML5 is activated, | +| | | contains the input type to use (``datetime``, ``date`` or ``time``). | ++----------+------------+----------------------------------------------------------------------+ + +.. _`ISO 8601`: https://en.wikipedia.org/wiki/ISO_8601