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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy