Fixed #35892 -- Supported Widget.use_fieldset in admin forms and linked help texts aria-describedby for accessibility. #19678

Antoliny0919 · 2025-07-27T23:05:14Z

Trac ticket number

Branch description

continues PR..

Thank you to @sai-ganesh-03 for implementing the work, to @sarahboyce for offering guidance on the direction,
and to @knyghty for bringing up the issue 🥰

I updated the admin change form to use <fieldset> and <legend> tags for fields when use_fieldset is set to True.
I also connected additional help texts within widgets using aria-describedby.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

sarahboyce

Thank you for the PR ⭐

The styling of the legend is not right on mobile:

Also the AdminSplitDateTime widget (see django/contrib/admin/templates/admin/widgets/split_datetime.html) should have "Date" and "Time" in label tags associated with the appropriate inputs 👍

sarahboyce · 2025-07-29T07:07:48Z

django/contrib/admin/static/admin/js/SelectFilter2.js

@@ -47,7 +47,7 @@ Requires core.js and SelectBox.js.
                'p',
                selector_available_title,
                interpolate(gettext('Choose %s by selecting them and then select the "Choose" arrow button.'), [field_name]),
-                'class', 'helptext'
+                'id', `${field_id}_choose_helptext`, 'class', 'helptext'


This is the help text for the from box rather than the help text for the fieldset, so the from box should have the aria-describedby attribute (not the fieldset). Similar for the to box

Thank you for pointing out such an important detail.
Currently, when the select element is focused, it’s connected to the title via aria-labelledby, so both the label and a description are provided.
However, it might be better to provide the label via aria-labelledby, and then connect the help text and the instructions for selecting multiple options using aria-describedby.

sarahboyce · 2025-07-29T07:12:28Z

django/contrib/admin/static/admin/js/admin/DateTimeShortcuts.js

            warning.classList.add('help', warningClass);
+            warning.id = `${field_id}_timezone_warning_helptext`;


I think this helptext should also be specific to the input rather than the fieldset

Yes, I think the same. It seems better to associate it with each input element.

sarahboyce · 2025-07-29T07:18:26Z

django/contrib/admin/widgets.py

