[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>

[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: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Amar):

* has_patch: 0 => 1

Comment:

https://github.com/django/django/pull/20654
--
Ticket URL: <https://code.djangoproject.com/ticket/36904#comment:4>

[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: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Shubh Rai):

Replying to [comment:4 Amar]:
> https://github.com/django/django/pull/20654


Hi, I noticed the PR is failing some checks . Are you still working on
this? If not, I would be happy to help work on the fix.
--
Ticket URL: <https://code.djangoproject.com/ticket/36904#comment:5>

[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: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Amar):

Hey Shubh, yeah I'm still working on this.

If you look at what's failing, the two checks are MySQL/MySQL GIS database
tests — this is a docs-only change, so those have nothing to do with my
PR.

Also worth noting the PR hasn't gotten any reviews yet, so there's not
much to act on from my side right now.

Btw if you haven't seen it, Sarah Boyce has a talk on the Djangonaut Space
channel ([https://www.youtube.com/watch?v=A-3eTMNQ3rM&t=647s "Your First
Django Contribution"] , around the 8:55 mark) where she talks about giving
contributors some time to work through their PRs before stepping in.
Really good watch.

Thanks for the interest though!
--
Ticket URL: <https://code.djangoproject.com/ticket/36904#comment:6>