diff options
Diffstat (limited to 'docs/ref/forms')
| -rw-r--r-- | docs/ref/forms/api.txt | 39 | ||||
| -rw-r--r-- | docs/ref/forms/fields.txt | 109 | ||||
| -rw-r--r-- | docs/ref/forms/models.txt | 13 | ||||
| -rw-r--r-- | docs/ref/forms/validation.txt | 4 | ||||
| -rw-r--r-- | docs/ref/forms/widgets.txt | 56 |
5 files changed, 117 insertions, 104 deletions
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index ed2bb4d604..bfc32c0d5c 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -45,10 +45,10 @@ your :class:`Form` class constructor: >>> f = ContactForm(data) In this dictionary, the keys are the field names, which correspond to the -attributes in your :class:`Form` class. The values are the data you're trying to -validate. These will usually be strings, but there's no requirement that they be -strings; the type of data you pass depends on the :class:`Field`, as we'll see -in a moment. +attributes in your :class:`Form` class. The values are the data you're trying +to validate. These will usually be strings, but there's no requirement that +they be strings; the type of data you pass depends on the :class:`Field`, as +we'll see in a moment. .. attribute:: Form.is_bound @@ -90,8 +90,8 @@ validation for fields that are interdependent. See .. method:: Form.is_valid() The primary task of a :class:`Form` object is to validate data. With a bound -:class:`Form` instance, call the :meth:`~Form.is_valid` method to run validation -and return a boolean designating whether the data was valid: +:class:`Form` instance, call the :meth:`~Form.is_valid` method to run +validation and return a boolean designating whether the data was valid: .. code-block:: pycon @@ -506,12 +506,12 @@ fields. In this example, the data dictionary doesn't include a value for the >>> f.cleaned_data {'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'} -In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an -empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat -empty values as an empty string. Each field type knows what its "blank" value -is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For -full details on each field's behavior in this case, see the "Empty value" note -for each field in the :ref:`built-in-fields` section below. +In this above example, the ``cleaned_data`` value for ``nick_name`` is set to +an empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s +treat empty values as an empty string. Each field type knows what its "blank" +value is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. +For full details on each field's behavior in this case, see the "Empty value" +note for each field in the :ref:`built-in-fields` section below. You can write code to perform validation for particular form fields (based on their name) or for the form as a whole (considering combinations of various @@ -1255,8 +1255,8 @@ Attributes of ``BoundField`` .. attribute:: BoundField.form - The :class:`~django.forms.Form` instance this :class:`~django.forms.BoundField` - is bound to. + The :class:`~django.forms.Form` instance this + :class:`~django.forms.BoundField` is bound to. .. attribute:: BoundField.help_text @@ -1264,8 +1264,8 @@ Attributes of ``BoundField`` .. attribute:: BoundField.html_name - The name that will be used in the widget's HTML ``name`` attribute. It takes - the form :attr:`~django.forms.Form.prefix` into account. + The name that will be used in the widget's HTML ``name`` attribute. It + takes the form :attr:`~django.forms.Form.prefix` into account. .. attribute:: BoundField.id_for_label @@ -1380,7 +1380,8 @@ Methods of ``BoundField`` .. method:: BoundField.as_hidden(attrs=None, **kwargs) - Returns a string of HTML for representing this as an ``<input type="hidden">``. + Returns a string of HTML for representing this as an + ``<input type="hidden">``. ``**kwargs`` are passed to :meth:`~django.forms.BoundField.as_widget`. @@ -1484,8 +1485,8 @@ Methods of ``BoundField`` .. method:: BoundField.value() - Use this method to render the raw value of this field as it would be rendered - by a ``Widget``: + Use this method to render the raw value of this field as it would be + rendered by a ``Widget``: .. code-block:: pycon diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index f0a8e6c341..c786239c25 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -239,7 +239,8 @@ Instead of a constant, you can also pass any callable: >>> print(DateForm()) <div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div> -The callable will be evaluated only when the unbound form is displayed, not when it is defined. +The callable will be evaluated only when the unbound form is displayed, not +when it is defined. ``widget`` ---------- @@ -326,8 +327,8 @@ inside ``aria-describedby``: .. attribute:: Field.error_messages The ``error_messages`` argument lets you override the default messages that the -field will raise. Pass in a dictionary with keys matching the error messages you -want to override. For example, here is the default error message: +field will raise. Pass in a dictionary with keys matching the error messages +you want to override. For example, here is the default error message: .. code-block:: pycon @@ -411,8 +412,8 @@ Checking if the field data has changed .. method:: Field.has_changed() -The ``has_changed()`` method is used to determine if the field value has changed -from the initial value. Returns ``True`` or ``False``. +The ``has_changed()`` method is used to determine if the field value has +changed from the initial value. Returns ``True`` or ``False``. See the :class:`Form.has_changed` documentation for more information. @@ -443,10 +444,10 @@ For each field, we describe the default widget used if you don't specify .. note:: Since all ``Field`` subclasses have ``required=True`` by default, the - validation condition here is important. If you want to include a boolean - in your form that can be either ``True`` or ``False`` (e.g. a checked or - unchecked checkbox), you must remember to pass in ``required=False`` when - creating the ``BooleanField``. + validation condition here is important. If you want to include a + boolean in your form that can be either ``True`` or ``False`` (e.g. a + checked or unchecked checkbox), you must remember to pass in + ``required=False`` when creating the ``BooleanField``. ``CharField`` ------------- @@ -489,8 +490,8 @@ For each field, we describe the default widget used if you don't specify * Validates that the given value exists in the list of choices. * Error message keys: ``required``, ``invalid_choice`` - The ``invalid_choice`` error message may contain ``%(value)s``, which will be - replaced with the selected choice. + The ``invalid_choice`` error message may contain ``%(value)s``, which will + be replaced with the selected choice. Takes one extra argument: @@ -678,8 +679,9 @@ For each field, we describe the default widget used if you don't specify :ref:`bind the file data to the form <binding-uploaded-files>`. The ``max_length`` error refers to the length of the filename. In the error - message for that key, ``%(max)d`` will be replaced with the maximum filename - length and ``%(length)d`` will be replaced with the current filename length. + message for that key, ``%(max)d`` will be replaced with the maximum + filename length and ``%(length)d`` will be replaced with the current + filename length. ``FilePathField`` ----------------- @@ -692,8 +694,8 @@ For each field, we describe the default widget used if you don't specify * Validates that the selected choice exists in the list of choices. * Error message keys: ``required``, ``invalid_choice`` - The field allows choosing from files inside a certain directory. It takes five - extra arguments; only ``path`` is required: + The field allows choosing from files inside a certain directory. It takes + five extra arguments; only ``path`` is required: .. attribute:: path @@ -708,8 +710,8 @@ For each field, we describe the default widget used if you don't specify .. attribute:: match - A regular expression pattern; only files with names matching this expression - will be allowed as choices. + A regular expression pattern; only files with names matching this + expression will be allowed as choices. .. attribute:: allow_files @@ -723,7 +725,6 @@ For each field, we describe the default widget used if you don't specify whether folders in the specified location should be included. Either this or :attr:`allow_files` must be ``True``. - ``FloatField`` -------------- @@ -765,15 +766,16 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) - * Normalizes to: A string. IPv6 addresses are normalized as described below. + * Normalizes to: A string. IPv6 addresses are normalized as described + below. * Validates that the given value is a valid IP address. * Error message keys: ``required``, ``invalid``, ``max_length`` The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2, - including using the IPv4 format suggested in paragraph 3 of that section, like - ``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to - ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters - are converted to lowercase. + including using the IPv4 format suggested in paragraph 3 of that section, + like ``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be + normalized to ``2001::1``, and ``::ffff:0a0a:0a0a`` to + ``::ffff:10.10.10.10``. All characters are converted to lowercase. Takes three optional arguments: @@ -962,10 +964,11 @@ For each field, we describe the default widget used if you don't specify of choices. * Error message keys: ``required``, ``invalid_choice``, ``invalid_list`` - The ``invalid_choice`` error message may contain ``%(value)s``, which will be - replaced with the selected choice. + The ``invalid_choice`` error message may contain ``%(value)s``, which will + be replaced with the selected choice. - Takes one extra required argument, ``choices``, as for :class:`ChoiceField`. + Takes one extra required argument, ``choices``, as for + :class:`ChoiceField`. ``NullBooleanField`` -------------------- @@ -1074,8 +1077,8 @@ For each field, we describe the default widget used if you don't specify .. class:: TypedChoiceField(**kwargs) - Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes two - extra arguments, :attr:`coerce` and :attr:`empty_value`. + Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes + two extra arguments, :attr:`coerce` and :attr:`empty_value`. * Default widget: :class:`Select` * Empty value: Whatever you've given as :attr:`empty_value`. @@ -1089,26 +1092,27 @@ For each field, we describe the default widget used if you don't specify .. attribute:: coerce - A function that takes one argument and returns a coerced value. Examples - include the built-in ``int``, ``float``, ``bool`` and other types. Defaults - to an identity function. Note that coercion happens after input - validation, so it is possible to coerce to a value not present in - ``choices``. + A function that takes one argument and returns a coerced value. + Examples include the built-in ``int``, ``float``, ``bool`` and other + types. Defaults to an identity function. Note that coercion happens + after input validation, so it is possible to coerce to a value not + present in ``choices``. .. attribute:: empty_value The value to use to represent "empty." Defaults to the empty string; - ``None`` is another common choice here. Note that this value will not be - coerced by the function given in the ``coerce`` argument, so choose it - accordingly. + ``None`` is another common choice here. Note that this value will not + be coerced by the function given in the ``coerce`` argument, so choose + it accordingly. ``TypedMultipleChoiceField`` ---------------------------- .. class:: TypedMultipleChoiceField(**kwargs) - Just like a :class:`MultipleChoiceField`, except :class:`TypedMultipleChoiceField` - takes two extra arguments, ``coerce`` and ``empty_value``. + Just like a :class:`MultipleChoiceField`, except + :class:`TypedMultipleChoiceField` takes two extra arguments, ``coerce`` and + ``empty_value``. * Default widget: :class:`SelectMultiple` * Empty value: Whatever you've given as ``empty_value`` @@ -1118,8 +1122,8 @@ For each field, we describe the default widget used if you don't specify coerced. * Error message keys: ``required``, ``invalid_choice`` - The ``invalid_choice`` error message may contain ``%(value)s``, which will be - replaced with the selected choice. + The ``invalid_choice`` error message may contain ``%(value)s``, which will + be replaced with the selected choice. Takes two extra arguments, ``coerce`` and ``empty_value``, as for :class:`TypedChoiceField`. @@ -1178,8 +1182,8 @@ Slightly complex built-in ``Field`` classes .. attribute:: fields - The list of fields that should be used to validate the field's value (in - the order in which they are provided). + The list of fields that should be used to validate the field's value + (in the order in which they are provided). .. code-block:: pycon @@ -1199,7 +1203,8 @@ Slightly complex built-in ``Field`` classes * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) - * Normalizes to: the type returned by the ``compress`` method of the subclass. + * Normalizes to: the type returned by the ``compress`` method of the + subclass. * Validates the given value against each of the fields specified as an argument to the ``MultiValueField``. * Error message keys: ``required``, ``invalid``, ``incomplete`` @@ -1307,16 +1312,16 @@ Slightly complex built-in ``Field`` classes A list of formats used to attempt to convert a string to a valid ``datetime.date`` object. - If no ``input_date_formats`` argument is provided, the default input formats - for :class:`DateField` are used. + If no ``input_date_formats`` argument is provided, the default input + formats for :class:`DateField` are used. .. attribute:: input_time_formats A list of formats used to attempt to convert a string to a valid ``datetime.time`` object. - If no ``input_time_formats`` argument is provided, the default input formats - for :class:`TimeField` are used. + If no ``input_time_formats`` argument is provided, the default input + formats for :class:`TimeField` are used. .. _fields-which-handle-relationships: @@ -1378,11 +1383,11 @@ generating choices. See :ref:`iterating-relationship-choices` for details. .. attribute:: empty_label - By default the ``<select>`` widget used by ``ModelChoiceField`` will have an - empty choice at the top of the list. You can change the text of this - label (which is ``"---------"`` by default) with the ``empty_label`` - attribute, or you can disable the empty label entirely by setting - ``empty_label`` to ``None``:: + By default the ``<select>`` widget used by ``ModelChoiceField`` will + have an empty choice at the top of the list. You can change the text of + this label (which is ``"---------"`` by default) with the + ``empty_label`` attribute, or you can disable the empty label entirely + by setting ``empty_label`` to ``None``:: # A custom empty label field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)") diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt index 459eb48ff2..8abe53833d 100644 --- a/docs/ref/forms/models.txt +++ b/docs/ref/forms/models.txt @@ -29,7 +29,8 @@ Model Form API reference. For introductory material about model forms, see the ``widgets`` is a dictionary of model field names mapped to a widget. - ``localized_fields`` is a list of names of fields which should be localized. + ``localized_fields`` is a list of names of fields which should be + localized. ``labels`` is a dictionary of model field names mapped to a label. @@ -43,11 +44,11 @@ Model Form API reference. For introductory material about model forms, see the See :ref:`modelforms-factory` for example usage. - You must provide the list of fields explicitly, either via keyword arguments - ``fields`` or ``exclude``, or the corresponding attributes on the form's - inner ``Meta`` class. See :ref:`modelforms-selecting-fields` for more - information. Omitting any definition of the fields to use will result in - an :exc:`~django.core.exceptions.ImproperlyConfigured` exception. + You must provide the list of fields explicitly, either via keyword + arguments ``fields`` or ``exclude``, or the corresponding attributes on the + form's inner ``Meta`` class. See :ref:`modelforms-selecting-fields` for + more information. Omitting any definition of the fields to use will result + in an :exc:`~django.core.exceptions.ImproperlyConfigured` exception. ``modelformset_factory`` ======================== diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 52206dea2a..5715d15fa7 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -13,8 +13,8 @@ validation (accessing the ``errors`` attribute or calling ``full_clean()`` directly), but normally they won't be needed. In general, any cleaning method can raise ``ValidationError`` if there is a -problem with the data it is processing, passing the relevant information to -the ``ValidationError`` constructor. :ref:`See below <raising-validation-error>` +problem with the data it is processing, passing the relevant information to the +``ValidationError`` constructor. :ref:`See below <raising-validation-error>` for the best practice in raising ``ValidationError``. If no ``ValidationError`` is raised, the method should return the cleaned (normalized) data as a Python object. diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 2c277f4587..8c19bf1206 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -12,16 +12,17 @@ handles the rendering of the HTML, and the extraction of data from a GET/POST dictionary that corresponds to the widget. The HTML generated by the built-in widgets uses HTML5 syntax, targeting -``<!DOCTYPE html>``. For example, it uses boolean attributes such as ``checked`` -rather than the XHTML style of ``checked='checked'``. +``<!DOCTYPE html>``. For example, it uses boolean attributes such as +``checked`` rather than the XHTML style of ``checked='checked'``. .. tip:: - Widgets should not be confused with the :doc:`form fields </ref/forms/fields>`. - Form fields deal with the logic of input validation and are used directly - in templates. Widgets deal with rendering of HTML form input elements on - the web page and extraction of raw submitted data. However, widgets do - need to be :ref:`assigned <widget-to-field>` to form fields. + Widgets should not be confused with the :doc:`form fields + </ref/forms/fields>`. Form fields deal with the logic of input validation + and are used directly in templates. Widgets deal with rendering of HTML + form input elements on the web page and extraction of raw submitted data. + However, widgets do need to be :ref:`assigned <widget-to-field>` to form + fields. .. _widget-to-field: @@ -120,7 +121,8 @@ means, for example, that all :class:`TextInput` widgets will appear the same on your web pages. There are two ways to customize widgets: :ref:`per widget instance -<styling-widget-instances>` and :ref:`per widget class <styling-widget-classes>`. +<styling-widget-instances>` and +:ref:`per widget class <styling-widget-classes>`. .. _styling-widget-instances: @@ -175,8 +177,8 @@ You can also modify a widget in the form definition:: name.widget.attrs.update({"class": "special"}) comment.widget.attrs.update(size="40") -Or if the field isn't declared directly on the form (such as model form fields), -you can use the :attr:`Form.fields` attribute:: +Or if the field isn't declared directly on the form (such as model form +fields), you can use the :attr:`Form.fields` attribute:: class CommentForm(forms.ModelForm): def __init__(self, *args, **kwargs): @@ -279,7 +281,8 @@ foundation for custom widgets. this widget is required. * ``'value'``: The value as returned by :meth:`format_value`. * ``'attrs'``: HTML attributes to be set on the rendered widget. The - combination of the :attr:`attrs` attribute and the ``attrs`` argument. + combination of the :attr:`attrs` attribute and the ``attrs`` + argument. * ``'template_name'``: The value of ``self.template_name``. ``Widget`` subclasses can provide custom context values by overriding @@ -331,8 +334,8 @@ foundation for custom widgets. An attribute to identify if the widget should be grouped in a ``<fieldset>`` with a ``<legend>`` when rendered. Defaults to ``False`` - but is ``True`` when the widget contains multiple ``<input>`` tags such as - :class:`~django.forms.CheckboxSelectMultiple`, + but is ``True`` when the widget contains multiple ``<input>`` tags such + as :class:`~django.forms.CheckboxSelectMultiple`, :class:`~django.forms.RadioSelect`, :class:`~django.forms.MultiWidget`, :class:`~django.forms.SplitDateTimeWidget`, and @@ -507,8 +510,8 @@ Built-in widgets Django provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets in the ``django.forms.widgets`` module, -including :ref:`the input of text <text-widgets>`, :ref:`various checkboxes -and selectors <selector-widgets>`, :ref:`uploading files <file-upload-widgets>`, +including :ref:`the input of text <text-widgets>`, :ref:`various checkboxes and +selectors <selector-widgets>`, :ref:`uploading files <file-upload-widgets>`, and :ref:`handling of multi-valued input <composite-widgets>`. .. _text-widgets: @@ -637,7 +640,8 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. * ``template_name``: ``'django/forms/widgets/date.html'`` * Renders as: ``<input type="text" ...>`` - Takes same arguments as :class:`TextInput`, with one more optional argument: + Takes same arguments as :class:`TextInput`, with one more optional + argument: .. attribute:: DateInput.format @@ -657,7 +661,8 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. * ``template_name``: ``'django/forms/widgets/datetime.html'`` * Renders as: ``<input type="text" ...>`` - Takes same arguments as :class:`TextInput`, with one more optional argument: + Takes same arguments as :class:`TextInput`, with one more optional + argument: .. attribute:: DateTimeInput.format @@ -681,7 +686,8 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. * ``template_name``: ``'django/forms/widgets/time.html'`` * Renders as: ``<input type="text" ...>`` - Takes same arguments as :class:`TextInput`, with one more optional argument: + Takes same arguments as :class:`TextInput`, with one more optional + argument: .. attribute:: TimeInput.format @@ -866,9 +872,9 @@ that specifies the template used to render each choice. For example, for the The outer ``<div>`` container receives the ``id`` attribute of the widget, if defined, or :attr:`BoundField.auto_id` otherwise. - When looping over the radio buttons, the ``label`` and ``input`` tags include - ``for`` and ``id`` attributes, respectively. Each radio button has an - ``id_for_label`` attribute to output the element's ID. + When looping over the radio buttons, the ``label`` and ``input`` tags + include ``for`` and ``id`` attributes, respectively. Each radio button has + an ``id_for_label`` attribute to output the element's ID. ``CheckboxSelectMultiple`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1023,10 +1029,10 @@ Composite widgets list (which is ``---`` by default). You can change the text of this label with the ``empty_label`` attribute. ``empty_label`` can be a ``string``, ``list``, or ``tuple``. When a string is used, all select - boxes will each have an empty choice with this label. If ``empty_label`` - is a ``list`` or ``tuple`` of 3 string elements, the select boxes will - have their own custom label. The labels should be in this order - ``('year_label', 'month_label', 'day_label')``. + boxes will each have an empty choice with this label. If + ``empty_label`` is a ``list`` or ``tuple`` of 3 string elements, the + select boxes will have their own custom label. The labels should be in + this order ``('year_label', 'month_label', 'day_label')``. .. code-block:: python |