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