[Django] #32340: Usability issues with Django form fields expecting specific patterns
Django
-------------------------------------+-------------------------------------
Reporter: Thibaud | Owner: nobody
Colas |
Type: | Status: new
Uncategorized |
Component: Forms | Version: master
Severity: Normal | Keywords: accessibility,
Triage Stage: | usability, forms
Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 1 |
-------------------------------------+-------------------------------------
Related: [https://code.djangoproject.com/ticket/32338 #32338],
[https://code.djangoproject.com/ticket/32339 #32339].
- Test form I’m basing this report on: http://django-admin-
tests.herokuapp.com/forms/example_form/p/
- Form fields definitions:
https://github.com/thibaudcolas/django_admin_tests/blob/main/django_admin_tests/forms.py
- Template:
https://github.com/thibaudcolas/django_admin_tests/blob/main/django_admin_tests/templates/django_admin_tests/example_form.html
Django offers a lot of fields that expect specific formats:
- Date and time fields – DateField, DatetimeField, TimeField,
SplitDateTimeField, DurationField
- More technical fields which have very specific formats: SlugField,
JSONField, UUIDField, RegexField, GenericIPAddressField
The default widget markup for all of those fields never displays the
expected format. For some fields this can somewhat be addressed via the
field’s label or help text (for example having "JSON" in the label, or a
description of a regex pattern in help text). But not for all. This is
particularly problematic for date and time fields:
- Even though end users know about date formats, just saying a field
expects a "Date" is never enough to know which specific format is
expected.
- Django supports providing supported formats globally via settings, and
at the field level. Ideally the widget would display the format(s) it’s
accepting based on this configuration, rather than having to hard-code it
in help text, which is prone to being incorrect / falling out of date /
not being set.
- The default error messages for invalid formats are vague ("Enter a valid
date.", "Enter a valid date/time.", "Enter a valid duration.").
I don’t think this is something that can necessarily be solved for all
cases directly in Django, but thought it would be worth raising
nonetheless. As-is, having default templates for those widgets makes it
easy for developers to overlook the need for this guidance. And we end up
with forms that are impossible to fill.
Solutions I can think of are:
- Update documentation to at least express the need for communicating the
expected format to end users. Ideally have examples of communicating those
formats for specific field types.
- Find a way to auto-display the format alongside the help text for the
field.
- Update the error messages to actually display the expected formats,
rather than a basic "Enter a valid <field type>".
I hope this makes sense, even though again this isn’t as clear-cut as the
other forms issues I noticed.
--
Ticket URL: <https://code.djangoproject.com/ticket/32340>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
* type: Uncategorized => Cleanup/optimization
* component: Forms => Documentation
* stage: Unreviewed => Accepted
Comment:
Hi Thibaud.
Initially let's accept this as a Documentation issue. Certainly we can do
that right? 😀
**Very happy** to consider specific changes that you come up with here
too!
Without some idea of what we might do though, it's a bit `needsinfo` —
maybe targeted changes for single fields to begin...?
A proof-of-concept here would help push it forward.
Thanks! 👍
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:1>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
Comment (by Thibaud Colas):
Thank you, I think I’ll start with getting more familiar with the
documentation so I can figure out where best to address this. And as I do
I’ll likely have to come up with code snippets that might inform further
changes.
I think it would also be good to get feedback from others here – on the
specific issues outlined here, and perhaps also more generally on how much
it’s Django’s role to make sure it’s not too easy to misuse.
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:2>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
Comment (by Thibaud Colas):
I have discussed this again with a coworker, and we think that as an
immediate action it would be best to have "accessibility considerations"
as a standalone page in the forms / fields documentation, or cover it
separately for each field, as preferred.
For the issues listed here, this would allow us to:
- Recommend using help_text (or template overrides?) to display the
expected date format, with practical copy-paste-able examples
- At the same time we could briefly mention why this is better than
alternatives (having the format in error messages or as a placeholder
attribute – both better than nothing but poor in comparison).
Additionally, in the future, we could also cover common considerations for
other field types:
- How it’s rarely appropriate to use `type="number"` even if the field
might be storable as a number (see
https://technology.blog.gov.uk/2020/02/24/why-the-gov-uk-design-system-
team-changed-the-input-type-for-numbers/).
- How a `type=”date”` input should be favoured if browser support for a
given project allows it
And broader considerations that are relevant for all field types:
- Usage of fieldsets
- Usage of autocomplete / autocapitalize attributes
- Visually distinguishing between optional and required fields
---
This goes beyond what I reported here initially, and I’d still personally
prefer something that could be done in Django core directly, but thought
it would be worth mentioning nonetheless.
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:3>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
Comment (by Carlton Gibson):
HI Thibauld.
I think a small section in the docs would be great. We don't want to write
a whole guide, but showing some basics and (if there are canonical
resources) pointing on to more would likely be in scope.
I think we can get some changes here into core too... :)
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:4>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
Comment (by Surya):
Hi Thibauld and Tom,
I am a new contributor and after looking into issue tracker, I see this as
a ticket that I would love to work on if nobody else is working on it.
In case I get to work on this, I had a couple of questions regarding what
needs to be done. Carlton asked me to ask my question here, so here it
goes.
1. For the suggestion of having explicit instructions on the Django
documentation about the format of the form fields, as described in the
ticket, should I focus on mentioning the default formats for the following
fields -
Date and time fields – DateField, DatetimeField, TimeField,
SplitDateTimeField, DurationField
More technical fields which have very specific formats: SlugField,
JSONField, UUIDField, RegexField, GenericIPAddressField
2. Should the changes in the documentation extend to issues such as #32339
or #32338 on why it should be avoided?
Please forgive me if I have not been able to understand the ticket
responsibility the way it is intended, and I would be very grateful if the
scope of the changes required could be pointed out to me by any senior
member of the community.
Thanks,
Surya
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:5>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
Comment (by Thibaud Colas):
See PR [Accessibility guidelines for all contributors #17338
https://github.com/django/django/pull/17338] for the next step on adding
accessibility docs in Django. After this, I believe [Add guidelines for
accessibility in documentation #17340
https://github.com/django/django/pull/17340] will be a good step in adding
accessibility considerations in documentation.
After _that_, I think we’ll be in an excellent place for someone to pick
up this ticket and write the right docs. We don’t necessarily need all of
this to be merged though if someone wants to already take a look. A good
first step would be to identify where in Django’s documentation we could
document what’s discussed in this ticket.
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:6>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
Replying to [comment:6 Thibaud Colas]:
Hi Thibaud,
> After _that_, I think we’ll be in an excellent place for someone to pick
up this ticket and write the right docs.
What I can understand by going through this ticket is that we need to add
more explicit examples of input formats to the form fields in our Docs. To
get more clarity, I would like to know if the requirement is somewhat like
detailed examples stated in DateTimeField
https://docs.djangoproject.com/en/5.0/ref/forms/fields/#datetimefield
whereas just a link to accepted formats is given in DateField
https://docs.djangoproject.com/en/5.0/ref/forms/fields/#datefield. So are
we looking to provide more information here?
> A good first step would be to identify where in Django’s documentation
we could document what’s discussed in this ticket.
If my understanding of the ticket is apt, I would say adding the details
within the respective fields themselves would be better as it would
provide an easier understanding to the end user at a glance rather than
moving to an altogether different section.
Please correct me if I am proceeding in the wrong direction.
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:7>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
* cc: Ülgen Sarıkavak (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:8>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
"This issue can be resolved by:
Adding placeholders to widgets like DateInput and TimeInput for better
usability (e.g., 'YYYY-MM-DD' for dates).
Customizing error messages in DateField and similar fields to clearly
communicate the expected format.
Updating templates to display placeholders and help texts dynamically.
Enhancing documentation with examples of expected formats for various
fields.
I am assigning this issue to myself and will submit a patch addressing
these points soon. Please let me know if any further inputs are needed."
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:9>
Django
-------------------------------------+-------------------------------------
Type: | Khatri
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
* owner: nobody => Ayush Khatri
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:10>
Django
-------------------------------------+-------------------------------------
Type: | panwar
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
* owner: Ayush Khatri => Bhupesh panwar
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:11>
Django
-------------------------------------+-------------------------------------
Type: | Boulton1
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
* owner: Bhupesh panwar => Jordan-Boulton1
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:12>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Easy pickings: 0 | UI/UX: 1
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:13>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage: Accepted
usability, forms |
Needs tests: 0 | Patch needs improvement: 1
-------------------------------------+-------------------------------------
* needs_better_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/32340#comment:14>