From ec5659382a5f5fc2daf0c87ccc89d0fb07534874 Mon Sep 17 00:00:00 2001
From: David Smith <smithdc@gmail.com>
Date: Thu, 5 May 2022 09:21:47 +0200
Subject: Fixed #32339 -- Added div.html form template.

---
 docs/ref/forms/api.txt         | 49 ++++++++++++++++++++++++++++++++++++++++++
 docs/releases/4.1.txt          |  9 ++++++++
 docs/topics/forms/formsets.txt | 16 +++++++++++---
 docs/topics/forms/index.txt    |  8 ++++---
 4 files changed, 76 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 8530af2611..72937bfa9a 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -607,6 +607,55 @@ list using ``{{ form.as_ul }}``.
 Each helper pairs a form method with an attribute giving the appropriate
 template name.
 
+``as_div()``
+~~~~~~~~~~~~
+
+.. attribute:: Form.template_name_div
+
+.. versionadded:: 4.1
+
+The template used by ``as_div()``. Default: ``'django/forms/div.html'``.
+
+.. method:: Form.as_div()
+
+.. versionadded:: 4.1
+
+``as_div()`` renders the form as a series of ``<div>`` elements, with each
+``<div>`` containing one field, such as:
+
+.. code-block:: pycon
+
+    >>> f = ContactForm()
+    >>> f.as_div()
+
+… gives HTML like:
+
+.. code-block:: html
+
+    <div>
+    <label for="id_subject">Subject:</label>
+    <input type="text" name="subject" maxlength="100" required id="id_subject">
+    </div>
+    <div>
+    <label for="id_message">Message:</label>
+    <input type="text" name="message" required id="id_message">
+    </div>
+    <div>
+    <label for="id_sender">Sender:</label>
+    <input type="email" name="sender" required id="id_sender">
+    </div>
+    <div>
+    <label for="id_cc_myself">Cc myself:</label>
+    <input type="checkbox" name="cc_myself" id="id_cc_myself">
+    </div>
+
+.. note::
+
+    Of the framework provided templates and output styles, ``as_div()`` is
+    recommended over the ``as_p()``, ``as_table()``, and ``as_ul()`` versions
+    as the template implements ``<fieldset>`` and ``<legend>`` to group related
+    inputs and is easier for screen reader users to navigate.
+
 ``as_p()``
 ~~~~~~~~~~
 
diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt
index 2864d179b2..1bd3fe68b0 100644
--- a/docs/releases/4.1.txt
+++ b/docs/releases/4.1.txt
@@ -258,6 +258,15 @@ Forms
   :attr:`~django.forms.renderers.BaseRenderer.formset_template_name` renderer
   attribute.
 
+* The new ``div.html`` form template, referencing
+  :attr:`.Form.template_name_div` attribute, and matching :meth:`.Form.as_div`
+  method, render forms using HTML ``<div>`` elements.
+
+  This new output style is recommended over the existing
+  :meth:`~.Form.as_table`, :meth:`~.Form.as_p` and :meth:`~.Form.as_ul` styles,
+  as the template implements ``<fieldset>`` and ``<legend>`` to group related
+  inputs and is easier for screen reader users to navigate.
+
 * The new :meth:`~django.forms.BoundField.legend_tag` allows rendering field
   labels in ``<legend>`` tags via the new ``tag`` argument of
   :meth:`~django.forms.BoundField.label_tag`.
diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt
index 0206959f1d..1b54f2accb 100644
--- a/docs/topics/forms/formsets.txt
+++ b/docs/topics/forms/formsets.txt
@@ -800,12 +800,22 @@ Formsets have the following attributes and methods associated with rendering:
         In older versions ``template_name`` defaulted to the string value
         ``'django/forms/formset/default.html'``.
 
+
+.. attribute:: BaseFormSet.template_name_div
+
+    .. versionadded:: 4.1
+
+    The name of the template used when calling :meth:`.as_div`. By default this
+    is ``"django/forms/formsets/div.html"``. This template renders the
+    formset's management form and then each form in the formset as per the
+    form's :meth:`~django.forms.Form.as_div` method.
+
 .. attribute:: BaseFormSet.template_name_p
 
     .. versionadded:: 4.0
 
     The name of the template used when calling :meth:`.as_p`. By default this
-    is ``'django/forms/formsets/p.html'``. This template renders the formset's
+    is ``"django/forms/formsets/p.html"``. This template renders the formset's
     management form and then each form in the formset as per the form's
     :meth:`~django.forms.Form.as_p` method.
 
@@ -814,7 +824,7 @@ Formsets have the following attributes and methods associated with rendering:
     .. versionadded:: 4.0
 
     The name of the template used when calling :meth:`.as_table`. By default
-    this is ``'django/forms/formsets/table.html'``. This template renders the
+    this is ``"django/forms/formsets/table.html"``. This template renders the
     formset's management form and then each form in the formset as per the
     form's :meth:`~django.forms.Form.as_table` method.
 
@@ -823,7 +833,7 @@ Formsets have the following attributes and methods associated with rendering:
     .. versionadded:: 4.0
 
     The name of the template used when calling :meth:`.as_ul`. By default this
-    is ``'django/forms/formsets/ul.html'``. This template renders the formset's
+    is ``"django/forms/formsets/ul.html"``. This template renders the formset's
     management form and then each form in the formset as per the form's
     :meth:`~django.forms.Form.as_ul` method.
 
diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index c8e43389a0..e153d73bab 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -566,12 +566,14 @@ Form rendering options
 
 There are other output options though for the ``<label>``/``<input>`` pairs:
 
+* ``{{ form.as_div }}`` will render them wrapped in ``<div>`` tags.
+
 * ``{{ form.as_table }}`` will render them as table cells wrapped in ``<tr>``
-  tags
+  tags.
 
-* ``{{ form.as_p }}`` will render them wrapped in ``<p>`` tags
+* ``{{ form.as_p }}`` will render them wrapped in ``<p>`` tags.
 
-* ``{{ form.as_ul }}`` will render them wrapped in ``<li>`` tags
+* ``{{ form.as_ul }}`` will render them wrapped in ``<li>`` tags.
 
 Note that you'll have to provide the surrounding ``<table>`` or ``<ul>``
 elements yourself.
-- 
cgit v1.3