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:
committed by
Carlton Gibson
parent
5d91dc8ee3
commit
fde946daff
@@ -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
|
||||
==============
|
||||
|
||||
|
||||
Reference in New Issue
Block a user