[Django] #36904: Form Field label - improve documentation to explain how to omit labels

[Django]

#36904: Form Field label - improve documentation to explain how to omit labels
---------------------------------+-----------------------------------------
Reporter: Alastair Porter | Type: Uncategorized
Status: new | Component: Documentation
Version: 6.0 | Severity: Normal
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
---------------------------------+-----------------------------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/36904>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36904: Form Field label - improve documentation to explain how to omit labels
---------------------------------+--------------------------------------

Reporter: Alastair Porter | Owner: (none)

Type: Uncategorized | Status: new
Component: Documentation | Version: 6.0

Severity: Normal | Resolution:

Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
---------------------------------+--------------------------------------

Changes (by jaffar Khan):

* cc: jaffar Khan (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/36904#comment:1>

[Django]

#36904: Form Field label - improve documentation to explain how to omit labels
---------------------------------+--------------------------------------

Reporter: Alastair Porter | Owner: Amar
Type: Uncategorized | Status: assigned

Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
---------------------------------+--------------------------------------

Changes (by Amar):

* owner: (none) => Amar
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36904#comment:2>

[Django]

#36904: Form Field label - improve documentation to explain how to omit labels

--------------------------------------+------------------------------------

Reporter: Alastair Porter | Owner: Amar

Type: Cleanup/optimization | Status: assigned

Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Jacob Walls):

* stage: Unreviewed => Accepted
* type: Uncategorized => Cleanup/optimization

--
Ticket URL: <https://code.djangoproject.com/ticket/36904#comment:3>