Opened 3 hours ago

Last modified 2 hours ago

#36904 new Uncategorized

Form Field label - improve documentation to explain how to omit labels

Reported by: Alastair Porter Owned by:
Component: Documentation Version: 6.0
Severity: Normal Keywords:
Cc: jaffar Khan Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The documentation for form fields labels (https://docs.djangoproject.com/en/6.0/ref/forms/fields/#label) says

Specify label if that default behavior doesn’t result in an adequate label.

In our app we had a situation where we didn't want to use the django default label. so we set

class MyForm(forms.Form):
    email1 = forms.EmailField(label=False, max_length=254)

resulting in the label being omitted from the form when we generate it due to the {% if field.label %} check at https://github.com/django/django/blob/986f7f2098a2186b4085183951cbebae15220556/django/forms/templates/django/forms/p.html#L8

When we implemented type checking with django-stubs, we got a type error here saying that label can only be str or None, prompting me to open https://github.com/typeddjango/django-stubs/issues/3028

In the resulting discussion, it became clear that it would be probably be better to use label="" to set the label to empty, but this isn't documented as a best practise.

One comment by a django-stubs maintainer (copied from the above ticket):

it just happens to work by accident. In the source code it does {% if field.label %} before rendering, so falsy values like False get skipped. But if you call label_tag() directly, it actually renders the literal text "False" as the label, and label=True crashes with a TypeError

It would be nice to update the documentation with this specific recommendation. This could be as simple as

Specify a string for label if that default behavior doesn’t result in an adequate label. Use an empty string to hide the label.

Change History (1)

comment:1 by jaffar Khan, 2 hours ago

Cc: jaffar Khan added
Note: See TracTickets for help on using tickets.
Back to Top