Debian Codegraph @

docs/ref/class-based-views/generic-date-based.txt

raw
1 ==================
2 Generic date views
3 ==================
4
5 .. module:: django.views.generic.dates
6
7 Date-based generic views, provided in :mod:`django.views.generic.dates`, are
8 views for displaying drilldown pages for date-based data.
9
10 .. note::
11
12 Some of the examples on this page assume that an ``Article`` model has been
13 defined as follows in ``myapp/models.py``::
14
15 from django.db import models
16 from django.urls import reverse
17
18
19 class Article(models.Model):
20 title = models.CharField(max_length=200)
21 pub_date = models.DateField()
22
23 def get_absolute_url(self):
24 return reverse("article-detail", kwargs={"pk": self.pk})
25
26 ``ArchiveIndexView``
27 ====================
28
29 .. class:: ArchiveIndexView
30
31 A top-level index page showing the "latest" objects, by date. Objects with
32 a date in the *future* are not included unless you set ``allow_future`` to
33 ``True``.
34
35 **Ancestors (MRO)**
36
37 * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
38 * :class:`django.views.generic.base.TemplateResponseMixin`
39 * :class:`django.views.generic.dates.BaseArchiveIndexView`
40 * :class:`django.views.generic.dates.BaseDateListView`
41 * :class:`django.views.generic.list.MultipleObjectMixin`
42 * :class:`django.views.generic.dates.DateMixin`
43 * :class:`django.views.generic.base.View`
44
45 **Context**
46
47 In addition to the context provided by
48 :class:`django.views.generic.list.MultipleObjectMixin` (via
49 :class:`django.views.generic.dates.BaseDateListView`), the template's
50 context will be:
51
52 * ``date_list``: A :meth:`QuerySet <django.db.models.query.QuerySet.dates>`
53 object containing all years that have objects available according to
54 ``queryset``, represented as :class:`datetime.datetime` objects, in
55 descending order.
56
57 **Notes**
58
59 * Uses a default ``context_object_name`` of ``latest``.
60 * Uses a default ``template_name_suffix`` of ``_archive``.
61 * Defaults to providing ``date_list`` by year, but this can be altered to
62 month or day using the attribute ``date_list_period``. This also applies
63 to all subclass views.
64
65 **Example myapp/urls.py**::
66
67 from django.urls import path
68 from django.views.generic.dates import ArchiveIndexView
69
70 from myapp.models import Article
71
72 urlpatterns = [
73 path(
74 "archive/",
75 ArchiveIndexView.as_view(model=Article, date_field="pub_date"),
76 name="article_archive",
77 ),
78 ]
79
80 **Example myapp/article_archive.html**:
81
82 .. code-block:: html+django
83
84 <ul>
85 {% for article in latest %}
86 <li>{{ article.pub_date }}: {{ article.title }}</li>
87 {% endfor %}
88 </ul>
89
90 This will output all articles.
91
92 ``YearArchiveView``
93 ===================
94
95 .. class:: YearArchiveView
96
97 A yearly archive page showing all available months in a given year. Objects
98 with a date in the *future* are not displayed unless you set
99 ``allow_future`` to ``True``.
100
101 **Ancestors (MRO)**
102
103 * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
104 * :class:`django.views.generic.base.TemplateResponseMixin`
105 * :class:`django.views.generic.dates.BaseYearArchiveView`
106 * :class:`django.views.generic.dates.YearMixin`
107 * :class:`django.views.generic.dates.BaseDateListView`
108 * :class:`django.views.generic.list.MultipleObjectMixin`
109 * :class:`django.views.generic.dates.DateMixin`
110 * :class:`django.views.generic.base.View`
111
112 .. attribute:: make_object_list
113
114 A boolean specifying whether to retrieve the full list of objects for
115 this year and pass those to the template. If ``True``, the list of
116 objects will be made available to the context. If ``False``, the
117 ``None`` queryset will be used as the object list. By default, this is
118 ``False``.
119
120 .. method:: get_make_object_list()
121
122 Determine if an object list will be returned as part of the context.
123 Returns :attr:`~YearArchiveView.make_object_list` by default.
124
125 **Context**
126
127 In addition to the context provided by
128 :class:`django.views.generic.list.MultipleObjectMixin` (via
129 :class:`django.views.generic.dates.BaseDateListView`), the template's
130 context will be:
131
132 * ``date_list``: A :meth:`QuerySet <django.db.models.query.QuerySet.dates>`
133 object containing all months that have objects available according to
134 ``queryset``, represented as :class:`datetime.datetime` objects, in
135 ascending order.
136
137 * ``year``: A :class:`~datetime.date` object
138 representing the given year.
139
140 * ``next_year``: A :class:`~datetime.date` object
141 representing the first day of the next year, according to
142 :attr:`~BaseDateListView.allow_empty` and
143 :attr:`~DateMixin.allow_future`.
144
145 * ``previous_year``: A :class:`~datetime.date` object
146 representing the first day of the previous year, according to
147 :attr:`~BaseDateListView.allow_empty` and
148 :attr:`~DateMixin.allow_future`.
149
150 **Notes**
151
152 * Uses a default ``template_name_suffix`` of ``_archive_year``.
153
154 **Example myapp/views.py**::
155
156 from django.views.generic.dates import YearArchiveView
157
158 from myapp.models import Article
159
160
161 class ArticleYearArchiveView(YearArchiveView):
162 queryset = Article.objects.all()
163 date_field = "pub_date"
164 make_object_list = True
165 allow_future = True
166
167 **Example myapp/urls.py**::
168
169 from django.urls import path
170
171 from myapp.views import ArticleYearArchiveView
172
173 urlpatterns = [
174 path("<int:year>/", ArticleYearArchiveView.as_view(), name="article_year_archive"),
175 ]
176
177 **Example myapp/article_archive_year.html**:
178
179 .. code-block:: html+django
180
181 <ul>
182 {% for date in date_list %}
183 <li>{{ date|date }}</li>
184 {% endfor %}
185 </ul>
186
187 <div>
188 <h1>All Articles for {{ year|date:"Y" }}</h1>
189 {% for obj in object_list %}
190 <p>
191 {{ obj.title }} - {{ obj.pub_date|date:"F j, Y" }}
192 </p>
193 {% endfor %}
194 </div>
195
196 ``MonthArchiveView``
197 ====================
198
199 .. class:: MonthArchiveView
200
201 A monthly archive page showing all objects in a given month. Objects with a
202 date in the *future* are not displayed unless you set ``allow_future`` to
203 ``True``.
204
205 **Ancestors (MRO)**
206
207 * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
208 * :class:`django.views.generic.base.TemplateResponseMixin`
209 * :class:`django.views.generic.dates.BaseMonthArchiveView`
210 * :class:`django.views.generic.dates.YearMixin`
211 * :class:`django.views.generic.dates.MonthMixin`
212 * :class:`django.views.generic.dates.BaseDateListView`
213 * :class:`django.views.generic.list.MultipleObjectMixin`
214 * :class:`django.views.generic.dates.DateMixin`
215 * :class:`django.views.generic.base.View`
216
217 **Context**
218
219 In addition to the context provided by
220 :class:`~django.views.generic.list.MultipleObjectMixin` (via
221 :class:`~django.views.generic.dates.BaseDateListView`), the template's
222 context will be:
223
224 * ``date_list``: A :meth:`QuerySet <django.db.models.query.QuerySet.dates>`
225 object containing all days that have objects available in the given month,
226 according to ``queryset``, represented as :class:`datetime.datetime`
227 objects, in ascending order.
228
229 * ``month``: A :class:`~datetime.date` object
230 representing the given month.
231
232 * ``next_month``: A :class:`~datetime.date` object
233 representing the first day of the next month, according to
234 :attr:`~BaseDateListView.allow_empty` and
235 :attr:`~DateMixin.allow_future`.
236
237 * ``previous_month``: A :class:`~datetime.date` object
238 representing the first day of the previous month, according to
239 :attr:`~BaseDateListView.allow_empty` and
240 :attr:`~DateMixin.allow_future`.
241
242 **Notes**
243
244 * Uses a default ``template_name_suffix`` of ``_archive_month``.
245
246 **Example myapp/views.py**::
247
248 from django.views.generic.dates import MonthArchiveView
249
250 from myapp.models import Article
251
252
253 class ArticleMonthArchiveView(MonthArchiveView):
254 queryset = Article.objects.all()
255 date_field = "pub_date"
256 allow_future = True
257
258 **Example myapp/urls.py**::
259
260 from django.urls import path
261
262 from myapp.views import ArticleMonthArchiveView
263
264 urlpatterns = [
265 # Example: /2012/08/
266 path(
267 "<int:year>/<int:month>/",
268 ArticleMonthArchiveView.as_view(month_format="%m"),
269 name="archive_month_numeric",
270 ),
271 # Example: /2012/aug/
272 path(
273 "<int:year>/<str:month>/",
274 ArticleMonthArchiveView.as_view(),
275 name="archive_month",
276 ),
277 ]
278
279 **Example myapp/article_archive_month.html**:
280
281 .. code-block:: html+django
282
283 <ul>
284 {% for article in object_list %}
285 <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>
286 {% endfor %}
287 </ul>
288
289 <p>
290 {% if previous_month %}
291 Previous Month: {{ previous_month|date:"F Y" }}
292 {% endif %}
293 {% if next_month %}
294 Next Month: {{ next_month|date:"F Y" }}
295 {% endif %}
296 </p>
297
298 ``WeekArchiveView``
299 ===================
300
301 .. class:: WeekArchiveView
302
303 A weekly archive page showing all objects in a given week. Objects with a
304 date in the *future* are not displayed unless you set ``allow_future`` to
305 ``True``.
306
307 **Ancestors (MRO)**
308
309 * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
310 * :class:`django.views.generic.base.TemplateResponseMixin`
311 * :class:`django.views.generic.dates.BaseWeekArchiveView`
312 * :class:`django.views.generic.dates.YearMixin`
313 * :class:`django.views.generic.dates.WeekMixin`
314 * :class:`django.views.generic.dates.BaseDateListView`
315 * :class:`django.views.generic.list.MultipleObjectMixin`
316 * :class:`django.views.generic.dates.DateMixin`
317 * :class:`django.views.generic.base.View`
318
319 **Context**
320
321 In addition to the context provided by
322 :class:`~django.views.generic.list.MultipleObjectMixin` (via
323 :class:`~django.views.generic.dates.BaseDateListView`), the template's
324 context will be:
325
326 * ``week``: A :class:`~datetime.date` object
327 representing the first day of the given week.
328
329 * ``next_week``: A :class:`~datetime.date` object
330 representing the first day of the next week, according to
331 :attr:`~BaseDateListView.allow_empty` and
332 :attr:`~DateMixin.allow_future`.
333
334 * ``previous_week``: A :class:`~datetime.date` object
335 representing the first day of the previous week, according to
336 :attr:`~BaseDateListView.allow_empty` and
337 :attr:`~DateMixin.allow_future`.
338
339 **Notes**
340
341 * Uses a default ``template_name_suffix`` of ``_archive_week``.
342
343 * The ``week_format`` attribute is a :func:`~time.strptime` format string
344 used to parse the week number. The following values are supported:
345
346 * ``'%U'``: Based on the United States week system where the week
347 begins on Sunday. This is the default value.
348
349 * ``'%W'``: Similar to ``'%U'``, except it assumes that the week
350 begins on Monday. This is not the same as the ISO 8601 week number.
351
352 * ``'%V'``: ISO 8601 week number where the week begins on Monday.
353
354 **Example myapp/views.py**::
355
356 from django.views.generic.dates import WeekArchiveView
357
358 from myapp.models import Article
359
360
361 class ArticleWeekArchiveView(WeekArchiveView):
362 queryset = Article.objects.all()
363 date_field = "pub_date"
364 week_format = "%W"
365 allow_future = True
366
367 **Example myapp/urls.py**::
368
369 from django.urls import path
370
371 from myapp.views import ArticleWeekArchiveView
372
373 urlpatterns = [
374 # Example: /2012/week/23/
375 path(
376 "<int:year>/week/<int:week>/",
377 ArticleWeekArchiveView.as_view(),
378 name="archive_week",
379 ),
380 ]
381
382 **Example myapp/article_archive_week.html**:
383
384 .. code-block:: html+django
385
386 <h1>Week {{ week|date:'W' }}</h1>
387
388 <ul>
389 {% for article in object_list %}
390 <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>
391 {% endfor %}
392 </ul>
393
394 <p>
395 {% if previous_week %}
396 Previous Week: {{ previous_week|date:"W" }} of year {{ previous_week|date:"Y" }}
397 {% endif %}
398 {% if previous_week and next_week %}--{% endif %}
399 {% if next_week %}
400 Next week: {{ next_week|date:"W" }} of year {{ next_week|date:"Y" }}
401 {% endif %}
402 </p>
403
404 In this example, you are outputting the week number. Keep in mind that week
405 numbers computed by the :tfilter:`date` template filter with the ``'W'``
406 format character are not always the same as those computed by
407 :func:`~time.strftime` and :func:`~time.strptime` with the ``'%W'`` format
408 string. For year 2015, for example, week numbers output by :tfilter:`date`
409 are higher by one compared to those output by :func:`~time.strftime`. There
410 isn't an equivalent for the ``'%U'`` :func:`~time.strftime` format string
411 in :tfilter:`date`. Therefore, you should avoid using :tfilter:`date` to
412 generate URLs for ``WeekArchiveView``.
413
414 ``DayArchiveView``
415 ==================
416
417 .. class:: DayArchiveView
418
419 A day archive page showing all objects in a given day. Days in the future
420 throw a 404 error, regardless of whether any objects exist for future days,
421 unless you set ``allow_future`` to ``True``.
422
423 **Ancestors (MRO)**
424
425 * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
426 * :class:`django.views.generic.base.TemplateResponseMixin`
427 * :class:`django.views.generic.dates.BaseDayArchiveView`
428 * :class:`django.views.generic.dates.YearMixin`
429 * :class:`django.views.generic.dates.MonthMixin`
430 * :class:`django.views.generic.dates.DayMixin`
431 * :class:`django.views.generic.dates.BaseDateListView`
432 * :class:`django.views.generic.list.MultipleObjectMixin`
433 * :class:`django.views.generic.dates.DateMixin`
434 * :class:`django.views.generic.base.View`
435
436 **Context**
437
438 In addition to the context provided by
439 :class:`~django.views.generic.list.MultipleObjectMixin` (via
440 :class:`~django.views.generic.dates.BaseDateListView`), the template's
441 context will be:
442
443 * ``day``: A :class:`~datetime.date` object
444 representing the given day.
445
446 * ``next_day``: A :class:`~datetime.date` object
447 representing the next day, according to
448 :attr:`~BaseDateListView.allow_empty` and
449 :attr:`~DateMixin.allow_future`.
450
451 * ``previous_day``: A :class:`~datetime.date` object
452 representing the previous day, according to
453 :attr:`~BaseDateListView.allow_empty` and
454 :attr:`~DateMixin.allow_future`.
455
456 * ``next_month``: A :class:`~datetime.date` object
457 representing the first day of the next month, according to
458 :attr:`~BaseDateListView.allow_empty` and
459 :attr:`~DateMixin.allow_future`.
460
461 * ``previous_month``: A :class:`~datetime.date` object
462 representing the first day of the previous month, according to
463 :attr:`~BaseDateListView.allow_empty` and
464 :attr:`~DateMixin.allow_future`.
465
466 **Notes**
467
468 * Uses a default ``template_name_suffix`` of ``_archive_day``.
469
470 **Example myapp/views.py**::
471
472 from django.views.generic.dates import DayArchiveView
473
474 from myapp.models import Article
475
476
477 class ArticleDayArchiveView(DayArchiveView):
478 queryset = Article.objects.all()
479 date_field = "pub_date"
480 allow_future = True
481
482 **Example myapp/urls.py**::
483
484 from django.urls import path
485
486 from myapp.views import ArticleDayArchiveView
487
488 urlpatterns = [
489 # Example: /2012/nov/10/
490 path(
491 "<int:year>/<str:month>/<int:day>/",
492 ArticleDayArchiveView.as_view(),
493 name="archive_day",
494 ),
495 ]
496
497 **Example myapp/article_archive_day.html**:
498
499 .. code-block:: html+django
500
501 <h1>{{ day }}</h1>
502
503 <ul>
504 {% for article in object_list %}
505 <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>
506 {% endfor %}
507 </ul>
508
509 <p>
510 {% if previous_day %}
511 Previous Day: {{ previous_day }}
512 {% endif %}
513 {% if previous_day and next_day %}--{% endif %}
514 {% if next_day %}
515 Next Day: {{ next_day }}
516 {% endif %}
517 </p>
518
519 ``TodayArchiveView``
520 ====================
521
522 .. class:: TodayArchiveView
523
524 A day archive page showing all objects for *today*. This is exactly the
525 same as :class:`django.views.generic.dates.DayArchiveView`, except today's
526 date is used instead of the ``year``/``month``/``day`` arguments.
527
528 **Ancestors (MRO)**
529
530 * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
531 * :class:`django.views.generic.base.TemplateResponseMixin`
532 * :class:`django.views.generic.dates.BaseTodayArchiveView`
533 * :class:`django.views.generic.dates.BaseDayArchiveView`
534 * :class:`django.views.generic.dates.YearMixin`
535 * :class:`django.views.generic.dates.MonthMixin`
536 * :class:`django.views.generic.dates.DayMixin`
537 * :class:`django.views.generic.dates.BaseDateListView`
538 * :class:`django.views.generic.list.MultipleObjectMixin`
539 * :class:`django.views.generic.dates.DateMixin`
540 * :class:`django.views.generic.base.View`
541
542 **Notes**
543
544 * Uses a default ``template_name_suffix`` of ``_archive_today``.
545
546 **Example myapp/views.py**::
547
548 from django.views.generic.dates import TodayArchiveView
549
550 from myapp.models import Article
551
552
553 class ArticleTodayArchiveView(TodayArchiveView):
554 queryset = Article.objects.all()
555 date_field = "pub_date"
556 allow_future = True
557
558 **Example myapp/urls.py**::
559
560 from django.urls import path
561
562 from myapp.views import ArticleTodayArchiveView
563
564 urlpatterns = [
565 path("today/", ArticleTodayArchiveView.as_view(), name="archive_today"),
566 ]
567
568 .. admonition:: Where is the example template for ``TodayArchiveView``?
569
570 This view uses by default the same template as the
571 :class:`~DayArchiveView`, which is in the previous example. If you need
572 a different template, set the ``template_name`` attribute to be the
573 name of the new template.
574
575 ``DateDetailView``
576 ==================
577
578 .. class:: DateDetailView
579
580 A page representing an individual object. If the object has a date value in
581 the future, the view will throw a 404 error by default, unless you set
582 ``allow_future`` to ``True``.
583
584 **Ancestors (MRO)**
585
586 * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
587 * :class:`django.views.generic.base.TemplateResponseMixin`
588 * :class:`django.views.generic.dates.BaseDateDetailView`
589 * :class:`django.views.generic.dates.YearMixin`
590 * :class:`django.views.generic.dates.MonthMixin`
591 * :class:`django.views.generic.dates.DayMixin`
592 * :class:`django.views.generic.dates.DateMixin`
593 * :class:`django.views.generic.detail.BaseDetailView`
594 * :class:`django.views.generic.detail.SingleObjectMixin`
595 * :class:`django.views.generic.base.View`
596
597 **Context**
598
599 * Includes the single object associated with the ``model`` specified in
600 the ``DateDetailView``.
601
602 **Notes**
603
604 * Uses a default ``template_name_suffix`` of ``_detail``.
605
606 **Example myapp/urls.py**::
607
608 from django.urls import path
609 from django.views.generic.dates import DateDetailView
610
611 urlpatterns = [
612 path(
613 "<int:year>/<str:month>/<int:day>/<int:pk>/",
614 DateDetailView.as_view(model=Article, date_field="pub_date"),
615 name="archive_date_detail",
616 ),
617 ]
618
619 **Example myapp/article_detail.html**:
620
621 .. code-block:: html+django
622
623 <h1>{{ object.title }}</h1>
624
625 .. note::
626
627 All of the generic views listed above have matching ``Base`` views that
628 only differ in that they do not include the
629 :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`
630 (for the archive views) or
631 :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`
632 (for the :class:`DateDetailView`):
633
634 .. class:: BaseArchiveIndexView
635
636 .. class:: BaseYearArchiveView
637
638 .. class:: BaseMonthArchiveView
639
640 .. class:: BaseWeekArchiveView
641
642 .. class:: BaseDayArchiveView
643
644 .. class:: BaseTodayArchiveView
645
646 .. class:: BaseDateDetailView