From b784768eef75afb32f6d2ce7166551a528bce0ec Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Thu, 9 Feb 2023 16:48:46 +0100 Subject: [4.2.x] Refs #34140 -- Applied rst code-block to non-Python examples. Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for reviews. Backport of 534ac4829764f317cf2fbc4a18354fcc998c1425 from main. --- docs/ref/forms/api.txt | 208 +++++++++++++++++++++++++++++++++------------ docs/ref/forms/fields.txt | 68 ++++++++++----- docs/ref/forms/widgets.txt | 20 +++-- 3 files changed, 218 insertions(+), 78 deletions(-) (limited to 'docs/ref/forms') diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 6d296c537e..99a140ad0e 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -25,12 +25,16 @@ A :class:`Form` instance is either **bound** to a set of data, or **unbound**. .. class:: Form -To create an unbound :class:`Form` instance, instantiate the class:: +To create an unbound :class:`Form` instance, instantiate the class: + +.. code-block:: pycon >>> f = ContactForm() To bind data to a form, pass the data as a dictionary as the first parameter to -your :class:`Form` class constructor:: +your :class:`Form` class constructor: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -47,7 +51,9 @@ in a moment. .. attribute:: Form.is_bound If you need to distinguish between bound and unbound form instances at runtime, -check the value of the form's :attr:`~Form.is_bound` attribute:: +check the value of the form's :attr:`~Form.is_bound` attribute: + +.. code-block:: pycon >>> f = ContactForm() >>> f.is_bound @@ -56,7 +62,9 @@ check the value of the form's :attr:`~Form.is_bound` attribute:: >>> f.is_bound True -Note that passing an empty dictionary creates a *bound* form with empty data:: +Note that passing an empty dictionary creates a *bound* form with empty data: + +.. code-block:: pycon >>> f = ContactForm({}) >>> f.is_bound @@ -81,7 +89,9 @@ validation for fields that are interdependent. See 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:: +and return a boolean designating whether the data was valid: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -93,7 +103,9 @@ and return a boolean designating whether the data was valid:: Let's try with some invalid data. In this case, ``subject`` is blank (an error, because all fields are required by default) and ``sender`` is not a valid -email address:: +email address: + +.. code-block:: pycon >>> data = {'subject': '', ... 'message': 'Hi there', @@ -106,7 +118,9 @@ email address:: .. attribute:: Form.errors Access the :attr:`~Form.errors` attribute to get a dictionary of error -messages:: +messages: + +.. code-block:: pycon >>> f.errors {'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']} @@ -214,7 +228,9 @@ Behavior of unbound forms ------------------------- It's meaningless to validate a form with no data, but, for the record, here's -what happens with unbound forms:: +what happens with unbound forms: + +.. code-block:: pycon >>> f = ContactForm() >>> f.is_valid() @@ -236,7 +252,9 @@ username of the current session. To accomplish this, use the :attr:`~Form.initial` argument to a :class:`Form`. This argument, if given, should be a dictionary mapping field names to initial values. Only include the fields for which you're specifying an initial value; -it's not necessary to include every field in your form. For example:: +it's not necessary to include every field in your form. For example: + +.. code-block:: pycon >>> f = ContactForm(initial={'subject': 'Hi there!'}) @@ -247,7 +265,9 @@ If a :class:`~django.forms.Field` defines :attr:`~Field.initial` *and* you include :attr:`~Form.initial` when instantiating the ``Form``, then the latter ``initial`` will have precedence. In this example, ``initial`` is provided both at the field level and at the form instance level, and the latter gets -precedence:: +precedence: + +.. code-block:: pycon >>> from django import forms >>> class CommentForm(forms.Form): @@ -271,7 +291,9 @@ It is recommended to use :attr:`BoundField.initial` over simpler interface. Also, unlike :meth:`~Form.get_initial_for_field()`, :attr:`BoundField.initial` caches its values. This is useful especially when dealing with callables whose return values can change (e.g. ``datetime.now`` or -``uuid.uuid4``):: +``uuid.uuid4``): + +.. code-block:: pycon >>> import uuid >>> class UUIDCommentForm(CommentForm): @@ -332,7 +354,9 @@ Accessing the fields from the form .. attribute:: Form.fields You can access the fields of :class:`Form` instance from its ``fields`` -attribute:: +attribute: + +.. code-block:: pycon >>> for row in f.fields.values(): print(row) ... @@ -343,7 +367,9 @@ attribute:: You can alter the field and :class:`.BoundField` of :class:`Form` instance to -change the way it is presented in the form:: +change the way it is presented in the form: + +.. code-block:: pycon >>> f.as_div().split("")[0] '
' @@ -353,7 +379,9 @@ change the way it is presented in the form:: Beware not to alter the ``base_fields`` attribute because this modification will influence all subsequent ``ContactForm`` instances within the same Python -process:: +process: + +.. code-block:: pycon >>> f.base_fields["subject"].label_suffix = "?" >>> another_f = CommentForm(auto_id=False) @@ -377,7 +405,9 @@ formats, ``DateField`` will always normalize it to a ``datetime.date`` object as long as it's valid. Once you've created a :class:`~Form` instance with a set of data and validated -it, you can access the clean data via its ``cleaned_data`` attribute:: +it, you can access the clean data via its ``cleaned_data`` attribute: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -394,7 +424,9 @@ always cleans the input into a string. We'll cover the encoding implications later in this document. If your data does *not* validate, the ``cleaned_data`` dictionary contains -only the valid fields:: +only the valid fields: + +.. code-block:: pycon >>> data = {'subject': '', ... 'message': 'Hi there', @@ -409,7 +441,9 @@ only the valid fields:: ``cleaned_data`` will always *only* contain a key for fields defined in the ``Form``, even if you pass extra data when you define the ``Form``. In this example, we pass a bunch of extra fields to the ``ContactForm`` constructor, -but ``cleaned_data`` contains only the form's fields:: +but ``cleaned_data`` contains only the form's fields: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -427,7 +461,9 @@ but ``cleaned_data`` contains only the form's fields:: When the ``Form`` is valid, ``cleaned_data`` will include a key and value for *all* its fields, even if the data didn't include a value for some optional fields. In this example, the data dictionary doesn't include a value for the -``nick_name`` field, but ``cleaned_data`` includes it, with an empty value:: +``nick_name`` field, but ``cleaned_data`` includes it, with an empty value: + +.. code-block:: pycon >>> from django import forms >>> class OptionalPersonForm(forms.Form): @@ -458,7 +494,9 @@ Outputting forms as HTML ======================== The second task of a ``Form`` object is to render itself as HTML. To do so, -``print`` it:: +``print`` it: + +.. code-block:: pycon >>> f = ContactForm() >>> print(f) @@ -471,7 +509,9 @@ If the form is bound to data, the HTML output will include that data appropriately. For example, if a field is represented by an ````, the data will be in the ``value`` attribute. If a field is represented by an ````, then that HTML will -include ``checked`` if appropriate:: +include ``checked`` if appropriate: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -658,7 +698,9 @@ The template used by ``as_p()``. Default: ``'django/forms/p.html'``. .. method:: Form.as_p() ``as_p()`` renders the form as a series of ``

`` tags, with each ``

`` -containing one field:: +containing one field: + +.. code-block:: pycon >>> f = ContactForm() >>> f.as_p() @@ -680,7 +722,9 @@ The template used by ``as_ul()``. Default: ``'django/forms/ul.html'``. ``as_ul()`` renders the form as a series of ``

  • `` tags, with each ``
  • `` containing one field. It does *not* include the ``
      `` or ``
    ``, so that -you can specify any HTML attributes on the ``
      `` for flexibility:: +you can specify any HTML attributes on the ``
        `` for flexibility: + +.. code-block:: pycon >>> f = ContactForm() >>> f.as_ul() @@ -700,7 +744,9 @@ The template used by ``as_table()``. Default: ``'django/forms/table.html'``. .. method:: Form.as_table() -``as_table()`` renders the form as an HTML ````:: +``as_table()`` renders the form as an HTML ``
        ``: + +.. code-block:: pycon >>> f = ContactForm() >>> f.as_table() @@ -737,7 +783,9 @@ attributes:: # ... and the rest of your fields here Once you've done that, rows will be given ``"error"`` and/or ``"required"`` -classes, as needed. The HTML will look something like:: +classes, as needed. The HTML will look something like: + +.. code-block:: pycon >>> f = ContactForm(data) >>> print(f.as_table()) @@ -779,7 +827,9 @@ Use the ``auto_id`` argument to the ``Form`` constructor to control the ``id`` and label behavior. This argument must be ``True``, ``False`` or a string. If ``auto_id`` is ``False``, then the form output will not include ``