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

329 lines
12 KiB
Plaintext

==================
Generic date views
==================
.. module:: django.views.generic.dates
Date-based generic views, provided in :mod:`django.views.generic.dates`, are
views for displaying drilldown pages for date-based data.
ArchiveIndexView
----------------
.. class:: ArchiveIndexView
A top-level index page showing the "latest" objects, by date. Objects with
a date in the *future* are not included unless you set ``allow_future`` to
``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.ArchiveIndexView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseArchiveIndexView`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Notes**
* Uses a default ``context_object_name`` of ``latest``.
* Uses a default ``template_name_suffix`` of ``_archive``.
* Defaults to providing ``date_list`` by year, but this can be altered to
month or day using the attribute ``date_list_period``. This also applies
to all subclass views.
YearArchiveView
---------------
.. class:: YearArchiveView
A yearly archive page showing all available months in a given year. Objects
with a date in the *future* are not displayed unless you set
``allow_future`` to ``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.YearArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseYearArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
.. attribute:: make_object_list
A boolean specifying whether to retrieve the full list of objects for
this year and pass those to the template. If ``True``, the list of
objects will be made available to the context. If ``False``, the
``None`` queryset will be used as the object list. By default, this is
``False``.
.. method:: get_make_object_list()
Determine if an object list will be returned as part of the context.
Returns :attr:`~YearArchiveView.make_object_list` by default.
**Context**
In addition to the context provided by
:class:`django.views.generic.list.MultipleObjectMixin` (via
:class:`django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``date_list``: A
:meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object object
containing all months that have objects available according to
``queryset``, represented as
:class:`datetime.datetime<python:datetime.datetime>` objects, in
ascending order.
* ``year``: A :class:`~datetime.date` object
representing the given year.
* ``next_year``: A :class:`~datetime.date` object
representing the first day of the next year, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_year``: A :class:`~datetime.date` object
representing the first day of the previous year, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_year``.
MonthArchiveView
----------------
.. class:: MonthArchiveView
A monthly archive page showing all objects in a given month. Objects with a
date in the *future* are not displayed unless you set ``allow_future`` to
``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.MonthArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseMonthArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Context**
In addition to the context provided by
:class:`~django.views.generic.list.MultipleObjectMixin` (via
:class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``date_list``: A
:meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object
containing all days that have objects available in the given month,
according to ``queryset``, represented as
:class:`datetime.datetime<python:datetime.datetime>` objects, in
ascending order.
* ``month``: A :class:`~datetime.date` object
representing the given month.
* ``next_month``: A :class:`~datetime.date` object
representing the first day of the next month, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_month``: A :class:`~datetime.date` object
representing the first day of the previous month, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_month``.
WeekArchiveView
---------------
.. class:: WeekArchiveView
A weekly archive page showing all objects in a given week. Objects with a
date in the *future* are not displayed unless you set ``allow_future`` to
``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.WeekArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseWeekArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.WeekMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Context**
In addition to the context provided by
:class:`~django.views.generic.list.MultipleObjectMixin` (via
:class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``week``: A :class:`~datetime.date` object
representing the first day of the given week.
* ``next_week``: A :class:`~datetime.date` object
representing the first day of the next week, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_week``: A :class:`~datetime.date` object
representing the first day of the previous week, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_week``.
DayArchiveView
--------------
.. class:: DayArchiveView
A day archive page showing all objects in a given day. Days in the future
throw a 404 error, regardless of whether any objects exist for future days,
unless you set ``allow_future`` to ``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.DayArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseDayArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.DayMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Context**
In addition to the context provided by
:class:`~django.views.generic.list.MultipleObjectMixin` (via
:class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``day``: A :class:`~datetime.date` object
representing the given day.
* ``next_day``: A :class:`~datetime.date` object
representing the next day, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_day``: A :class:`~datetime.date` object
representing the previous day, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``next_month``: A :class:`~datetime.date` object
representing the first day of the next month, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_month``: A :class:`~datetime.date` object
representing the first day of the previous month, according to
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_day``.
TodayArchiveView
----------------
.. class:: TodayArchiveView
A day archive page showing all objects for *today*. This is exactly the
same as :class:`django.views.generic.dates.DayArchiveView`, except today's
date is used instead of the ``year``/``month``/``day`` arguments.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.TodayArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseTodayArchiveView`
* :class:`django.views.generic.dates.BaseDayArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.DayMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
DateDetailView
--------------
.. class:: DateDetailView
A page representing an individual object. If the object has a date value in
the future, the view will throw a 404 error by default, unless you set
``allow_future`` to ``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.DateDetailView`
* :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseDateDetailView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.DayMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.detail.BaseDetailView`
* :class:`django.views.generic.detail.SingleObjectMixin`
* :class:`django.views.generic.base.View`
.. note::
All of the generic views listed above have matching ``Base`` views that
only differ in that the they do not include the
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`:
.. class:: BaseArchiveIndexView
.. class:: BaseYearArchiveView
.. class:: BaseMonthArchiveView
.. class:: BaseWeekArchiveView
.. class:: BaseDayArchiveView
.. class:: BaseTodayArchiveView
.. class:: BaseDateDetailView