|
1 ============= |
|
2 Generic views |
|
3 ============= |
|
4 |
|
5 Writing Web applications can be monotonous, because we repeat certain patterns |
|
6 again and again. In Django, the most common of these patterns have been |
|
7 abstracted into "generic views" that let you quickly provide common views of |
|
8 an object without actually needing to write any Python code. |
|
9 |
|
10 A general introduction to generic views can be found in the :doc:`topic guide |
|
11 </topics/http/generic-views>`. |
|
12 |
|
13 This reference contains details of Django's built-in generic views, along with |
|
14 a list of all keyword arguments that a generic view expects. Remember that |
|
15 arguments may either come from the URL pattern or from the ``extra_context`` |
|
16 additional-information dictionary. |
|
17 |
|
18 Most generic views require the ``queryset`` key, which is a ``QuerySet`` |
|
19 instance; see :doc:`/topics/db/queries` for more information about ``QuerySet`` |
|
20 objects. |
|
21 |
|
22 "Simple" generic views |
|
23 ====================== |
|
24 |
|
25 The ``django.views.generic.simple`` module contains simple views to handle a |
|
26 couple of common cases: rendering a template when no view logic is needed, |
|
27 and issuing a redirect. |
|
28 |
|
29 ``django.views.generic.simple.direct_to_template`` |
|
30 -------------------------------------------------- |
|
31 |
|
32 **Description:** |
|
33 |
|
34 Renders a given template, passing it a ``{{ params }}`` template variable, |
|
35 which is a dictionary of the parameters captured in the URL. |
|
36 |
|
37 **Required arguments:** |
|
38 |
|
39 * ``template``: The full name of a template to use. |
|
40 |
|
41 **Optional arguments:** |
|
42 |
|
43 * ``extra_context``: A dictionary of values to add to the template |
|
44 context. By default, this is an empty dictionary. If a value in the |
|
45 dictionary is callable, the generic view will call it |
|
46 just before rendering the template. |
|
47 |
|
48 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
49 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
50 |
|
51 **Example:** |
|
52 |
|
53 Given the following URL patterns:: |
|
54 |
|
55 urlpatterns = patterns('django.views.generic.simple', |
|
56 (r'^foo/$', 'direct_to_template', {'template': 'foo_index.html'}), |
|
57 (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}), |
|
58 ) |
|
59 |
|
60 ... a request to ``/foo/`` would render the template ``foo_index.html``, and a |
|
61 request to ``/foo/15/`` would render the ``foo_detail.html`` with a context |
|
62 variable ``{{ params.id }}`` that is set to ``15``. |
|
63 |
|
64 ``django.views.generic.simple.redirect_to`` |
|
65 ------------------------------------------- |
|
66 |
|
67 **Description:** |
|
68 |
|
69 Redirects to a given URL. |
|
70 |
|
71 The given URL may contain dictionary-style string formatting, which will be |
|
72 interpolated against the parameters captured in the URL. Because keyword |
|
73 interpolation is *always* done (even if no arguments are passed in), any ``"%"`` |
|
74 characters in the URL must be written as ``"%%"`` so that Python will convert |
|
75 them to a single percent sign on output. |
|
76 |
|
77 If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). |
|
78 |
|
79 **Required arguments:** |
|
80 |
|
81 * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410 |
|
82 (Gone) HTTP error. |
|
83 |
|
84 **Optional arguments:** |
|
85 |
|
86 * ``permanent``: Whether the redirect should be permanent. The only |
|
87 difference here is the HTTP status code returned. If ``True``, then the |
|
88 redirect will use status code 301. If ``False``, then the redirect will |
|
89 use status code 302. By default, ``permanent`` is ``True``. |
|
90 |
|
91 .. versionadded:: 1.1 |
|
92 The ``permanent`` keyword argument is new in Django 1.1. |
|
93 |
|
94 **Example:** |
|
95 |
|
96 This example issues a permanent redirect (HTTP status code 301) from |
|
97 ``/foo/<id>/`` to ``/bar/<id>/``:: |
|
98 |
|
99 urlpatterns = patterns('django.views.generic.simple', |
|
100 ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}), |
|
101 ) |
|
102 |
|
103 This example issues a non-permanent redirect (HTTP status code 302) from |
|
104 ``/foo/<id>/`` to ``/bar/<id>/``:: |
|
105 |
|
106 urlpatterns = patterns('django.views.generic.simple', |
|
107 ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/', 'permanent': False}), |
|
108 ) |
|
109 |
|
110 This example returns a 410 HTTP error for requests to ``/bar/``:: |
|
111 |
|
112 urlpatterns = patterns('django.views.generic.simple', |
|
113 ('^bar/$', 'redirect_to', {'url': None}), |
|
114 ) |
|
115 |
|
116 This example shows how ``"%"`` characters must be written in the URL in order |
|
117 to avoid confusion with Python's string formatting markers. If the redirect |
|
118 string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised:: |
|
119 |
|
120 urlpatterns = patterns('django.views.generic.simple', |
|
121 ('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}), |
|
122 ) |
|
123 |
|
124 Date-based generic views |
|
125 ======================== |
|
126 |
|
127 Date-based generic views (in the module ``django.views.generic.date_based``) |
|
128 are views for displaying drilldown pages for date-based data. |
|
129 |
|
130 ``django.views.generic.date_based.archive_index`` |
|
131 ------------------------------------------------- |
|
132 |
|
133 **Description:** |
|
134 |
|
135 A top-level index page showing the "latest" objects, by date. Objects with |
|
136 a date in the *future* are not included unless you set ``allow_future`` to |
|
137 ``True``. |
|
138 |
|
139 **Required arguments:** |
|
140 |
|
141 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
|
142 |
|
143 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
|
144 the ``QuerySet``'s model that the date-based archive should use to |
|
145 determine the objects on the page. |
|
146 |
|
147 **Optional arguments:** |
|
148 |
|
149 * ``num_latest``: The number of latest objects to send to the template |
|
150 context. By default, it's 15. |
|
151 |
|
152 * ``template_name``: The full name of a template to use in rendering the |
|
153 page. This lets you override the default template name (see below). |
|
154 |
|
155 * ``template_loader``: The template loader to use when loading the |
|
156 template. By default, it's ``django.template.loader``. |
|
157 |
|
158 * ``extra_context``: A dictionary of values to add to the template |
|
159 context. By default, this is an empty dictionary. If a value in the |
|
160 dictionary is callable, the generic view will call it |
|
161 just before rendering the template. |
|
162 |
|
163 * ``allow_empty``: A boolean specifying whether to display the page if no |
|
164 objects are available. If this is ``False`` and no objects are available, |
|
165 the view will raise a 404 instead of displaying an empty page. By |
|
166 default, this is ``True``. |
|
167 |
|
168 * ``context_processors``: A list of template-context processors to apply to |
|
169 the view's template. |
|
170 |
|
171 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
172 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
173 |
|
174 * ``allow_future``: A boolean specifying whether to include "future" |
|
175 objects on this page, where "future" means objects in which the field |
|
176 specified in ``date_field`` is greater than the current date/time. By |
|
177 default, this is ``False``. |
|
178 |
|
179 .. versionadded:: 1.0 |
|
180 |
|
181 * ``template_object_name``: Designates the name of the template variable |
|
182 to use in the template context. By default, this is ``'latest'``. |
|
183 |
|
184 **Template name:** |
|
185 |
|
186 If ``template_name`` isn't specified, this view will use the template |
|
187 ``<app_label>/<model_name>_archive.html`` by default, where: |
|
188 |
|
189 * ``<model_name>`` is your model's name in all lowercase. For a model |
|
190 ``StaffMember``, that'd be ``staffmember``. |
|
191 |
|
192 * ``<app_label>`` is the right-most part of the full Python path to |
|
193 your model's app. For example, if your model lives in |
|
194 ``apps/blog/models.py``, that'd be ``blog``. |
|
195 |
|
196 **Template context:** |
|
197 |
|
198 In addition to ``extra_context``, the template's context will be: |
|
199 |
|
200 * ``date_list``: A ``DateQuerySet`` object containing all years that have |
|
201 have objects available according to ``queryset``, represented as |
|
202 ``datetime.datetime`` objects. These are ordered in reverse. This is |
|
203 equivalent to ``queryset.dates(date_field, 'year')[::-1]``. |
|
204 |
|
205 .. versionchanged:: 1.0 |
|
206 The behaviour depending on ``template_object_name`` is new in this version. |
|
207 |
|
208 * ``latest``: The ``num_latest`` objects in the system, ordered descending |
|
209 by ``date_field``. For example, if ``num_latest`` is ``10``, then |
|
210 ``latest`` will be a list of the latest 10 objects in ``queryset``. |
|
211 |
|
212 This variable's name depends on the ``template_object_name`` parameter, |
|
213 which is ``'latest'`` by default. If ``template_object_name`` is |
|
214 ``'foo'``, this variable's name will be ``foo``. |
|
215 |
|
216 ``django.views.generic.date_based.archive_year`` |
|
217 ------------------------------------------------ |
|
218 |
|
219 **Description:** |
|
220 |
|
221 A yearly archive page showing all available months in a given year. Objects |
|
222 with a date in the *future* are not displayed unless you set ``allow_future`` |
|
223 to ``True``. |
|
224 |
|
225 **Required arguments:** |
|
226 |
|
227 * ``year``: The four-digit year for which the archive serves. |
|
228 |
|
229 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
|
230 |
|
231 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
|
232 the ``QuerySet``'s model that the date-based archive should use to |
|
233 determine the objects on the page. |
|
234 |
|
235 **Optional arguments:** |
|
236 |
|
237 * ``template_name``: The full name of a template to use in rendering the |
|
238 page. This lets you override the default template name (see below). |
|
239 |
|
240 * ``template_loader``: The template loader to use when loading the |
|
241 template. By default, it's ``django.template.loader``. |
|
242 |
|
243 * ``extra_context``: A dictionary of values to add to the template |
|
244 context. By default, this is an empty dictionary. If a value in the |
|
245 dictionary is callable, the generic view will call it |
|
246 just before rendering the template. |
|
247 |
|
248 * ``allow_empty``: A boolean specifying whether to display the page if no |
|
249 objects are available. If this is ``False`` and no objects are available, |
|
250 the view will raise a 404 instead of displaying an empty page. By |
|
251 default, this is ``False``. |
|
252 |
|
253 * ``context_processors``: A list of template-context processors to apply to |
|
254 the view's template. |
|
255 |
|
256 * ``template_object_name``: Designates the name of the template variable |
|
257 to use in the template context. By default, this is ``'object'``. The |
|
258 view will append ``'_list'`` to the value of this parameter in |
|
259 determining the variable's name. |
|
260 |
|
261 * ``make_object_list``: A boolean specifying whether to retrieve the full |
|
262 list of objects for this year and pass those to the template. If ``True``, |
|
263 this list of objects will be made available to the template as |
|
264 ``object_list``. (The name ``object_list`` may be different; see the docs |
|
265 for ``object_list`` in the "Template context" section below.) By default, |
|
266 this is ``False``. |
|
267 |
|
268 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
269 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
270 |
|
271 * ``allow_future``: A boolean specifying whether to include "future" |
|
272 objects on this page, where "future" means objects in which the field |
|
273 specified in ``date_field`` is greater than the current date/time. By |
|
274 default, this is ``False``. |
|
275 |
|
276 **Template name:** |
|
277 |
|
278 If ``template_name`` isn't specified, this view will use the template |
|
279 ``<app_label>/<model_name>_archive_year.html`` by default. |
|
280 |
|
281 **Template context:** |
|
282 |
|
283 In addition to ``extra_context``, the template's context will be: |
|
284 |
|
285 * ``date_list``: A ``DateQuerySet`` object containing all months that have |
|
286 have objects available according to ``queryset``, represented as |
|
287 ``datetime.datetime`` objects, in ascending order. |
|
288 |
|
289 * ``year``: The given year, as a four-character string. |
|
290 |
|
291 * ``object_list``: If the ``make_object_list`` parameter is ``True``, this |
|
292 will be set to a list of objects available for the given year, ordered by |
|
293 the date field. This variable's name depends on the |
|
294 ``template_object_name`` parameter, which is ``'object'`` by default. If |
|
295 ``template_object_name`` is ``'foo'``, this variable's name will be |
|
296 ``foo_list``. |
|
297 |
|
298 If ``make_object_list`` is ``False``, ``object_list`` will be passed to |
|
299 the template as an empty list. |
|
300 |
|
301 ``django.views.generic.date_based.archive_month`` |
|
302 ------------------------------------------------- |
|
303 |
|
304 **Description:** |
|
305 |
|
306 A monthly archive page showing all objects in a given month. Objects with a |
|
307 date in the *future* are not displayed unless you set ``allow_future`` to |
|
308 ``True``. |
|
309 |
|
310 **Required arguments:** |
|
311 |
|
312 * ``year``: The four-digit year for which the archive serves (a string). |
|
313 |
|
314 * ``month``: The month for which the archive serves, formatted according to |
|
315 the ``month_format`` argument. |
|
316 |
|
317 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
|
318 |
|
319 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
|
320 the ``QuerySet``'s model that the date-based archive should use to |
|
321 determine the objects on the page. |
|
322 |
|
323 **Optional arguments:** |
|
324 |
|
325 * ``month_format``: A format string that regulates what format the |
|
326 ``month`` parameter uses. This should be in the syntax accepted by |
|
327 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to |
|
328 ``"%b"`` by default, which is a three-letter month abbreviation. To |
|
329 change it to use numbers, use ``"%m"``. |
|
330 |
|
331 * ``template_name``: The full name of a template to use in rendering the |
|
332 page. This lets you override the default template name (see below). |
|
333 |
|
334 * ``template_loader``: The template loader to use when loading the |
|
335 template. By default, it's ``django.template.loader``. |
|
336 |
|
337 * ``extra_context``: A dictionary of values to add to the template |
|
338 context. By default, this is an empty dictionary. If a value in the |
|
339 dictionary is callable, the generic view will call it |
|
340 just before rendering the template. |
|
341 |
|
342 * ``allow_empty``: A boolean specifying whether to display the page if no |
|
343 objects are available. If this is ``False`` and no objects are available, |
|
344 the view will raise a 404 instead of displaying an empty page. By |
|
345 default, this is ``False``. |
|
346 |
|
347 * ``context_processors``: A list of template-context processors to apply to |
|
348 the view's template. |
|
349 |
|
350 * ``template_object_name``: Designates the name of the template variable |
|
351 to use in the template context. By default, this is ``'object'``. The |
|
352 view will append ``'_list'`` to the value of this parameter in |
|
353 determining the variable's name. |
|
354 |
|
355 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
356 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
357 |
|
358 * ``allow_future``: A boolean specifying whether to include "future" |
|
359 objects on this page, where "future" means objects in which the field |
|
360 specified in ``date_field`` is greater than the current date/time. By |
|
361 default, this is ``False``. |
|
362 |
|
363 **Template name:** |
|
364 |
|
365 If ``template_name`` isn't specified, this view will use the template |
|
366 ``<app_label>/<model_name>_archive_month.html`` by default. |
|
367 |
|
368 **Template context:** |
|
369 |
|
370 .. versionadded:: 1.2 |
|
371 The inclusion of ``date_list`` in the template's context is new. |
|
372 |
|
373 In addition to ``extra_context``, the template's context will be: |
|
374 |
|
375 * ``date_list``: A ``DateQuerySet`` object containing all days that have |
|
376 have objects available in the given month, according to ``queryset``, |
|
377 represented as ``datetime.datetime`` objects, in ascending order. |
|
378 |
|
379 * ``month``: A ``datetime.date`` object representing the given month. |
|
380 |
|
381 * ``next_month``: A ``datetime.date`` object representing the first day of |
|
382 the next month. If the next month is in the future, this will be |
|
383 ``None``. |
|
384 |
|
385 * ``previous_month``: A ``datetime.date`` object representing the first day |
|
386 of the previous month. Unlike ``next_month``, this will never be |
|
387 ``None``. |
|
388 |
|
389 * ``object_list``: A list of objects available for the given month. This |
|
390 variable's name depends on the ``template_object_name`` parameter, which |
|
391 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
|
392 this variable's name will be ``foo_list``. |
|
393 |
|
394 .. _strftime docs: http://docs.python.org/library/time.html#time.strftime |
|
395 |
|
396 ``django.views.generic.date_based.archive_week`` |
|
397 ------------------------------------------------ |
|
398 |
|
399 **Description:** |
|
400 |
|
401 A weekly archive page showing all objects in a given week. Objects with a date |
|
402 in the *future* are not displayed unless you set ``allow_future`` to ``True``. |
|
403 |
|
404 **Required arguments:** |
|
405 |
|
406 * ``year``: The four-digit year for which the archive serves (a string). |
|
407 |
|
408 * ``week``: The week of the year for which the archive serves (a string). |
|
409 Weeks start with Sunday. |
|
410 |
|
411 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
|
412 |
|
413 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
|
414 the ``QuerySet``'s model that the date-based archive should use to |
|
415 determine the objects on the page. |
|
416 |
|
417 **Optional arguments:** |
|
418 |
|
419 * ``template_name``: The full name of a template to use in rendering the |
|
420 page. This lets you override the default template name (see below). |
|
421 |
|
422 * ``template_loader``: The template loader to use when loading the |
|
423 template. By default, it's ``django.template.loader``. |
|
424 |
|
425 * ``extra_context``: A dictionary of values to add to the template |
|
426 context. By default, this is an empty dictionary. If a value in the |
|
427 dictionary is callable, the generic view will call it |
|
428 just before rendering the template. |
|
429 |
|
430 * ``allow_empty``: A boolean specifying whether to display the page if no |
|
431 objects are available. If this is ``False`` and no objects are available, |
|
432 the view will raise a 404 instead of displaying an empty page. By |
|
433 default, this is ``True``. |
|
434 |
|
435 * ``context_processors``: A list of template-context processors to apply to |
|
436 the view's template. |
|
437 |
|
438 * ``template_object_name``: Designates the name of the template variable |
|
439 to use in the template context. By default, this is ``'object'``. The |
|
440 view will append ``'_list'`` to the value of this parameter in |
|
441 determining the variable's name. |
|
442 |
|
443 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
444 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
445 |
|
446 * ``allow_future``: A boolean specifying whether to include "future" |
|
447 objects on this page, where "future" means objects in which the field |
|
448 specified in ``date_field`` is greater than the current date/time. By |
|
449 default, this is ``False``. |
|
450 |
|
451 **Template name:** |
|
452 |
|
453 If ``template_name`` isn't specified, this view will use the template |
|
454 ``<app_label>/<model_name>_archive_week.html`` by default. |
|
455 |
|
456 **Template context:** |
|
457 |
|
458 In addition to ``extra_context``, the template's context will be: |
|
459 |
|
460 * ``week``: A ``datetime.date`` object representing the first day of the |
|
461 given week. |
|
462 |
|
463 * ``object_list``: A list of objects available for the given week. This |
|
464 variable's name depends on the ``template_object_name`` parameter, which |
|
465 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
|
466 this variable's name will be ``foo_list``. |
|
467 |
|
468 ``django.views.generic.date_based.archive_day`` |
|
469 ----------------------------------------------- |
|
470 |
|
471 **Description:** |
|
472 |
|
473 A day archive page showing all objects in a given day. Days in the future throw |
|
474 a 404 error, regardless of whether any objects exist for future days, unless |
|
475 you set ``allow_future`` to ``True``. |
|
476 |
|
477 **Required arguments:** |
|
478 |
|
479 * ``year``: The four-digit year for which the archive serves (a string). |
|
480 |
|
481 * ``month``: The month for which the archive serves, formatted according to |
|
482 the ``month_format`` argument. |
|
483 |
|
484 * ``day``: The day for which the archive serves, formatted according to the |
|
485 ``day_format`` argument. |
|
486 |
|
487 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
|
488 |
|
489 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
|
490 the ``QuerySet``'s model that the date-based archive should use to |
|
491 determine the objects on the page. |
|
492 |
|
493 **Optional arguments:** |
|
494 |
|
495 * ``month_format``: A format string that regulates what format the |
|
496 ``month`` parameter uses. This should be in the syntax accepted by |
|
497 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to |
|
498 ``"%b"`` by default, which is a three-letter month abbreviation. To |
|
499 change it to use numbers, use ``"%m"``. |
|
500 |
|
501 * ``day_format``: Like ``month_format``, but for the ``day`` parameter. |
|
502 It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). |
|
503 |
|
504 * ``template_name``: The full name of a template to use in rendering the |
|
505 page. This lets you override the default template name (see below). |
|
506 |
|
507 * ``template_loader``: The template loader to use when loading the |
|
508 template. By default, it's ``django.template.loader``. |
|
509 |
|
510 * ``extra_context``: A dictionary of values to add to the template |
|
511 context. By default, this is an empty dictionary. If a value in the |
|
512 dictionary is callable, the generic view will call it |
|
513 just before rendering the template. |
|
514 |
|
515 * ``allow_empty``: A boolean specifying whether to display the page if no |
|
516 objects are available. If this is ``False`` and no objects are available, |
|
517 the view will raise a 404 instead of displaying an empty page. By |
|
518 default, this is ``False``. |
|
519 |
|
520 * ``context_processors``: A list of template-context processors to apply to |
|
521 the view's template. |
|
522 |
|
523 * ``template_object_name``: Designates the name of the template variable |
|
524 to use in the template context. By default, this is ``'object'``. The |
|
525 view will append ``'_list'`` to the value of this parameter in |
|
526 determining the variable's name. |
|
527 |
|
528 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
529 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
530 |
|
531 * ``allow_future``: A boolean specifying whether to include "future" |
|
532 objects on this page, where "future" means objects in which the field |
|
533 specified in ``date_field`` is greater than the current date/time. By |
|
534 default, this is ``False``. |
|
535 |
|
536 **Template name:** |
|
537 |
|
538 If ``template_name`` isn't specified, this view will use the template |
|
539 ``<app_label>/<model_name>_archive_day.html`` by default. |
|
540 |
|
541 **Template context:** |
|
542 |
|
543 In addition to ``extra_context``, the template's context will be: |
|
544 |
|
545 * ``day``: A ``datetime.date`` object representing the given day. |
|
546 |
|
547 * ``next_day``: A ``datetime.date`` object representing the next day. If |
|
548 the next day is in the future, this will be ``None``. |
|
549 |
|
550 * ``previous_day``: A ``datetime.date`` object representing the previous day. |
|
551 Unlike ``next_day``, this will never be ``None``. |
|
552 |
|
553 * ``object_list``: A list of objects available for the given day. This |
|
554 variable's name depends on the ``template_object_name`` parameter, which |
|
555 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
|
556 this variable's name will be ``foo_list``. |
|
557 |
|
558 ``django.views.generic.date_based.archive_today`` |
|
559 ------------------------------------------------- |
|
560 |
|
561 **Description:** |
|
562 |
|
563 A day archive page showing all objects for *today*. This is exactly the same as |
|
564 ``archive_day``, except the ``year``/``month``/``day`` arguments are not used, |
|
565 and today's date is used instead. |
|
566 |
|
567 ``django.views.generic.date_based.object_detail`` |
|
568 ------------------------------------------------- |
|
569 |
|
570 **Description:** |
|
571 |
|
572 A page representing an individual object. If the object has a date value in the |
|
573 future, the view will throw a 404 error by default, unless you set |
|
574 ``allow_future`` to ``True``. |
|
575 |
|
576 **Required arguments:** |
|
577 |
|
578 * ``year``: The object's four-digit year (a string). |
|
579 |
|
580 * ``month``: The object's month , formatted according to the |
|
581 ``month_format`` argument. |
|
582 |
|
583 * ``day``: The object's day , formatted according to the ``day_format`` |
|
584 argument. |
|
585 |
|
586 * ``queryset``: A ``QuerySet`` that contains the object. |
|
587 |
|
588 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
|
589 the ``QuerySet``'s model that the generic view should use to look up the |
|
590 object according to ``year``, ``month`` and ``day``. |
|
591 |
|
592 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
|
593 |
|
594 If you provide ``object_id``, it should be the value of the primary-key |
|
595 field for the object being displayed on this page. |
|
596 |
|
597 Otherwise, ``slug`` should be the slug of the given object, and |
|
598 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
|
599 model. By default, ``slug_field`` is ``'slug'``. |
|
600 |
|
601 **Optional arguments:** |
|
602 |
|
603 * ``month_format``: A format string that regulates what format the |
|
604 ``month`` parameter uses. This should be in the syntax accepted by |
|
605 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to |
|
606 ``"%b"`` by default, which is a three-letter month abbreviation. To |
|
607 change it to use numbers, use ``"%m"``. |
|
608 |
|
609 * ``day_format``: Like ``month_format``, but for the ``day`` parameter. |
|
610 It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). |
|
611 |
|
612 * ``template_name``: The full name of a template to use in rendering the |
|
613 page. This lets you override the default template name (see below). |
|
614 |
|
615 * ``template_name_field``: The name of a field on the object whose value is |
|
616 the template name to use. This lets you store template names in the data. |
|
617 In other words, if your object has a field ``'the_template'`` that |
|
618 contains a string ``'foo.html'``, and you set ``template_name_field`` to |
|
619 ``'the_template'``, then the generic view for this object will use the |
|
620 template ``'foo.html'``. |
|
621 |
|
622 It's a bit of a brain-bender, but it's useful in some cases. |
|
623 |
|
624 * ``template_loader``: The template loader to use when loading the |
|
625 template. By default, it's ``django.template.loader``. |
|
626 |
|
627 * ``extra_context``: A dictionary of values to add to the template |
|
628 context. By default, this is an empty dictionary. If a value in the |
|
629 dictionary is callable, the generic view will call it |
|
630 just before rendering the template. |
|
631 |
|
632 * ``context_processors``: A list of template-context processors to apply to |
|
633 the view's template. |
|
634 |
|
635 * ``template_object_name``: Designates the name of the template variable |
|
636 to use in the template context. By default, this is ``'object'``. |
|
637 |
|
638 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
639 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
640 |
|
641 * ``allow_future``: A boolean specifying whether to include "future" |
|
642 objects on this page, where "future" means objects in which the field |
|
643 specified in ``date_field`` is greater than the current date/time. By |
|
644 default, this is ``False``. |
|
645 |
|
646 **Template name:** |
|
647 |
|
648 If ``template_name`` isn't specified, this view will use the template |
|
649 ``<app_label>/<model_name>_detail.html`` by default. |
|
650 |
|
651 **Template context:** |
|
652 |
|
653 In addition to ``extra_context``, the template's context will be: |
|
654 |
|
655 * ``object``: The object. This variable's name depends on the |
|
656 ``template_object_name`` parameter, which is ``'object'`` by default. If |
|
657 ``template_object_name`` is ``'foo'``, this variable's name will be |
|
658 ``foo``. |
|
659 |
|
660 List/detail generic views |
|
661 ========================= |
|
662 |
|
663 The list-detail generic-view framework (in the |
|
664 ``django.views.generic.list_detail`` module) is similar to the date-based one, |
|
665 except the former simply has two views: a list of objects and an individual |
|
666 object page. |
|
667 |
|
668 ``django.views.generic.list_detail.object_list`` |
|
669 ------------------------------------------------ |
|
670 |
|
671 **Description:** |
|
672 |
|
673 A page representing a list of objects. |
|
674 |
|
675 **Required arguments:** |
|
676 |
|
677 * ``queryset``: A ``QuerySet`` that represents the objects. |
|
678 |
|
679 **Optional arguments:** |
|
680 |
|
681 * ``paginate_by``: An integer specifying how many objects should be |
|
682 displayed per page. If this is given, the view will paginate objects with |
|
683 ``paginate_by`` objects per page. The view will expect either a ``page`` |
|
684 query string parameter (via ``GET``) or a ``page`` variable specified in |
|
685 the URLconf. See `Notes on pagination`_ below. |
|
686 |
|
687 * ``page``: The current page number, as an integer, or the string |
|
688 ``'last'``. This is 1-based. See `Notes on pagination`_ below. |
|
689 |
|
690 * ``template_name``: The full name of a template to use in rendering the |
|
691 page. This lets you override the default template name (see below). |
|
692 |
|
693 * ``template_loader``: The template loader to use when loading the |
|
694 template. By default, it's ``django.template.loader``. |
|
695 |
|
696 * ``extra_context``: A dictionary of values to add to the template |
|
697 context. By default, this is an empty dictionary. If a value in the |
|
698 dictionary is callable, the generic view will call it |
|
699 just before rendering the template. |
|
700 |
|
701 * ``allow_empty``: A boolean specifying whether to display the page if no |
|
702 objects are available. If this is ``False`` and no objects are available, |
|
703 the view will raise a 404 instead of displaying an empty page. By |
|
704 default, this is ``True``. |
|
705 |
|
706 * ``context_processors``: A list of template-context processors to apply to |
|
707 the view's template. |
|
708 |
|
709 * ``template_object_name``: Designates the name of the template variable |
|
710 to use in the template context. By default, this is ``'object'``. The |
|
711 view will append ``'_list'`` to the value of this parameter in |
|
712 determining the variable's name. |
|
713 |
|
714 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
715 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
716 |
|
717 **Template name:** |
|
718 |
|
719 If ``template_name`` isn't specified, this view will use the template |
|
720 ``<app_label>/<model_name>_list.html`` by default. |
|
721 |
|
722 **Template context:** |
|
723 |
|
724 .. versionadded:: 1.0 |
|
725 The ``paginator`` and ``page_obj`` context variables are new. |
|
726 |
|
727 In addition to ``extra_context``, the template's context will be: |
|
728 |
|
729 * ``object_list``: The list of objects. This variable's name depends on the |
|
730 ``template_object_name`` parameter, which is ``'object'`` by default. If |
|
731 ``template_object_name`` is ``'foo'``, this variable's name will be |
|
732 ``foo_list``. |
|
733 |
|
734 * ``is_paginated``: A boolean representing whether the results are |
|
735 paginated. Specifically, this is set to ``False`` if the number of |
|
736 available objects is less than or equal to ``paginate_by``. |
|
737 |
|
738 If the results are paginated, the context will contain these extra variables: |
|
739 |
|
740 * ``paginator``: An instance of ``django.core.paginator.Paginator``. |
|
741 |
|
742 * ``page_obj``: An instance of ``django.core.paginator.Page``. |
|
743 |
|
744 Notes on pagination |
|
745 ~~~~~~~~~~~~~~~~~~~ |
|
746 |
|
747 If ``paginate_by`` is specified, Django will paginate the results. You can |
|
748 specify the page number in the URL in one of two ways: |
|
749 |
|
750 * Use the ``page`` parameter in the URLconf. For example, this is what |
|
751 your URLconf might look like:: |
|
752 |
|
753 (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict)) |
|
754 |
|
755 * Pass the page number via the ``page`` query-string parameter. For |
|
756 example, a URL would look like this:: |
|
757 |
|
758 /objects/?page=3 |
|
759 |
|
760 * To loop over all the available page numbers, use the ``page_range`` |
|
761 variable. You can iterate over the list provided by ``page_range`` |
|
762 to create a link to every page of results. |
|
763 |
|
764 These values and lists are 1-based, not 0-based, so the first page would be |
|
765 represented as page ``1``. |
|
766 |
|
767 For more on pagination, read the :doc:`pagination documentation |
|
768 </topics/pagination>`. |
|
769 |
|
770 .. versionadded:: 1.0 |
|
771 |
|
772 As a special case, you are also permitted to use ``last`` as a value for |
|
773 ``page``:: |
|
774 |
|
775 /objects/?page=last |
|
776 |
|
777 This allows you to access the final page of results without first having to |
|
778 determine how many pages there are. |
|
779 |
|
780 Note that ``page`` *must* be either a valid page number or the value ``last``; |
|
781 any other value for ``page`` will result in a 404 error. |
|
782 |
|
783 ``django.views.generic.list_detail.object_detail`` |
|
784 -------------------------------------------------- |
|
785 |
|
786 A page representing an individual object. |
|
787 |
|
788 **Description:** |
|
789 |
|
790 A page representing an individual object. |
|
791 |
|
792 **Required arguments:** |
|
793 |
|
794 * ``queryset``: A ``QuerySet`` that contains the object. |
|
795 |
|
796 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
|
797 |
|
798 If you provide ``object_id``, it should be the value of the primary-key |
|
799 field for the object being displayed on this page. |
|
800 |
|
801 Otherwise, ``slug`` should be the slug of the given object, and |
|
802 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
|
803 model. By default, ``slug_field`` is ``'slug'``. |
|
804 |
|
805 **Optional arguments:** |
|
806 |
|
807 * ``template_name``: The full name of a template to use in rendering the |
|
808 page. This lets you override the default template name (see below). |
|
809 |
|
810 * ``template_name_field``: The name of a field on the object whose value is |
|
811 the template name to use. This lets you store template names in the data. |
|
812 In other words, if your object has a field ``'the_template'`` that |
|
813 contains a string ``'foo.html'``, and you set ``template_name_field`` to |
|
814 ``'the_template'``, then the generic view for this object will use the |
|
815 template ``'foo.html'``. |
|
816 |
|
817 It's a bit of a brain-bender, but it's useful in some cases. |
|
818 |
|
819 * ``template_loader``: The template loader to use when loading the |
|
820 template. By default, it's ``django.template.loader``. |
|
821 |
|
822 * ``extra_context``: A dictionary of values to add to the template |
|
823 context. By default, this is an empty dictionary. If a value in the |
|
824 dictionary is callable, the generic view will call it |
|
825 just before rendering the template. |
|
826 |
|
827 * ``context_processors``: A list of template-context processors to apply to |
|
828 the view's template. |
|
829 |
|
830 * ``template_object_name``: Designates the name of the template variable |
|
831 to use in the template context. By default, this is ``'object'``. |
|
832 |
|
833 * ``mimetype``: The MIME type to use for the resulting document. Defaults |
|
834 to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
|
835 |
|
836 **Template name:** |
|
837 |
|
838 If ``template_name`` isn't specified, this view will use the template |
|
839 ``<app_label>/<model_name>_detail.html`` by default. |
|
840 |
|
841 **Template context:** |
|
842 |
|
843 In addition to ``extra_context``, the template's context will be: |
|
844 |
|
845 * ``object``: The object. This variable's name depends on the |
|
846 ``template_object_name`` parameter, which is ``'object'`` by default. If |
|
847 ``template_object_name`` is ``'foo'``, this variable's name will be |
|
848 ``foo``. |
|
849 |
|
850 Create/update/delete generic views |
|
851 ================================== |
|
852 |
|
853 The ``django.views.generic.create_update`` module contains a set of functions |
|
854 for creating, editing and deleting objects. |
|
855 |
|
856 .. versionchanged:: 1.0 |
|
857 |
|
858 ``django.views.generic.create_update.create_object`` and |
|
859 ``django.views.generic.create_update.update_object`` now use the new :doc:`forms |
|
860 library </topics/forms/index>` to build and display the form. |
|
861 |
|
862 ``django.views.generic.create_update.create_object`` |
|
863 ---------------------------------------------------- |
|
864 |
|
865 **Description:** |
|
866 |
|
867 A page that displays a form for creating an object, redisplaying the form with |
|
868 validation errors (if there are any) and saving the object. |
|
869 |
|
870 **Required arguments:** |
|
871 |
|
872 * Either ``form_class`` or ``model`` is required. |
|
873 |
|
874 If you provide ``form_class``, it should be a ``django.forms.ModelForm`` |
|
875 subclass. Use this argument when you need to customize the model's form. |
|
876 See the :doc:`ModelForm docs </topics/forms/modelforms>` for more |
|
877 information. |
|
878 |
|
879 Otherwise, ``model`` should be a Django model class and the form used |
|
880 will be a standard ``ModelForm`` for ``model``. |
|
881 |
|
882 **Optional arguments:** |
|
883 |
|
884 * ``post_save_redirect``: A URL to which the view will redirect after |
|
885 saving the object. By default, it's ``object.get_absolute_url()``. |
|
886 |
|
887 ``post_save_redirect`` may contain dictionary string formatting, which |
|
888 will be interpolated against the object's field attributes. For example, |
|
889 you could use ``post_save_redirect="/polls/%(slug)s/"``. |
|
890 |
|
891 * ``login_required``: A boolean that designates whether a user must be |
|
892 logged in, in order to see the page and save changes. This hooks into the |
|
893 Django :doc:`authentication system </topics/auth>`. By default, this is |
|
894 ``False``. |
|
895 |
|
896 If this is ``True``, and a non-logged-in user attempts to visit this page |
|
897 or save the form, Django will redirect the request to ``/accounts/login/``. |
|
898 |
|
899 * ``template_name``: The full name of a template to use in rendering the |
|
900 page. This lets you override the default template name (see below). |
|
901 |
|
902 * ``template_loader``: The template loader to use when loading the |
|
903 template. By default, it's ``django.template.loader``. |
|
904 |
|
905 * ``extra_context``: A dictionary of values to add to the template |
|
906 context. By default, this is an empty dictionary. If a value in the |
|
907 dictionary is callable, the generic view will call it |
|
908 just before rendering the template. |
|
909 |
|
910 * ``context_processors``: A list of template-context processors to apply to |
|
911 the view's template. |
|
912 |
|
913 **Template name:** |
|
914 |
|
915 If ``template_name`` isn't specified, this view will use the template |
|
916 ``<app_label>/<model_name>_form.html`` by default. |
|
917 |
|
918 **Template context:** |
|
919 |
|
920 In addition to ``extra_context``, the template's context will be: |
|
921 |
|
922 * ``form``: A ``django.forms.ModelForm`` instance representing the form |
|
923 for creating the object. This lets you refer to form fields easily in the |
|
924 template system. |
|
925 |
|
926 For example, if the model has two fields, ``name`` and ``address``:: |
|
927 |
|
928 <form action="" method="post"> |
|
929 <p>{{ form.name.label_tag }} {{ form.name }}</p> |
|
930 <p>{{ form.address.label_tag }} {{ form.address }}</p> |
|
931 </form> |
|
932 |
|
933 See the :doc:`forms documentation </topics/forms/index>` for more |
|
934 information about using ``Form`` objects in templates. |
|
935 |
|
936 ``django.views.generic.create_update.update_object`` |
|
937 ---------------------------------------------------- |
|
938 |
|
939 **Description:** |
|
940 |
|
941 A page that displays a form for editing an existing object, redisplaying the |
|
942 form with validation errors (if there are any) and saving changes to the |
|
943 object. This uses a form automatically generated from the object's |
|
944 model class. |
|
945 |
|
946 **Required arguments:** |
|
947 |
|
948 * Either ``form_class`` or ``model`` is required. |
|
949 |
|
950 If you provide ``form_class``, it should be a ``django.forms.ModelForm`` |
|
951 subclass. Use this argument when you need to customize the model's form. |
|
952 See the :doc:`ModelForm docs </topics/forms/modelforms>` for more |
|
953 information. |
|
954 |
|
955 Otherwise, ``model`` should be a Django model class and the form used |
|
956 will be a standard ``ModelForm`` for ``model``. |
|
957 |
|
958 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
|
959 |
|
960 If you provide ``object_id``, it should be the value of the primary-key |
|
961 field for the object being displayed on this page. |
|
962 |
|
963 Otherwise, ``slug`` should be the slug of the given object, and |
|
964 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
|
965 model. By default, ``slug_field`` is ``'slug'``. |
|
966 |
|
967 **Optional arguments:** |
|
968 |
|
969 * ``post_save_redirect``: A URL to which the view will redirect after |
|
970 saving the object. By default, it's ``object.get_absolute_url()``. |
|
971 |
|
972 ``post_save_redirect`` may contain dictionary string formatting, which |
|
973 will be interpolated against the object's field attributes. For example, |
|
974 you could use ``post_save_redirect="/polls/%(slug)s/"``. |
|
975 |
|
976 * ``login_required``: A boolean that designates whether a user must be |
|
977 logged in, in order to see the page and save changes. This hooks into the |
|
978 Django :doc:`authentication system </topics/auth>`. By default, this is |
|
979 ``False``. |
|
980 |
|
981 If this is ``True``, and a non-logged-in user attempts to visit this page |
|
982 or save the form, Django will redirect the request to ``/accounts/login/``. |
|
983 |
|
984 * ``template_name``: The full name of a template to use in rendering the |
|
985 page. This lets you override the default template name (see below). |
|
986 |
|
987 * ``template_loader``: The template loader to use when loading the |
|
988 template. By default, it's ``django.template.loader``. |
|
989 |
|
990 * ``extra_context``: A dictionary of values to add to the template |
|
991 context. By default, this is an empty dictionary. If a value in the |
|
992 dictionary is callable, the generic view will call it |
|
993 just before rendering the template. |
|
994 |
|
995 * ``context_processors``: A list of template-context processors to apply to |
|
996 the view's template. |
|
997 |
|
998 * ``template_object_name``: Designates the name of the template variable |
|
999 to use in the template context. By default, this is ``'object'``. |
|
1000 |
|
1001 **Template name:** |
|
1002 |
|
1003 If ``template_name`` isn't specified, this view will use the template |
|
1004 ``<app_label>/<model_name>_form.html`` by default. |
|
1005 |
|
1006 **Template context:** |
|
1007 |
|
1008 In addition to ``extra_context``, the template's context will be: |
|
1009 |
|
1010 * ``form``: A ``django.forms.ModelForm`` instance representing the form |
|
1011 for editing the object. This lets you refer to form fields easily in the |
|
1012 template system. |
|
1013 |
|
1014 For example, if the model has two fields, ``name`` and ``address``:: |
|
1015 |
|
1016 <form action="" method="post"> |
|
1017 <p>{{ form.name.label_tag }} {{ form.name }}</p> |
|
1018 <p>{{ form.address.label_tag }} {{ form.address }}</p> |
|
1019 </form> |
|
1020 |
|
1021 See the :doc:`forms documentation </topics/forms/index>` for more |
|
1022 information about using ``Form`` objects in templates. |
|
1023 |
|
1024 * ``object``: The original object being edited. This variable's name |
|
1025 depends on the ``template_object_name`` parameter, which is ``'object'`` |
|
1026 by default. If ``template_object_name`` is ``'foo'``, this variable's |
|
1027 name will be ``foo``. |
|
1028 |
|
1029 ``django.views.generic.create_update.delete_object`` |
|
1030 ---------------------------------------------------- |
|
1031 |
|
1032 **Description:** |
|
1033 |
|
1034 A view that displays a confirmation page and deletes an existing object. The |
|
1035 given object will only be deleted if the request method is ``POST``. If this |
|
1036 view is fetched via ``GET``, it will display a confirmation page that should |
|
1037 contain a form that POSTs to the same URL. |
|
1038 |
|
1039 **Required arguments:** |
|
1040 |
|
1041 * ``model``: The Django model class of the object that the form will |
|
1042 create. |
|
1043 |
|
1044 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
|
1045 |
|
1046 If you provide ``object_id``, it should be the value of the primary-key |
|
1047 field for the object being displayed on this page. |
|
1048 |
|
1049 Otherwise, ``slug`` should be the slug of the given object, and |
|
1050 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
|
1051 model. By default, ``slug_field`` is ``'slug'``. |
|
1052 |
|
1053 * ``post_delete_redirect``: A URL to which the view will redirect after |
|
1054 deleting the object. |
|
1055 |
|
1056 **Optional arguments:** |
|
1057 |
|
1058 * ``login_required``: A boolean that designates whether a user must be |
|
1059 logged in, in order to see the page and save changes. This hooks into the |
|
1060 Django :doc:`authentication system </topics/auth>`. By default, this is |
|
1061 ``False``. |
|
1062 |
|
1063 If this is ``True``, and a non-logged-in user attempts to visit this page |
|
1064 or save the form, Django will redirect the request to ``/accounts/login/``. |
|
1065 |
|
1066 * ``template_name``: The full name of a template to use in rendering the |
|
1067 page. This lets you override the default template name (see below). |
|
1068 |
|
1069 * ``template_loader``: The template loader to use when loading the |
|
1070 template. By default, it's ``django.template.loader``. |
|
1071 |
|
1072 * ``extra_context``: A dictionary of values to add to the template |
|
1073 context. By default, this is an empty dictionary. If a value in the |
|
1074 dictionary is callable, the generic view will call it |
|
1075 just before rendering the template. |
|
1076 |
|
1077 * ``context_processors``: A list of template-context processors to apply to |
|
1078 the view's template. |
|
1079 |
|
1080 * ``template_object_name``: Designates the name of the template variable |
|
1081 to use in the template context. By default, this is ``'object'``. |
|
1082 |
|
1083 **Template name:** |
|
1084 |
|
1085 If ``template_name`` isn't specified, this view will use the template |
|
1086 ``<app_label>/<model_name>_confirm_delete.html`` by default. |
|
1087 |
|
1088 **Template context:** |
|
1089 |
|
1090 In addition to ``extra_context``, the template's context will be: |
|
1091 |
|
1092 * ``object``: The original object that's about to be deleted. This |
|
1093 variable's name depends on the ``template_object_name`` parameter, which |
|
1094 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
|
1095 this variable's name will be ``foo``. |