[Django] #36725: Add documentation for HTML form field equivalents to Django form fields

[Django]

#36725: Add documentation for HTML form field equivalents to Django form fields
-------------------------------------+-------------------------------------
Reporter: Quinn-beep | Type:
| Cleanup/optimization
Status: new | Component: Forms
Version: 5.2 | 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
-------------------------------------+-------------------------------------
Currently, Django’s documentation explains the mapping between model
fields and form fields, but it doesn’t provide a clear reference showing
how Django form fields correspond to standard HTML form elements.

To make the documentation more accessible to beginners and web developers
transitioning from raw HTML forms to Django forms, I propose adding a
section (or table) that lists Django form fields and their equivalent HTML
form field types.

This addition will help users quickly understand which Django field to use
when they are familiar with basic HTML input types.

The proposed documentation enhancement includes a table similar to the one
below:
| **Django Form Field** | **HTML Equivalent** | **Example HTML
Tag** |
| --------------------------------- | ------------------- |
--------------------------------------- |
| `CharField` | Text input | `<input
type="text">` |
| `EmailField` | Email input | `<input
type="email">` |
| `BooleanField` | Checkbox input | `<input
type="checkbox">` |
| `DateField` | Date input | `<input
type="date">` |
| `FileField` | File upload | `<input
type="file">` |
| `TextField` | Text area |
`<textarea></textarea>` |
| `ChoiceField` | Dropdown |
`<select><option>...</option></select>` |
| … *(and other relevant mappings)* | |
|
… (and other relevant mappings)

This addition would be placed in the Forms documentation (likely
docs/topics/forms/modelforms.txt) under a new section titled “HTML Form
Field Equivalents in Django.”
--
Ticket URL: <https://code.djangoproject.com/ticket/36725>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36725: Add documentation for HTML form field equivalents to Django form fields

-------------------------------+--------------------------------------
Reporter: Quinn-beep | Owner: (none)
Type: New feature | Status: closed
Component: Documentation | Version: 5.2
Severity: Normal | Resolution: wontfix

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 Jacob Walls):

* component: Forms => Documentation
* resolution: => wontfix
* status: new => closed
* type: Cleanup/optimization => New feature

Comment:

Thanks for the idea.

> Currently, Django’s documentation explains the mapping between model
fields and form fields, but it doesn’t provide a clear reference showing
how Django form fields correspond to standard HTML form elements.

I would qualify that statement by saying that the mapping from form fields
to HTML is described in a few places (e.g. "In most cases, the field will
have a sensible default widget.") -- and that the default widgets are
listed here, by field:

https://docs.djangoproject.com/en/5.2/ref/forms/fields/#built-in-field-
classes

In terms of discoverability, we already have a table like you describe
mapping model fields to form fields, so I take it that the issue we're
discussing is that it takes two clicks (one to get to the default widget
("Default widget: EmailInput"), and another to get to the default input
("Renders as: <input type="email" ...>"), making "reverse lookups"
tedious:

https://docs.djangoproject.com/en/5.2/topics/forms/modelforms/#field-types

Instead of creating a new table, it would be better to consider extending
that table with a third column for default widget, to save one of the two
clicks.

But then how to deal with complexity like this:

{{{
class DecimalField(**kwargs)
Default widget: NumberInput when Field.localize is False, else TextInput.
}}}

Then, I'm not sure how much value the reverse lookup provides. You can't
backsolve from a `<select>` to a `ChoiceField` to a model field (if it's
not a `ModelChoiceField`). And the reverse lookup is not so hard from the
existing two-column table. And it will get noisy, e.g. 8 fields have
"Default widget: TextInput".

I'm not opposed to something in principle here, I'm just not sure I can
judge feasibility without seeing a proof of concept. Marking `wontfix`
pending a proof of concept.
--
Ticket URL: <https://code.djangoproject.com/ticket/36725#comment:1>