Debian Codegraph @

docs/ref/forms/renderers.txt

raw
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.