id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
32340	Usability issues with Django form fields expecting specific patterns	Thibaud Colas	Jordan	"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."	Cleanup/optimization	assigned	Documentation	dev	Normal		accessibility, usability, forms	Ülgen Sarıkavak	Accepted	1	0	0	1	0	1