Refs #32338 -- Added Boundfield.legend_tag().

6 files changed, 141 insertions, 12 deletions

diff --git a/tests/forms_tests/templates/forms_tests/legend_test.html b/tests/forms_tests/templates/forms_tests/legend_test.html
new file mode 100644
index 0000000000..436485e794
--- /dev/null
+++ b/tests/forms_tests/templates/forms_tests/legend_test.html
@@ -0,0 +1,7 @@
+{% for field in form %}
+  {% if field.widget_type == 'radioselect' %}
+    {{ field.legend_tag }}
+  {% else %}
+    {{ field.label_tag }}
+  {% endif %}
+{% endfor %}
diff --git a/tests/forms_tests/tests/test_forms.py b/tests/forms_tests/tests/test_forms.py
index c478a71699..7e0bdeeb77 100644
--- a/tests/forms_tests/tests/test_forms.py
+++ b/tests/forms_tests/tests/test_forms.py
@@ -2728,7 +2728,8 @@ Password: <input type="password" name="password" required>
 
     def test_label_has_required_css_class(self):
         """
-        #17922 - required_css_class is added to the label_tag() of required fields.
+        required_css_class is added to label_tag() and legend_tag() of required
+        fields.
         """
         class SomeForm(Form):
             required_css_class = 'required'
@@ -2738,10 +2739,22 @@ Password: <input type="password" name="password" required>
         f = SomeForm({'field': 'test'})
         self.assertHTMLEqual(f['field'].label_tag(), '<label for="id_field" class="required">Field:</label>')
         self.assertHTMLEqual(
+            f['field'].legend_tag(),
+            '<legend for="id_field" class="required">Field:</legend>',
+        )
+        self.assertHTMLEqual(
             f['field'].label_tag(attrs={'class': 'foo'}),
             '<label for="id_field" class="foo required">Field:</label>'
         )
+        self.assertHTMLEqual(
+            f['field'].legend_tag(attrs={'class': 'foo'}),
+            '<legend for="id_field" class="foo required">Field:</legend>'
+        )
         self.assertHTMLEqual(f['field2'].label_tag(), '<label for="id_field2">Field2:</label>')
+        self.assertHTMLEqual(
+            f['field2'].legend_tag(),
+            '<legend for="id_field2">Field2:</legend>',
+        )
 
     def test_label_split_datetime_not_displayed(self):
         class EventForm(Form):
@@ -2964,34 +2977,47 @@ Password: <input type="password" name="password" required>
 
         testcases = [  # (args, kwargs, expected)
             # without anything: just print the <label>
-            ((), {}, '<label for="id_field">Field:</label>'),
+            ((), {}, '<%(tag)s for="id_field">Field:</%(tag)s>'),
 
             # passing just one argument: overrides the field's label
-            (('custom',), {}, '<label for="id_field">custom:</label>'),
+            (('custom',), {}, '<%(tag)s for="id_field">custom:</%(tag)s>'),
 
             # the overridden label is escaped
-            (('custom&',), {}, '<label for="id_field">custom&amp;:</label>'),
-            ((mark_safe('custom&'),), {}, '<label for="id_field">custom&:</label>'),
+            (('custom&',), {}, '<%(tag)s for="id_field">custom&amp;:</%(tag)s>'),
+            ((mark_safe('custom&'),), {}, '<%(tag)s for="id_field">custom&:</%(tag)s>'),
 
             # Passing attrs to add extra attributes on the <label>
-            ((), {'attrs': {'class': 'pretty'}}, '<label for="id_field" class="pretty">Field:</label>')
+            (
+                (),
+                {'attrs': {'class': 'pretty'}},
+                '<%(tag)s for="id_field" class="pretty">Field:</%(tag)s>',
+            ),
         ]
 
         for args, kwargs, expected in testcases:
             with self.subTest(args=args, kwargs=kwargs):
-                self.assertHTMLEqual(boundfield.label_tag(*args, **kwargs), expected)
+                self.assertHTMLEqual(
+                    boundfield.label_tag(*args, **kwargs),
+                    expected % {'tag': 'label'},
+                )
+                self.assertHTMLEqual(
+                    boundfield.legend_tag(*args, **kwargs),
+                    expected % {'tag': 'legend'},
+                )
 
     def test_boundfield_label_tag_no_id(self):
         """
-        If a widget has no id, label_tag just returns the text with no
-        surrounding <label>.
+        If a widget has no id, label_tag() and legend_tag() return the text
+        with no surrounding <label>.
         """
         class SomeForm(Form):
             field = CharField()
         boundfield = SomeForm(auto_id='')['field']
 
         self.assertHTMLEqual(boundfield.label_tag(), 'Field:')
+        self.assertHTMLEqual(boundfield.legend_tag(), 'Field:')
         self.assertHTMLEqual(boundfield.label_tag('Custom&'), 'Custom&amp;:')
