Opened 3 years ago

Last modified 3 years ago

#32340 new Cleanup/optimization

Usability issues with Django form fields expecting specific patterns

Reported by: Thibaud Colas Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords: accessibility, usability, forms
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: yes


Related: #32338, #32339.

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.

Change History (5)

comment:1 Changed 3 years ago by Carlton Gibson

Component: FormsDocumentation
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

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! 👍

comment:2 Changed 3 years ago 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.

comment:3 Changed 3 years ago 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:

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.

comment:4 Changed 3 years ago 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... :)

comment:5 Changed 3 years ago 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

  1. 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.


Note: See TracTickets for help on using tickets.
Back to Top