| 1 |
====================== |
| 2 |
The form rendering API |
| 3 |
====================== |
| 4 |
|
| 5 |
.. module:: django.forms.renderers |
| 6 |
:synopsis: Built-in form renderers. |
| 7 |
|
| 8 |
Django's form widgets are rendered using Django's :doc:`template engines |
| 9 |
system </topics/templates>`. |
| 10 |
|
| 11 |
The form rendering process can be customized at several levels: |
| 12 |
|
| 13 |
* Widgets can specify custom template names. |
| 14 |
* Forms and widgets can specify custom renderer classes. |
| 15 |
* A widget's template can be overridden by a project. (Reusable applications |
| 16 |
typically shouldn't override built-in templates because they might conflict |
| 17 |
with a project's custom templates.) |
| 18 |
|
| 19 |
.. _low-level-widget-render-api: |
| 20 |
|
| 21 |
The low-level render API |
| 22 |
======================== |
| 23 |
|
| 24 |
The rendering of form templates is controlled by a customizable renderer class. |
| 25 |
A custom renderer can be specified by updating the :setting:`FORM_RENDERER` |
| 26 |
setting. It defaults to |
| 27 |
``'``:class:`django.forms.renderers.DjangoTemplates`\ ``'``. |
| 28 |
|
| 29 |
By specifying a custom form renderer and overriding |
| 30 |
:attr:`~.BaseRenderer.form_template_name` you can adjust the default form |
| 31 |
markup across your project from a single place. |
| 32 |
|
| 33 |
You can also provide a custom renderer per-form or per-widget by setting the |
| 34 |
:attr:`.Form.default_renderer` attribute or by using the ``renderer`` argument |
| 35 |
of :meth:`.Form.render`, or :meth:`.Widget.render`. |
| 36 |
|
| 37 |
Matching points apply to formset rendering. See :ref:`formset-rendering` for |
| 38 |
discussion. |
| 39 |
|
| 40 |
Use one of the :ref:`built-in template form renderers |
| 41 |
<built-in-template-form-renderers>` or implement your own. Custom renderers |
| 42 |
must implement a ``render(template_name, context, request=None)`` method. It |
| 43 |
should return a rendered template (as a string) or raise |
| 44 |
:exc:`~django.template.TemplateDoesNotExist`. |
| 45 |
|
| 46 |
.. class:: BaseRenderer |
| 47 |
|
| 48 |
The base class for the built-in form renderers. |
| 49 |
|
| 50 |
.. attribute:: form_template_name |
| 51 |
|
| 52 |
The default name of the template to use to render a form. |
| 53 |
|
| 54 |
Defaults to ``"django/forms/div.html"`` template. |
| 55 |
|
| 56 |
.. attribute:: formset_template_name |
| 57 |
|
| 58 |
The default name of the template to use to render a formset. |
| 59 |
|
| 60 |
Defaults to ``"django/forms/formsets/div.html"`` template. |
| 61 |
|
| 62 |
.. attribute:: field_template_name |
| 63 |
|
| 64 |
The default name of the template used to render a ``BoundField``. |
| 65 |
|
| 66 |
Defaults to ``"django/forms/field.html"`` |
| 67 |
|
| 68 |
.. attribute:: bound_field_class |
| 69 |
|
| 70 |
.. versionadded:: 5.2 |
| 71 |
|
| 72 |
The default class used to represent form fields across the project. |
| 73 |
|
| 74 |
Defaults to :class:`.BoundField` class. |
| 75 |
|
| 76 |
This can be customized further using :attr:`.Form.bound_field_class` |
| 77 |
for per-form overrides, or :attr:`.Field.bound_field_class` for |
| 78 |
per-field overrides. |
| 79 |
|
| 80 |
.. method:: get_template(template_name) |
| 81 |
|
| 82 |
Subclasses must implement this method with the appropriate template |
| 83 |
finding logic. |
| 84 |
|
| 85 |
.. method:: render(template_name, context, request=None) |
| 86 |
|
| 87 |
Renders the given template, or raises |
| 88 |
:exc:`~django.template.TemplateDoesNotExist`. |
| 89 |
|
| 90 |
.. _built-in-template-form-renderers: |
| 91 |
|
| 92 |
Built-in-template form renderers |
| 93 |
================================ |
| 94 |
|
| 95 |
``DjangoTemplates`` |
| 96 |
------------------- |
| 97 |
|
| 98 |
.. class:: DjangoTemplates |
| 99 |
|
| 100 |
This renderer uses a standalone |
| 101 |
:class:`~django.template.backends.django.DjangoTemplates` |
| 102 |
engine (unconnected to what you might have configured in the |
| 103 |
:setting:`TEMPLATES` setting). It loads templates first from the built-in form |
| 104 |
templates directory in :source:`django/forms/templates` and then from the |
| 105 |
installed apps' templates directories using the :class:`app_directories |
| 106 |
<django.template.loaders.app_directories.Loader>` loader. |
| 107 |
|
| 108 |
If you want to render templates with customizations from your |
| 109 |
:setting:`TEMPLATES` setting, such as context processors for example, use the |
| 110 |
:class:`TemplatesSetting` renderer. |
| 111 |
|
| 112 |
.. class:: DjangoDivFormRenderer |
| 113 |
|
| 114 |
.. deprecated:: 5.0 |
| 115 |
|
| 116 |
The alias of :class:`DjangoTemplates`. |
| 117 |
|
| 118 |
``Jinja2`` |
| 119 |
---------- |
| 120 |
|
| 121 |
.. class:: Jinja2 |
| 122 |
|
| 123 |
This renderer is the same as the :class:`DjangoTemplates` renderer except that |
| 124 |
it uses a :class:`~django.template.backends.jinja2.Jinja2` backend. Templates |
| 125 |
for the built-in widgets are located in :source:`django/forms/jinja2` and |
| 126 |
installed apps can provide templates in a ``jinja2`` directory. |
| 127 |
|
| 128 |
To use this backend, all the forms and widgets in your project and its |
| 129 |
third-party apps must have Jinja2 templates. Unless you provide your own Jinja2 |
| 130 |
templates for widgets that don't have any, you can't use this renderer. For |
| 131 |
example, :mod:`django.contrib.admin` doesn't include Jinja2 templates for its |
| 132 |
widgets due to their usage of Django template tags. |
| 133 |
|
| 134 |
.. class:: Jinja2DivFormRenderer |
| 135 |
|
| 136 |
.. deprecated:: 5.0 |
| 137 |
|
| 138 |
The alias of :class:`Jinja2`. |
| 139 |
|
| 140 |
``TemplatesSetting`` |
| 141 |
-------------------- |
| 142 |
|
| 143 |
.. class:: TemplatesSetting |
| 144 |
|
| 145 |
This renderer gives you complete control of how form and widget templates are |
| 146 |
sourced. It uses :func:`~django.template.loader.get_template` to find templates |
| 147 |
based on what's configured in the :setting:`TEMPLATES` setting. |
| 148 |
|
| 149 |
Using this renderer along with the built-in templates requires either: |
| 150 |
|
| 151 |
* ``'django.forms'`` in :setting:`INSTALLED_APPS` and at least one engine |
| 152 |
with :setting:`APP_DIRS=True <TEMPLATES-APP_DIRS>`. |
| 153 |
|
| 154 |
* Adding the built-in templates directory in :setting:`DIRS <TEMPLATES-DIRS>` |
| 155 |
of one of your template engines. To generate that path:: |
| 156 |
|
| 157 |
import django |
| 158 |
|
| 159 |
django.__path__[0] + "/forms/templates" # or '/forms/jinja2' |
| 160 |
|
| 161 |
Using this renderer requires you to make sure the form templates your project |
| 162 |
needs can be located. |
| 163 |
|
| 164 |
Context available in formset templates |
| 165 |
====================================== |
| 166 |
|
| 167 |
Formset templates receive a context from :meth:`.BaseFormSet.get_context`. By |
| 168 |
default, formsets receive a dictionary with the following values: |
| 169 |
|
| 170 |
* ``formset``: The formset instance. |
| 171 |
|
| 172 |
Context available in form templates |
| 173 |
=================================== |
| 174 |
|
| 175 |
Form templates receive a context from :meth:`.Form.get_context`. By default, |
| 176 |
forms receive a dictionary with the following values: |
| 177 |
|
| 178 |
* ``form``: The bound form. |
| 179 |
* ``fields``: All bound fields, except the hidden fields. |
| 180 |
* ``hidden_fields``: All hidden bound fields. |
| 181 |
* ``errors``: All non field related or hidden field related form errors. |
| 182 |
|
| 183 |
Context available in field templates |
| 184 |
==================================== |
| 185 |
|
| 186 |
Field templates receive a context from :meth:`.BoundField.get_context`. By |
| 187 |
default, fields receive a dictionary with the following values: |
| 188 |
|
| 189 |
* ``field``: The :class:`~django.forms.BoundField`. |
| 190 |
|
| 191 |
Context available in widget templates |
| 192 |
===================================== |
| 193 |
|
| 194 |
Widget templates receive a context from :meth:`.Widget.get_context`. By |
| 195 |
default, widgets receive a single value in the context, ``widget``. This is a |
| 196 |
dictionary that contains values like: |
| 197 |
|
| 198 |
* ``name`` |
| 199 |
* ``value`` |
| 200 |
* ``attrs`` |
| 201 |
* ``is_hidden`` |
| 202 |
* ``template_name`` |
| 203 |
|
| 204 |
Some widgets add further information to the context. For instance, all widgets |
| 205 |
that subclass ``Input`` defines ``widget['type']`` and :class:`.MultiWidget` |
| 206 |
defines ``widget['subwidgets']`` for looping purposes. |
| 207 |
|
| 208 |
.. _overriding-built-in-formset-templates: |
| 209 |
|
| 210 |
Overriding built-in formset templates |
| 211 |
===================================== |
| 212 |
|
| 213 |
:attr:`.BaseFormSet.template_name` |
| 214 |
|
| 215 |
To override formset templates, you must use the :class:`TemplatesSetting` |
| 216 |
renderer. Then overriding formset templates works :doc:`the same as |
| 217 |
</howto/overriding-templates>` overriding any other template in your project. |
| 218 |
|
| 219 |
.. _overriding-built-in-form-templates: |
| 220 |
|
| 221 |
Overriding built-in form templates |
| 222 |
================================== |
| 223 |
|
| 224 |
:attr:`.Form.template_name` |
| 225 |
|
| 226 |
To override form templates, you must use the :class:`TemplatesSetting` |
| 227 |
renderer. Then overriding form templates works :doc:`the same as |
| 228 |
</howto/overriding-templates>` overriding any other template in your project. |
| 229 |
|
| 230 |
.. _overriding-built-in-field-templates: |
| 231 |
|
| 232 |
Overriding built-in field templates |
| 233 |
=================================== |
| 234 |
|
| 235 |
:attr:`.Field.template_name` |
| 236 |
|
| 237 |
To override field templates, you must use the :class:`TemplatesSetting` |
| 238 |
renderer. Then overriding field templates works :doc:`the same as |
| 239 |
</howto/overriding-templates>` overriding any other template in your project. |
| 240 |
|
| 241 |
.. _overriding-built-in-widget-templates: |
| 242 |
|
| 243 |
Overriding built-in widget templates |
| 244 |
==================================== |
| 245 |
|
| 246 |
Each widget has a ``template_name`` attribute with a value such as |
| 247 |
``input.html``. Built-in widget templates are stored in the |
| 248 |
``django/forms/widgets`` path. You can provide a custom template for |
| 249 |
``input.html`` by defining ``django/forms/widgets/input.html``, for example. |
| 250 |
See :ref:`built-in widgets` for the name of each widget's template. |
| 251 |
|
| 252 |
To override widget templates, you must use the :class:`TemplatesSetting` |
| 253 |
renderer. Then overriding widget templates works :doc:`the same as |
| 254 |
</howto/overriding-templates>` overriding any other template in your project. |