+        self.assertHTMLEqual(boundfield.legend_tag('Custom&'), 'Custom&amp;:')
 
     def test_boundfield_label_tag_custom_widget_id_for_label(self):
         class CustomIdForLabelTextInput(TextInput):
@@ -3008,7 +3034,12 @@ Password: <input type="password" name="password" required>
 
         form = SomeForm()
         self.assertHTMLEqual(form['custom'].label_tag(), '<label for="custom_id_custom">Custom:</label>')
+        self.assertHTMLEqual(
+            form['custom'].legend_tag(),
+            '<legend for="custom_id_custom">Custom:</legend>',
+        )
         self.assertHTMLEqual(form['empty'].label_tag(), '<label>Empty:</label>')
+        self.assertHTMLEqual(form['empty'].legend_tag(), '<legend>Empty:</legend>')
 
     def test_boundfield_empty_label(self):
         class SomeForm(Form):
@@ -3016,6 +3047,10 @@ Password: <input type="password" name="password" required>
         boundfield = SomeForm()['field']
 
         self.assertHTMLEqual(boundfield.label_tag(), '<label for="id_field"></label>')
+        self.assertHTMLEqual(
+            boundfield.legend_tag(),
+            '<legend for="id_field"></legend>',
+        )
 
     def test_boundfield_id_for_label(self):
         class SomeForm(Form):
@@ -3069,7 +3104,7 @@ Password: <input type="password" name="password" required>
         self.assertEqual(field.css_classes(extra_classes='test'), 'test')
         self.assertEqual(field.css_classes(extra_classes='test test'), 'test')
 
-    def test_label_tag_override(self):
+    def test_label_suffix_override(self):
         """
         BoundField label_suffix (if provided) overrides Form label_suffix
         """
@@ -3078,6 +3113,10 @@ Password: <input type="password" name="password" required>
         boundfield = SomeForm(label_suffix='!')['field']
 
         self.assertHTMLEqual(boundfield.label_tag(label_suffix='$'), '<label for="id_field">Field$</label>')
+        self.assertHTMLEqual(
+            boundfield.legend_tag(label_suffix='$'),
+            '<legend for="id_field">Field$</legend>',
+        )
 
     def test_error_dict(self):
         class MyForm(Form):
@@ -3526,9 +3565,10 @@ Password: <input type="password" name="password" required>
     def test_label_does_not_include_new_line(self):
         form = Person()
         field = form['first_name']
+        self.assertEqual(field.label_tag(), '<label for="id_first_name">First name:</label>')
         self.assertEqual(
-            field.label_tag(),
-            '<label for="id_first_name">First name:</label>',
+            field.legend_tag(),
+            '<legend for="id_first_name">First name:</legend>',
         )
 
     @override_settings(USE_THOUSAND_SEPARATOR=True)
@@ -3539,6 +3579,10 @@ Password: <input type="password" name="password" required>
             field.label_tag(attrs={'number': 9999}),
             '<label number="9999" for="id_first_name">First name:</label>',
         )
+        self.assertHTMLEqual(
+            field.legend_tag(attrs={'number': 9999}),
+            '<legend number="9999" for="id_first_name">First name:</legend>',
+        )
 
 
 @jinja2_tests
@@ -3747,6 +3791,43 @@ class TemplateTests(SimpleTestCase):
             '<input type="submit" required>'
             '</form>',
         )