@@ -282,6 +287,8 @@ def __init__(
        self.can_view_related = not multiple and can_view_related
        # To check if the related object is registered with this AdminSite.
        self.admin_site = admin_site
+        self.use_fieldset = True


We potentially need to add use_fieldset = True to django.forms.widgets.ClearableFileInput which also is used (slightly customized) in the admin
Maybe add in a separate commit prior to this one if you agree with a test for forms

Antoliny0919 · 2025-07-30T10:01:59Z

New Accessibility Improvement Project 🎉🎉🎉

Antoliny0919 · 2025-07-30T11:24:59Z

Changed ..

Apply use_fieldset to fields in the Admin ChangeForm.
If a field has sub_help_text, provide a description when the associated node is accessed via aria-describedby.

When accessing each input field for DateTime, Date, and Time, a timezone explanation is provided.

For fields with filter_horizontal applied, the sub_help_text explaining how to select multiple items is provided in the selection boxes.

Previously, only the help text for the box type(from, to header) fields was provided.

…ed help texts aria-describedby for accessibility.

Antoliny0919 · 2025-07-30T12:11:44Z

After adding the label tag, the color of the Date and Time text became slightly lighter.
Would it be better to revert to the previous style?
It looks fine to me.

Before

After

sarahboyce · 2025-07-30T13:27:21Z

Would it be better to revert to the previous style?
It looks fine to me.

I also think it looks fine. More consistent with other labels 🤷

django/contrib/admin/templates/admin/widgets/split_datetime.html

sarahboyce

I noticed that the legends are styled black (rather than the grey styling of the labels), which needs an update

I did some testing with a screen reader and this is definitely an improvement to what we had 😁
I think this is getting close but I will let the accessibility team do more in depth testing

sarahboyce · 2025-08-04T12:30:04Z

tests/admin_widgets/tests.py

@@ -437,9 +441,14 @@ def test_render(self):
        self.assertHTMLEqual(
            w.render("test", datetime(2007, 12, 1, 9, 30)),
            '<p class="datetime">'
-            'Date: <input value="2007-12-01" type="text" class="vDateField" '
+            '<label for="">Date:</label> '


That the for is blank doesn't feel like a good test, could this widget be rendered for a field to have a value in the for attribute?

sarahboyce · 2025-08-04T12:36:12Z

tests/admin_views/models.py

+    difficulty = models.CharField(
+        max_length=20, choices=DIFFICULTY_CHOICES, null=True, blank=True
+    )
+    students = models.ManyToManyField(Student, blank=True)


To reduce the number of models, this could be:

Suggested change

students = models.ManyToManyField(Student, blank=True)

categories = models.ManyToManyField(Category, blank=True)

And we remove the student model

If we can avoid adding a new model entirely, that would also be good

sarahboyce · 2025-08-04T12:36:47Z

tests/admin_views/admin.py

+class CourseAdmin(admin.ModelAdmin):
+    radio_fields = {"difficulty": admin.VERTICAL}
+    filter_horizontal = ("students",)
+
+


Suggested change

class CourseAdmin(admin.ModelAdmin):

radio_fields = {"difficulty": admin.VERTICAL}

filter_horizontal = ("students",)

This is not required for the test, you can just do site.register(Course)

sarahboyce · 2025-08-04T12:48:18Z

js_tests/admin/DateTimeShortcuts.test.js

@@ -39,4 +39,5 @@ QUnit.test('time zone offset warning', function(assert) {
    DateTimeShortcuts.init();
    $('body').attr('data-admin-utc-offset', savedOffset);
    assert.equal($('.timezonewarning').text(), 'Note: You are 1 hour behind server time.');
+    assert.equal($('.timezonewarning').attr("id"), "_timezone_warning_helptext");


I think we want to update this test to better cover the code:

const id = inp.id; const field_id = inp.closest('p.datetime') ? id.slice(0, id.lastIndexOf("_")) : id; warning.classList.add('help', warningClass); warning.id = `${field_id}_timezone_warning_helptext`;

There are two cases here (which I believe might be a fieldset and normal field case)? I also don't like that the field id is not well formed in the test

sarahboyce added selenium Apply to have Selenium tests run on a PR screenshots 🖼️ labels Jul 29, 2025

sarahboyce reviewed Jul 29, 2025

View reviewed changes

knyghty requested a review from a team July 30, 2025 08:41

Antoliny0919 force-pushed the ticket_35892 branch 2 times, most recently from 55815b2 to 5b17a6e Compare July 30, 2025 09:58

Fixed #35892 -- Supported Widget.use_fieldset in admin forms and link…

4a03ac9

…ed help texts aria-describedby for accessibility.

Antoliny0919 force-pushed the ticket_35892 branch 2 times, most recently from 9403679 to 93a290f Compare July 30, 2025 12:09

sarahboyce reviewed Jul 30, 2025

View reviewed changes

django/contrib/admin/templates/admin/widgets/split_datetime.html Outdated Show resolved Hide resolved

Antoliny0919 force-pushed the ticket_35892 branch from 93a290f to 878b956 Compare July 30, 2025 13:51

Added use_fieldset to the ClearableFileInput widget.

8289d96

Antoliny0919 force-pushed the ticket_35892 branch from 878b956 to 8289d96 Compare July 30, 2025 14:03

sarahboyce mentioned this pull request Aug 4, 2025

Fixed #35892 -- Supported Widget.use_fieldset in admin forms #18803

Closed

6 tasks

sarahboyce reviewed Aug 4, 2025

View reviewed changes

		warning.classList.add('help', warningClass);
		warning.id = `${field_id}_timezone_warning_helptext`;

	students = models.ManyToManyField(Student, blank=True)
	categories = models.ManyToManyField(Category, blank=True)

	class CourseAdmin(admin.ModelAdmin):
	radio_fields = {"difficulty": admin.VERTICAL}
	filter_horizontal = ("students",)

Uh oh!

Fixed #35892 -- Supported Widget.use_fieldset in admin forms and linked help texts aria-describedby for accessibility. #19678

Are you sure you want to change the base?

Fixed #35892 -- Supported Widget.use_fieldset in admin forms and linked help texts aria-describedby for accessibility. #19678

Conversation

Antoliny0919 commented Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Trac ticket number

Branch description

Checklist

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 commented Jul 30, 2025

Uh oh!

Antoliny0919 commented Jul 30, 2025

Changed ..

Uh oh!

Antoliny0919 commented Jul 30, 2025

Before

After

Uh oh!

sarahboyce commented Jul 30, 2025

Uh oh!

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Antoliny0919 commented Jul 27, 2025 •

edited

Loading