diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ref/forms/fields.txt | 42 | ||||
| -rw-r--r-- | docs/releases/5.0.txt | 16 | ||||
| -rw-r--r-- | docs/topics/forms/index.txt | 4 |
3 files changed, 58 insertions, 4 deletions
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index e443e9eabf..77ccc9e862 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -275,6 +275,48 @@ fields. We've specified ``auto_id=False`` to simplify the output: <div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div> <div>Cc myself:<input type="checkbox" name="cc_myself"></div> +When a field has help text and :attr:`~django.forms.BoundField.id_for_label` +returns a value, we associate ``help_text`` with the input using the +``aria-describedby`` HTML attribute: + +.. code-block:: pycon + + >>> from django import forms + >>> class UserForm(forms.Form): + ... username = forms.CharField(max_length=255, help_text="e.g., user@example.com") + ... + >>> f = UserForm() + >>> print(f) + <div> + <label for="id_username">Username:</label> + <div class="helptext" id="id_username_helptext">e.g., user@example.com</div> + <input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username"> + </div> + +When adding a custom ``aria-describedby`` attribute, make sure to also include +the ``id`` of the ``help_text`` element (if used) in the desired order. For +screen reader users, descriptions will be read in their order of appearance +inside ``aria-describedby``: + +.. code-block:: pycon + + >>> class UserForm(forms.Form): + ... username = forms.CharField( + ... max_length=255, + ... help_text="e.g., user@example.com", + ... widget=forms.TextInput( + ... attrs={"aria-describedby": "custom-description id_username_helptext"}, + ... ), + ... ) + ... + >>> f = UserForm() + >>> print(f["username"]) + <input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required> + +.. versionchanged:: 5.0 + + ``aria-describedby`` was added to associate ``help_text`` with its input. + ``error_messages`` ------------------ diff --git a/docs/releases/5.0.txt b/docs/releases/5.0.txt index a2a04c6060..f309721d44 100644 --- a/docs/releases/5.0.txt +++ b/docs/releases/5.0.txt @@ -61,7 +61,9 @@ For example, the template below: <div> {{ form.name.label_tag }} {% if form.name.help_text %} - <div class="helptext">{{ form.name.help_text|safe }}</div> + <div class="helptext" id="{{ form.name.id_for_label }}_helptext"> + {{ form.name.help_text|safe }} + </div> {% endif %} {{ form.name.errors }} {{ form.name }} @@ -69,7 +71,9 @@ For example, the template below: <div class="col"> {{ form.email.label_tag }} {% if form.email.help_text %} - <div class="helptext">{{ form.email.help_text|safe }}</div> + <div class="helptext" id="{{ form.email.id_for_label }}_helptext"> + {{ form.email.help_text|safe }} + </div> {% endif %} {{ form.email.errors }} {{ form.email }} @@ -77,7 +81,9 @@ For example, the template below: <div class="col"> {{ form.password.label_tag }} {% if form.password.help_text %} - <div class="helptext">{{ form.password.help_text|safe }}</div> + <div class="helptext" id="{{ form.password.id_for_label }}_helptext"> + {{ form.password.help_text|safe }} + </div> {% endif %} {{ form.password.errors }} {{ form.password }} @@ -294,6 +300,10 @@ Forms * The new ``assume_scheme`` argument for :class:`~django.forms.URLField` allows specifying a default URL scheme. +* In order to improve accessibility and enable screen readers to associate form + fields with their help text, the form field now includes the + ``aria-describedby`` HTML attribute. + Generic Views ~~~~~~~~~~~~~ diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 27ea496ca6..673111b025 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -723,7 +723,9 @@ loop: {{ field.errors }} {{ field.label_tag }} {{ field }} {% if field.help_text %} - <p class="help">{{ field.help_text|safe }}</p> + <p class="help" id="{{ field.id_for_label }}_helptext"> + {{ field.help_text|safe }} + </p> {% endif %} </div> {% endfor %} |