Always set help text element ID for form fields with help text in fie…

…ld.html template
Stormheg · Jul 24, 2023 · 89ce882 · 89ce882
1 parent c220662
commit 89ce882
Show file tree

Hide file tree

Showing 5 changed files with 52 additions and 4 deletions.
diff --git a/CHANGELOG.txt b/CHANGELOG.txt
@@ -5,6 +5,7 @@ Changelog
 ~~~~~~~~~~~~~~~~
 
  * Add preview-aware and page-aware fragment caching template tags, `wagtailcache` & `wagtailpagecache` (Jake Howard)
+ * Always set help text element ID for form fields with help text in `field.html` template (Sage Abdullah)
  * Maintenance: Fix snippet search test to work on non-fallback database backends (Matt Westcott)
 
 

diff --git a/docs/releases/5.2.md b/docs/releases/5.2.md
@@ -15,6 +15,7 @@ depth: 1
 ### Other features
 
  * Add [`wagtailcache`](wagtailcache) and [`wagtailpagecache`](wagtailpagecache) template tags to ensure previewing Pages or Snippets will not be cached (Jake Howard)
+ * Always set help text element ID for form fields with help text in `field.html` template (Sage Abdullah)
 
 ### Bug fixes
 

diff --git a/wagtail/admin/templates/wagtailadmin/shared/field.html b/wagtail/admin/templates/wagtailadmin/shared/field.html
@@ -49,7 +49,9 @@
             {% endif %}
         </div>
 
-        <div class="w-field__help" {% if help_text_id %}id="{{ help_text_id }}"{% endif %} data-field-help>
+        {# If help_text_id is in the context, use it. #}
+        {# Otherwise, if the field has help_text and id_for_label, automatically generate the id with that. #}
+        <div class="w-field__help" {% if help_text_id %}id="{{ help_text_id }}"{% elif field.help_text and field.id_for_label %}id="{{ field.id_for_label }}-helptext"{% endif %} data-field-help>
             {% firstof help_text field.help_text as help_text_value %}
             {% if help_text_value %}
                 <div class="help">{{ help_text_value }}</div>

diff --git a/wagtail/admin/templatetags/wagtailadmin_tags.py b/wagtail/admin/templatetags/wagtailadmin_tags.py
@@ -343,7 +343,23 @@ def render_with_errors(bound_field):
             errors=bound_field.errors,
         )
     else:
-        return bound_field.as_widget()
+        attrs = {}
+        # If the widget doesn't have an aria-describedby attribute,
+        # and the field has help text, and the field has an id,
+        # add an aria-describedby attribute pointing to the help text.
+        # In this case, the corresponding help text element's id is set in the
+        # wagtailadmin/shared/field.html template.
+
+        # In Django 5.0 and up, this is done automatically, but we want to keep
+        # this code because we use a different convention for the help text id
+        # (we use -helptext suffix instead of Django's _helptext).
+        if (
+            not bound_field.field.widget.attrs.get("aria-describedby")
+            and bound_field.field.help_text
+            and bound_field.id_for_label
+        ):
+            attrs["aria-describedby"] = f"{bound_field.id_for_label}-helptext"
+        return bound_field.as_widget(attrs=attrs)
 
 
 @register.filter

diff --git a/wagtail/admin/tests/test_views.py b/wagtail/admin/tests/test_views.py
@@ -86,7 +86,21 @@ def test_bidi_language_changes_dir_attribute(self):
     def test_login_page_renders_extra_fields(self):
         response = self.client.get(reverse("wagtailadmin_login"))
         self.assertContains(
-            response, '<input type="text" name="captcha" required id="id_captcha">'
+            response,
+            """
+            <input type="text" name="captcha" required
+            aria-describedby="id_captcha-helptext" id="id_captcha">
+            """,
+            html=True,
+        )
+        self.assertContains(
+            response,
+            """
+            <div class="w-field__help" id="id_captcha-helptext" data-field-help>
+                <div class="help">should be in extra_fields()</div>
+            </div>
+            """,
+            html=True,
         )
 
     def test_session_expire_on_browser_close(self):
@@ -126,7 +140,21 @@ def test_password_reset_view_uses_correct_form(self):
     def test_password_reset_page_renders_extra_fields(self):
         response = self.client.get(reverse("wagtailadmin_password_reset"))
         self.assertContains(
-            response, '<input type="text" name="captcha" required id="id_captcha">'
+            response,
+            """
+            <input type="text" name="captcha" required
+            aria-describedby="id_captcha-helptext" id="id_captcha">
+            """,
+            html=True,
+        )
+        self.assertContains(
+            response,
+            """
+            <div class="w-field__help" id="id_captcha-helptext" data-field-help>
+                <div class="help">should be in extra_fields()</div>
+            </div>
+            """,
+            html=True,
         )