1
0
mirror of https://github.com/django/django.git synced 2025-10-24 14:16:09 +00:00

Refs #32339 -- Restructured outputting HTML form docs.

In the topic doc, promoted the Reusable form templates section.

In the reference, re-grouped and promoted the default __str__()
rendering path, and then gathered the various as_*() helpers
subsequently.

Thanks to David Smith for review.
This commit is contained in:
Carlton Gibson
2022-05-03 16:07:01 +02:00
committed by Carlton Gibson
parent 5d91dc8ee3
commit fde946daff
2 changed files with 188 additions and 157 deletions

View File

@@ -487,15 +487,83 @@ instance into the template context. So if your form is called ``form`` in the
context, ``{{ form }}`` will render its ``<label>`` and ``<input>`` elements
appropriately.
Form rendering options
----------------------
.. admonition:: Additional form template furniture
Don't forget that a form's output does *not* include the surrounding
``<form>`` tags, or the form's ``submit`` control. You will have to provide
these yourself.
Reusable form templates
-----------------------
The HTML output when rendering a form is itself generated via a template. You
can control this by creating an appropriate template file and setting a custom
:setting:`FORM_RENDERER` to use that
:attr:`~django.forms.renderers.BaseRenderer.form_template_name` site-wide. You
can also customize per-form by overriding the form's
:attr:`~django.forms.Form.template_name` attribute to render the form using the
custom template, or by passing the template name directly to
:meth:`.Form.render`.
The example below will result in ``{{ form }}`` being rendered as the output of
the ``form_snippet.html`` template.
In your templates:
.. code-block:: html+django
# In your template:
{{ form }}
# In form_snippet.html:
{% for field in form %}
<div class="fieldWrapper">
{{ field.errors }}
{{ field.label_tag }} {{ field }}
</div>
{% endfor %}
Then you can configure the :setting:`FORM_RENDERER` setting:
.. code-block:: python
:caption: settings.py
from django.forms.renderers import TemplatesSetting
class CustomFormRenderer(TemplatesSetting):
form_template_name = "form_snippet.html"
FORM_RENDERER = "project.settings.CustomFormRenderer"
… or for a single form::
class MyForm(forms.Form):
template_name = "form_snippet.html"
...
… or for a single render of a form instance, passing in the template name to
the :meth:`.Form.render`. Here's an example of this being used in a view::
def index(request):
form = MyForm()
rendered_form = form.render("form_snippet.html")
context = {'form': rendered_form}
return render(request, 'index.html', context)
See :ref:`ref-forms-api-outputting-html` for more details.
.. versionchanged:: 4.0
Template rendering of forms was added.
.. versionchanged:: 4.1
The ability to set the default ``form_template_name`` on the form renderer
was added.
Form rendering options
----------------------
There are other output options though for the ``<label>``/``<input>`` pairs:
* ``{{ form.as_table }}`` will render them as table cells wrapped in ``<tr>``
@@ -754,71 +822,6 @@ error in a hidden field is a sign of form tampering, since normal form
interaction won't alter them. However, you could easily insert some error
displays for those form errors, as well.
Reusable form templates
-----------------------
If your site uses the same rendering logic for forms in multiple places, you
can reduce duplication by saving the form's loop in a standalone template and
setting a custom :setting:`FORM_RENDERER` to use that
:attr:`~django.forms.renderers.BaseRenderer.form_template_name` site-wide. You
can also customize per-form by overriding the form's
:attr:`~django.forms.Form.template_name` attribute to render the form using the
custom template.
The below example will result in ``{{ form }}`` being rendered as the output of
the ``form_snippet.html`` template.
In your templates:
.. code-block:: html+django
# In your template:
{{ form }}
# In form_snippet.html:
{% for field in form %}
<div class="fieldWrapper">
{{ field.errors }}
{{ field.label_tag }} {{ field }}
</div>
{% endfor %}
Then you can configure the :setting:`FORM_RENDERER` setting:
.. code-block:: python
:caption: settings.py
from django.forms.renderers import TemplatesSetting
class CustomFormRenderer(TemplatesSetting):
form_template_name = "form_snippet.html"
FORM_RENDERER = "project.settings.CustomFormRenderer"
… or for a single form::
class MyForm(forms.Form):
template_name = "form_snippet.html"
...
… or for a single render of a form instance, passing in the template name to
the :meth:`.Form.render()`. Here's an example of this being used in a view::
def index(request):
form = MyForm()
rendered_form = form.render("form_snippet.html")
context = {'form': rendered_form}
return render(request, 'index.html', context)
.. versionchanged:: 4.0
Template rendering of forms was added.
.. versionchanged:: 4.1
The ability to set the default ``form_template_name`` on the form renderer
was added.
Further topics
==============