Debian Codegraph @

docs/ref/template-response.txt

raw
1 ===================================================
2 ``TemplateResponse`` and ``SimpleTemplateResponse``
3 ===================================================
4
5 .. module:: django.template.response
6 :synopsis: Classes dealing with lazy-rendered HTTP responses.
7
8 Standard :class:`~django.http.HttpResponse` objects are static structures.
9 They are provided with a block of pre-rendered content at time of
10 construction, and while that content can be modified, it isn't in a form that
11 makes it easy to perform modifications.
12
13 However, it can sometimes be beneficial to allow decorators or
14 middleware to modify a response *after* it has been constructed by the
15 view. For example, you may want to change the template that is used,
16 or put additional data into the context.
17
18 TemplateResponse provides a way to do just that. Unlike basic
19 :class:`~django.http.HttpResponse` objects, TemplateResponse objects retain
20 the details of the template and context that was provided by the view to
21 compute the response. The final output of the response is not computed until
22 it is needed, later in the response process.
23
24 ``SimpleTemplateResponse`` objects
25 ==================================
26
27 .. class:: SimpleTemplateResponse()
28
29 Attributes
30 ----------
31
32 .. attribute:: SimpleTemplateResponse.template_name
33
34 The name of the template to be rendered. Accepts a backend-dependent
35 template object (such as those returned by
36 :func:`~django.template.loader.get_template()`), the name of a template,
37 or a list of template names.
38
39 Example: ``['foo.html', 'path/to/bar.html']``
40
41 .. attribute:: SimpleTemplateResponse.context_data
42
43 The context data to be used when rendering the template. It must be a
44 :class:`dict`.
45
46 Example: ``{'foo': 123}``
47
48 .. attribute:: SimpleTemplateResponse.rendered_content
49
50 The current rendered value of the response content, using the current
51 template and context data.
52
53 .. attribute:: SimpleTemplateResponse.is_rendered
54
55 A boolean indicating whether the response content has been rendered.
56
57 Methods
58 -------
59
60 .. method:: SimpleTemplateResponse.__init__(template, context=None, content_type=None, status=None, charset=None, using=None, headers=None)
61
62 Instantiates a :class:`~django.template.response.SimpleTemplateResponse`
63 object with the given template, context, content type, HTTP status, and
64 charset.
65
66 ``template``
67 A backend-dependent template object (such as those returned by
68 :func:`~django.template.loader.get_template()`), the name of a template,
69 or a list of template names.
70
71 ``context``
72 A :class:`dict` of values to add to the template context. By default,
73 this is an empty dictionary.
74
75 ``content_type``
76 The value included in the HTTP ``Content-Type`` header, including the
77 MIME type specification and the character set encoding. If
78 ``content_type`` is specified, then its value is used. Otherwise,
79 ``'text/html'`` is used.
80
81 ``status``
82 The HTTP status code for the response.
83
84 ``charset``
85 The charset in which the response will be encoded. If not given it will
86 be extracted from ``content_type``, and if that is unsuccessful, the
87 :setting:`DEFAULT_CHARSET` setting will be used.
88
89 ``using``
90 The :setting:`NAME <TEMPLATES-NAME>` of a template engine to use for
91 loading the template.
92
93 ``headers``
94 A :class:`dict` of HTTP headers to add to the response.
95
96 .. method:: SimpleTemplateResponse.resolve_context(context)
97
98 Preprocesses context data that will be used for rendering a template.
99 Accepts a :class:`dict` of context data. By default, returns the same
100 :class:`dict`.
101
102 Override this method in order to customize the context.
103
104 .. method:: SimpleTemplateResponse.resolve_template(template)
105
106 Resolves the template instance to use for rendering. Accepts a
107 backend-dependent template object (such as those returned by
108 :func:`~django.template.loader.get_template()`), the name of a template,
109 or a list of template names.
110
111 Returns the backend-dependent template object instance to be rendered.
112
113 Override this method in order to customize template loading.
114
115 .. method:: SimpleTemplateResponse.add_post_render_callback()
116
117 Add a callback that will be invoked after rendering has taken
118 place. This hook can be used to defer certain processing
119 operations (such as caching) until after rendering has occurred.
120
121 If the :class:`~django.template.response.SimpleTemplateResponse`
122 has already been rendered, the callback will be invoked
123 immediately.
124
125 When called, callbacks will be passed a single argument -- the
126 rendered :class:`~django.template.response.SimpleTemplateResponse`
127 instance.
128
129 If the callback returns a value that is not ``None``, this will be
130 used as the response instead of the original response object (and
131 will be passed to the next post rendering callback etc.)
132
133 .. method:: SimpleTemplateResponse.render()
134
135 Sets ``response.content`` to the result obtained by
136 :attr:`SimpleTemplateResponse.rendered_content`, runs all post-rendering
137 callbacks, and returns the resulting response object.
138
139 ``render()`` will only have an effect the first time it is called. On
140 subsequent calls, it will return the result obtained from the first call.
141
142
143 ``TemplateResponse`` objects
144 ============================
145
146 .. class:: TemplateResponse()
147
148 ``TemplateResponse`` is a subclass of
149 :class:`~django.template.response.SimpleTemplateResponse` that knows about
150 the current :class:`~django.http.HttpRequest`.
151
152 Methods
153 -------
154
155 .. method:: TemplateResponse.__init__(request, template, context=None, content_type=None, status=None, charset=None, using=None, headers=None)
156
157 Instantiates a :class:`~django.template.response.TemplateResponse` object
158 with the given request, template, context, content type, HTTP status, and
159 charset.
160
161 ``request``
162 An :class:`~django.http.HttpRequest` instance.
163
164 ``template``
165 A backend-dependent template object (such as those returned by
166 :func:`~django.template.loader.get_template()`), the name of a template,
167 or a list of template names.
168
169 ``context``
170 A :class:`dict` of values to add to the template context. By default,
171 this is an empty dictionary.
172
173 ``content_type``
174 The value included in the HTTP ``Content-Type`` header, including the
175 MIME type specification and the character set encoding. If
176 ``content_type`` is specified, then its value is used. Otherwise,
177 ``'text/html'`` is used.
178
179 ``status``
180 The HTTP status code for the response.
181
182 ``charset``
183 The charset in which the response will be encoded. If not given it will
184 be extracted from ``content_type``, and if that is unsuccessful, the
185 :setting:`DEFAULT_CHARSET` setting will be used.
186
187 ``using``
188 The :setting:`NAME <TEMPLATES-NAME>` of a template engine to use for
189 loading the template.
190
191 ``headers``
192 A :class:`dict` of HTTP headers to add to the response.
193
194 The rendering process
195 =====================
196
197 Before a :class:`~django.template.response.TemplateResponse` instance can be
198 returned to the client, it must be rendered. The rendering process takes the
199 intermediate representation of template and context, and turns it into the
200 final byte stream that can be served to the client.
201
202 There are three circumstances under which a ``TemplateResponse`` will be
203 rendered:
204
205 * When the ``TemplateResponse`` instance is explicitly rendered, using
206 the :meth:`SimpleTemplateResponse.render()` method.
207
208 * When the content of the response is explicitly set by assigning
209 ``response.content``.
210
211 * After passing through template response middleware, but before
212 passing through response middleware.
213
214 A ``TemplateResponse`` can only be rendered once. The first call to
215 :meth:`SimpleTemplateResponse.render` sets the content of the response;
216 subsequent rendering calls do not change the response content.
217
218 However, when ``response.content`` is explicitly assigned, the
219 change is always applied. If you want to force the content to be
220 re-rendered, you can reevaluate the rendered content, and assign
221 the content of the response manually:
222
223 .. code-block:: pycon
224
225 # Set up a rendered TemplateResponse
226 >>> from django.template.response import TemplateResponse
227 >>> t = TemplateResponse(request, "original.html", {})
228 >>> t.render()
229 >>> print(t.content)
230 Original content
231
232 # Re-rendering doesn't change content
233 >>> t.template_name = "new.html"
234 >>> t.render()
235 >>> print(t.content)
236 Original content
237
238 # Assigning content does change, no render() call required
239 >>> t.content = t.rendered_content
240 >>> print(t.content)
241 New content
242
243 Post-render callbacks
244 ---------------------
245
246 Some operations -- such as caching -- cannot be performed on an
247 unrendered template. They must be performed on a fully complete and
248 rendered response.
249
250 If you're using middleware, you can do that. Middleware provides
251 multiple opportunities to process a response on exit from a view. If
252 you put behavior in the response middleware, it's guaranteed to execute
253 after template rendering has taken place.
254
255 However, if you're using a decorator, the same opportunities do not
256 exist. Any behavior defined in a decorator is handled immediately.
257
258 To compensate for this (and any other analogous use cases),
259 :class:`TemplateResponse` allows you to register callbacks that will
260 be invoked when rendering has completed. Using this callback, you can
261 defer critical processing until a point where you can guarantee that
262 rendered content will be available.
263
264 To define a post-render callback, define a function that takes
265 a single argument -- response -- and register that function with
266 the template response::
267
268 from django.template.response import TemplateResponse
269
270
271 def my_render_callback(response):
272 # Do content-sensitive processing
273 do_post_processing()
274
275
276 def my_view(request):
277 # Create a response
278 response = TemplateResponse(request, "mytemplate.html", {})
279 # Register the callback
280 response.add_post_render_callback(my_render_callback)
281 # Return the response
282 return response
283
284 ``my_render_callback()`` will be invoked after the ``mytemplate.html``
285 has been rendered, and will be provided the fully rendered
286 :class:`TemplateResponse` instance as an argument.
287
288 If the template has already been rendered, the callback will be
289 invoked immediately.
290
291 Using ``TemplateResponse`` and ``SimpleTemplateResponse``
292 =========================================================
293
294 A :class:`TemplateResponse` object can be used anywhere that a normal
295 :class:`django.http.HttpResponse` can be used. It can also be used as an
296 alternative to calling :func:`~django.shortcuts.render()`.
297
298 For example, the following view returns a :class:`TemplateResponse` with a
299 template and a context containing a queryset::
300
301 from django.template.response import TemplateResponse
302
303
304 def blog_index(request):
305 return TemplateResponse(
306 request, "entry_list.html", {"entries": Entry.objects.all()}
307 )