+        # Use form.[field].legend_tag to output a field's label with a <legend>
+        # tag wrapped around it, but *only* if the given field has an "id"
+        # attribute. Recall from above that passing the "auto_id" argument to a
+        # Form gives each field an "id" attribute.
+        t = Template(
+            '<form>'
+            '<p>{{ form.username.legend_tag }} {{ form.username }}</p>'
+            '<p>{{ form.password1.legend_tag }} {{ form.password1 }}</p>'
+            '<p>{{ form.password2.legend_tag }} {{ form.password2 }}</p>'
+            '<input type="submit" required>'
+            '</form>'
+        )
+        f = UserRegistration(auto_id=False)
+        self.assertHTMLEqual(
+            t.render(Context({'form': f})),
+            '<form>'
+            '<p>Username: '
+            '<input type="text" name="username" maxlength="10" required></p>'
+            '<p>Password1: <input type="password" name="password1" required></p>'
+            '<p>Password2: <input type="password" name="password2" required></p>'
+            '<input type="submit" required>'
+            '</form>',
+        )
+        f = UserRegistration(auto_id='id_%s')
+        self.assertHTMLEqual(
+            t.render(Context({'form': f})),
+            '<form>'
+            '<p><legend for="id_username">Username:</legend>'
+            '<input id="id_username" type="text" name="username" maxlength="10" '
+            'required></p>'
+            '<p><legend for="id_password1">Password1:</legend>'
+            '<input type="password" name="password1" id="id_password1" required></p>'
+            '<p><legend for="id_password2">Password2:</legend>'
+            '<input type="password" name="password2" id="id_password2" required></p>'
+            '<input type="submit" required>'
+            '</form>',
+        )
         # Use form.[field].help_text to output a field's help text. If the
         # given field does not have help text, nothing will be output.
         t = Template(
@@ -3965,3 +4046,15 @@ class OverrideTests(SimpleTestCase):
             self.assertInHTML('<th>1</th>', f.render())
         except RecursionError:
             self.fail('Cyclic reference in BoundField.render().')
+
+    def test_legend_tag(self):
+        class CustomFrameworkForm(FrameworkForm):
+            template_name = 'forms_tests/legend_test.html'
+            required_css_class = 'required'
+
+        f = CustomFrameworkForm()
+        self.assertHTMLEqual(
+            str(f),
+            '<label for="id_name" class="required">Name:</label>'
+            '<legend class="required">Language:</legend>',
+        )
diff --git a/tests/forms_tests/tests/test_i18n.py b/tests/forms_tests/tests/test_i18n.py
index 67aafa0527..29967b2cb7 100644
--- a/tests/forms_tests/tests/test_i18n.py
+++ b/tests/forms_tests/tests/test_i18n.py
@@ -44,7 +44,15 @@ class FormsI18nTests(SimpleTestCase):
 
         f = SomeForm()
         self.assertHTMLEqual(f['field_1'].label_tag(), '<label for="id_field_1">field_1:</label>')
+        self.assertHTMLEqual(
+            f['field_1'].legend_tag(),
+            '<legend for="id_field_1">field_1:</legend>',
+        )
         self.assertHTMLEqual(f['field_2'].label_tag(), '<label for="field_2_id">field_2:</label>')
+        self.assertHTMLEqual(
+            f['field_2'].legend_tag(),
+            '<legend for="field_2_id">field_2:</legend>',
+        )
 
     def test_non_ascii_choices(self):
         class SomeForm(Form):
diff --git a/tests/forms_tests/widget_tests/test_checkboxselectmultiple.py b/tests/forms_tests/widget_tests/test_checkboxselectmultiple.py
index e831038e02..65025ed748 100644
--- a/tests/forms_tests/widget_tests/test_checkboxselectmultiple.py
+++ b/tests/forms_tests/widget_tests/test_checkboxselectmultiple.py
@@ -185,3 +185,4 @@ class CheckboxSelectMultipleTest(WidgetTest):
         bound_field = TestForm()['f']
         self.assertEqual(bound_field.field.widget.id_for_label('id'), '')
         self.assertEqual(bound_field.label_tag(), '<label>F:</label>')
+        self.assertEqual(bound_field.legend_tag(), '<legend>F:</legend>')
diff --git a/tests/model_forms/tests.py b/tests/model_forms/tests.py
index 7907aa1c3d..0307569c12 100644
--- a/tests/model_forms/tests.py
+++ b/tests/model_forms/tests.py
@@ -830,6 +830,18 @@ class TestFieldOverridesByFormMeta(SimpleTestCase):
             str(form['slug'].label_tag()),
             '<label for="id_slug">Slug:</label>',
         )
+        self.assertHTMLEqual(
+            form['name'].legend_tag(),
+            '<legend for="id_name">Title:</legend>',
+        )
+        self.assertHTMLEqual(
+            form['url'].legend_tag(),
+            '<legend for="id_url">The URL:</legend>',
+        )
+        self.assertHTMLEqual(
+            form['slug'].legend_tag(),
+            '<legend for="id_slug">Slug:</legend>',
+        )
 
     def test_help_text_overrides(self):
         form = FieldOverridesByFormMetaForm()
diff --git a/tests/model_formsets/tests.py b/tests/model_formsets/tests.py
index 49e7705c2f..bb1a8a8a5e 100644
--- a/tests/model_formsets/tests.py
+++ b/tests/model_formsets/tests.py
@@ -1801,6 +1801,10 @@ class TestModelFormsetOverridesTroughFormMeta(TestCase):
         })
         form = BookFormSet.form()
         self.assertHTMLEqual(form['title'].label_tag(), '<label for="id_title">Name:</label>')
+        self.assertHTMLEqual(
+            form['title'].legend_tag(),
+            '<legend for="id_title">Name:</legend>',
+        )
 
     def test_inlineformset_factory_labels_overrides(self):
         BookFormSet = inlineformset_factory(Author, Book, fields="__all__", labels={
@@ -1808,6 +1812,10 @@ class TestModelFormsetOverridesTroughFormMeta(TestCase):
         })
         form = BookFormSet.form()
         self.assertHTMLEqual(form['title'].label_tag(), '<label for="id_title">Name:</label>')
+        self.assertHTMLEqual(
+            form['title'].legend_tag(),
+            '<legend for="id_title">Name:</legend>',
+        )
 
     def test_modelformset_factory_help_text_overrides(self):
         BookFormSet = modelformset_factory(Book, fields="__all__", help_texts={