From 232b60a21b951bd16b8c95b34fcbcbf3ecd89fca Mon Sep 17 00:00:00 2001 From: David Smith Date: Sun, 12 Feb 2023 13:20:05 +0000 Subject: Refs #32339 -- Updated docs to reflect default
style form rendering in Django 5.0. Follow up to 98756c685ee173bbd43f21ed0553f808be835ce5. --- docs/ref/forms/api.txt | 79 ++++++++++++++++++---------------------------- docs/ref/forms/fields.txt | 48 +++++++++++----------------- docs/ref/forms/widgets.txt | 16 +++++----- 3 files changed, 57 insertions(+), 86 deletions(-) (limited to 'docs/ref/forms') diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 8a18e1b5da..3a9ea81723 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -276,9 +276,9 @@ precedence: ... comment = forms.CharField() >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False) >>> print(f) - Name: - Url: - Comment: +
Name:
+
Url:
+
Comment:
.. method:: Form.get_initial_for_field(field, field_name) @@ -500,10 +500,10 @@ The second task of a ``Form`` object is to render itself as HTML. To do so, >>> f = ContactForm() >>> print(f) - - - - +
+
+
+
If the form is bound to data, the HTML output will include that data appropriately. For example, if a field is represented by an @@ -519,16 +519,14 @@ include ``checked`` if appropriate: ... 'cc_myself': True} >>> f = ContactForm(data) >>> print(f) - - - - +
+
+
+
-This default output is a two-column HTML table, with a ```` for each field. -Notice the following: +This default output wraps each field with a ``
``. Notice the following: -* For flexibility, the output does *not* include the ```` and - ``
`` tags, nor does it include the ``
`` and ``
`` +* For flexibility, the output does *not* include the ``
`` and ``
`` tags or an ```` tag. It's your job to do that. * Each field type has a default HTML representation. ``CharField`` is @@ -556,7 +554,7 @@ Notice the following: it uses boolean attributes such as ``checked`` rather than the XHTML style of ``checked='checked'``. -Although ```` output is the default output style when you ``print`` a +Although ``
`` output is the default output style when you ``print`` a form, other output styles are available. Each style is available as a method on a form object, and each rendering method returns a string. @@ -584,7 +582,7 @@ class. .. method:: Form.render(template_name=None, context=None, renderer=None) -The render method is called by ``__str__`` as well as the +The render method is called by ``__str__`` as well as the :meth:`.Form.as_div`, :meth:`.Form.as_table`, :meth:`.Form.as_p`, and :meth:`.Form.as_ul` methods. All arguments are optional and default to: @@ -779,11 +777,11 @@ classes, as needed. The HTML will look something like: .. code-block:: pycon >>> f = ContactForm(data) - >>> print(f.as_table()) -
- - - - >>> print(f.as_ul()) -
    • This field is required.
    Subject:
    • -
  • Message:
    • -
    • Enter a valid email address.
    Sender:
    • -
  • Cc myself:
    • - >>> print(f.as_p()) -

    • This field is required.

    -

    Subject:

    -

    Message:

    -

    • Enter a valid email address.

    -

    Sender:

    -

    Cc myself:

    .. _ref-forms-error-list-format: @@ -1515,7 +1496,7 @@ fields are ordered first: >>> class ContactFormWithPriority(ContactForm): ... priority = forms.CharField() >>> f = ContactFormWithPriority(auto_id=False) - >>> print(f.as_div()) + >>> print(f)
    Subject:
    Message:
    Sender:
    @@ -1538,7 +1519,7 @@ classes: >>> class BeatleForm(InstrumentForm, PersonForm): ... haircut_type = forms.CharField() >>> b = BeatleForm(auto_id=False) - >>> print(b.as_div()) + >>> print(b)
    First name:
    Last name:
    Instrument:
    @@ -1575,10 +1556,10 @@ You can put several Django forms inside one ```` tag. To give each >>> mother = PersonForm(prefix="mother") >>> father = PersonForm(prefix="father") - >>> print(mother.as_div()) + >>> print(mother)
    - >>> print(father.as_div()) + >>> print(father)
    diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index edf32ecdab..a7095ba5dc 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -129,9 +129,9 @@ We've specified ``auto_id=False`` to simplify the output: ... comment = forms.CharField() >>> f = CommentForm(auto_id=False) >>> print(f) - - - +
    Your name:
    +
    Your website:
    +
    Comment:
    ``label_suffix`` ---------------- @@ -148,10 +148,10 @@ The ``label_suffix`` argument lets you override the form's ... nationality = forms.CharField() ... captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =') >>> f = ContactForm(label_suffix='?') - >>> print(f.as_p()) -

    -

    -

    + >>> print(f) +
    +
    +
    ``initial`` ----------- @@ -175,9 +175,9 @@ field is initialized to a particular value. For example: ... comment = forms.CharField() >>> f = CommentForm(auto_id=False) >>> print(f) - - - +
    Name:
    +
    Url:
    +
    Comment:
    You may be thinking, why not just pass a dictionary of the initial values as data when displaying the form? Well, if you do that, you'll trigger validation, @@ -192,9 +192,9 @@ and the HTML output will include any validation errors: >>> default_data = {'name': 'Your name', 'url': 'http://'} >>> f = CommentForm(default_data, auto_id=False) >>> print(f) - - - +
    Name:
    +
    Url:
    • Enter a valid URL.
    +
    Comment:
    • This field is required.
    This is why ``initial`` values are only displayed for unbound forms. For bound forms, the HTML output will use the bound data. @@ -225,7 +225,7 @@ Instead of a constant, you can also pass any callable: >>> class DateForm(forms.Form): ... day = forms.DateField(initial=datetime.date.today) >>> print(DateForm()) - +
    The callable will be evaluated only when the unbound form is displayed, not when it is defined. @@ -262,21 +262,11 @@ fields. We've specified ``auto_id=False`` to simplify the output: ... sender = forms.EmailField(help_text='A valid email address, please.') ... cc_myself = forms.BooleanField(required=False) >>> f = HelpTextContactForm(auto_id=False) - >>> print(f.as_table()) - - - - - >>> print(f.as_ul())) -
  • Subject: 100 characters max.
    • -
  • Message:
    • -
  • Sender: A valid email address, please.
    • -
  • Cc myself:
    • - >>> print(f.as_p()) -

    Subject: 100 characters max.

    -

    Message:

    -

    Sender: A valid email address, please.

    -

    Cc myself:

    + >>> print(f) +
    Subject:
    100 characters max.
    +
    Message:
    +
    Sender:
    A valid email address, please.
    +
    Cc myself:
    ``error_messages`` ------------------ diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 45b154f753..43a579b4a5 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -144,10 +144,10 @@ provided for each widget will be rendered exactly the same: .. code-block:: pycon >>> f = CommentForm(auto_id=False) - >>> f.as_table() - - - + >>> print(f) +
    Name:
    +
    Url:
    +
    Comment:
    On a real web page, you probably don't want every widget to look the same. You might want a larger input element for the comment, and you might want the @@ -182,10 +182,10 @@ you can use the :attr:`Form.fields` attribute:: Django will then include the extra attributes in the rendered output: >>> f = CommentForm(auto_id=False) - >>> f.as_table() - - - + >>> print(f) +
    Name:
    +
    Url:
    +
    Comment:
    You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See :attr:`BoundField.id_for_label` for an example. -- cgit v1.3
    ... -
    ... -
    ... -
    Subject:
    • This field is required.
    Message:
    Sender:
    • Enter a valid email address.
    Cc myself:
    Your name:
    Your website:
    Comment:
    Name:
    Url:
    Comment:
    Name:
    Url:
    • Enter a valid URL.
    Comment:
    • This field is required.
    Day:
    Subject:
    100 characters max.
    Message:
    Sender:
    A valid email address, please.
    Cc myself:
    Name:
    Url:
    Comment:
    Name:
    Url:
    Comment: