==================

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.

.. note::

    Some of the examples on this page assume that an ``Article`` model has been

    defined as follows in ``myapp/models.py``::

        from django.db import models

        from django.urls import reverse

        class Article(models.Model):

            title = models.CharField(max_length=200)

            pub_date = models.DateField()

            def get_absolute_url(self):

                return reverse('article-detail', kwargs={'pk': self.pk})

``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.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`

    **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:`QuerySet <django.db.models.query.QuerySet.dates>`

      object containing all years that have objects available according to

      ``queryset``, represented as :class:`datetime.datetime` objects, in

      descending order.

    **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.

    **Example myapp/urls.py**::

        from django.urls import path

        from django.views.generic.dates import ArchiveIndexView

        from myapp.models import Article

        urlpatterns = [

            path('archive/',

                 ArchiveIndexView.as_view(model=Article, date_field="pub_date"),

                 name="article_archive"),

        ]

    **Example myapp/article_archive.html**:

    .. code-block:: html+django

        <ul>

            {% for article in latest %}

                <li>{{ article.pub_date }}: {{ article.title }}</li>

            {% endfor %}

        </ul>

    This will output all articles.

``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.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:`QuerySet <django.db.models.query.QuerySet.dates>`

      object containing all months that have objects available according to

      ``queryset``, represented as :class:`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``.

    **Example myapp/views.py**::

        from django.views.generic.dates import YearArchiveView

        from myapp.models import Article

        class ArticleYearArchiveView(YearArchiveView):

            queryset = Article.objects.all()

            date_field = "pub_date"

            make_object_list = True

            allow_future = True

    **Example myapp/urls.py**::

        from django.urls import path

        from myapp.views import ArticleYearArchiveView

        urlpatterns = [

            path('<int:year>/',

                 ArticleYearArchiveView.as_view(),

                 name="article_year_archive"),

        ]

    **Example myapp/article_archive_year.html**:

    .. code-block:: html+django

        <ul>

            {% for date in date_list %}

                <li>{{ date|date }}</li>

            {% endfor %}

        </ul>

        <div>

            <h1>All Articles for {{ year|date:"Y" }}</h1>

            {% for obj in object_list %}

                <p>

                    {{ obj.title }} - {{ obj.pub_date|date:"F j, Y" }}

                </p>

            {% endfor %}

        </div>

``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.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:`QuerySet <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`

      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``.

    **Example myapp/views.py**::

        from django.views.generic.dates import MonthArchiveView

        from myapp.models import Article

        class ArticleMonthArchiveView(MonthArchiveView):

            queryset = Article.objects.all()

            date_field = "pub_date"

            allow_future = True

    **Example myapp/urls.py**::

        from django.urls import path

        from myapp.views import ArticleMonthArchiveView

        urlpatterns = [

            # Example: /2012/08/

            path('<int:year>/<int:month>/',

                 ArticleMonthArchiveView.as_view(month_format='%m'),

                 name="archive_month_numeric"),

            # Example: /2012/aug/

            path('<int:year>/<str:month>/',

                 ArticleMonthArchiveView.as_view(),

                 name="archive_month"),

        ]

    **Example myapp/article_archive_month.html**:

    .. code-block:: html+django

        <ul>

            {% for article in object_list %}

                <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>

            {% endfor %}

        </ul>

        <p>

            {% if previous_month %}

                Previous Month: {{ previous_month|date:"F Y" }}

            {% endif %}

            {% if next_month %}

                Next Month: {{ next_month|date:"F Y" }}

            {% endif %}

        </p>

``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.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``.

    * The ``week_format`` attribute is a :func:`~time.strptime` format string

      used to parse the week number. The following values are supported:

      * ``'%U'``: Based on the United States week system where the week

        begins on Sunday. This is the default value.

      * ``'%W'``: Similar to ``'%U'``, except it assumes that the week

        begins on Monday. This is not the same as the ISO 8601 week number.

      * ``'%V'``: ISO 8601 week number where the week begins on Monday.

    **Example myapp/views.py**::

        from django.views.generic.dates import WeekArchiveView

        from myapp.models import Article

        class ArticleWeekArchiveView(WeekArchiveView):

            queryset = Article.objects.all()

            date_field = "pub_date"

            week_format = "%W"

            allow_future = True

    **Example myapp/urls.py**::

        from django.urls import path

        from myapp.views import ArticleWeekArchiveView

        urlpatterns = [

            # Example: /2012/week/23/

            path('<int:year>/week/<int:week>/',

                 ArticleWeekArchiveView.as_view(),

                 name="archive_week"),

        ]

    **Example myapp/article_archive_week.html**:

    .. code-block:: html+django

        <h1>Week {{ week|date:'W' }}</h1>

        <ul>

            {% for article in object_list %}

                <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>

            {% endfor %}

        </ul>

        <p>

            {% if previous_week %}

                Previous Week: {{ previous_week|date:"W" }} of year {{ previous_week|date:"Y" }}

            {% endif %}

            {% if previous_week and next_week %}--{% endif %}

            {% if next_week %}

                Next week: {{ next_week|date:"W" }} of year {{ next_week|date:"Y" }}

            {% endif %}

        </p>

    In this example, you are outputting the week number. Keep in mind that week

    numbers computed by the :tfilter:`date` template filter with the ``'W'``

    format character are not always the same as those computed by

    :func:`~time.strftime` and :func:`~time.strptime` with the ``'%W'`` format

    string. For year 2015, for example, week numbers output by :tfilter:`date`

    are higher by one compared to those output by :func:`~time.strftime`. There

    isn't an equivalent for the ``'%U'`` :func:`~time.strftime` format string

    in :tfilter:`date`. Therefore, you should avoid using :tfilter:`date` to

    generate URLs for ``WeekArchiveView``.

``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.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``.

    **Example myapp/views.py**::

        from django.views.generic.dates import DayArchiveView

        from myapp.models import Article

        class ArticleDayArchiveView(DayArchiveView):

            queryset = Article.objects.all()

            date_field = "pub_date"

            allow_future = True

    **Example myapp/urls.py**::

        from django.urls import path

        from myapp.views import ArticleDayArchiveView

        urlpatterns = [

            # Example: /2012/nov/10/

            path('<int:year>/<str:month>/<int:day>/',

                 ArticleDayArchiveView.as_view(),

                 name="archive_day"),

        ]

    **Example myapp/article_archive_day.html**:

    .. code-block:: html+django

        <h1>{{ day }}</h1>

        <ul>

            {% for article in object_list %}

                <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>

            {% endfor %}

        </ul>

        <p>

            {% if previous_day %}

                Previous Day: {{ previous_day }}

            {% endif %}

            {% if previous_day and next_day %}--{% endif %}

            {% if next_day %}

                Next Day: {{ next_day }}

            {% endif %}

        </p>

``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.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`

    **Notes**

    * Uses a default ``template_name_suffix`` of ``_archive_today``.

    **Example myapp/views.py**::

        from django.views.generic.dates import TodayArchiveView

        from myapp.models import Article

        class ArticleTodayArchiveView(TodayArchiveView):

            queryset = Article.objects.all()

            date_field = "pub_date"

            allow_future = True

    **Example myapp/urls.py**::

        from django.urls import path

        from myapp.views import ArticleTodayArchiveView

        urlpatterns = [

            path('today/',

                 ArticleTodayArchiveView.as_view(),

                 name="archive_today"),

        ]

    .. admonition:: Where is the example template for ``TodayArchiveView``?

        This view uses by default the same template as the

        :class:`~DayArchiveView`, which is in the previous example. If you need

        a different template, set the ``template_name`` attribute to be the

        name of the new template.

``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.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`

    **Context**

    * Includes the single object associated with the ``model`` specified in

      the ``DateDetailView``.

    **Notes**

    * Uses a default ``template_name_suffix`` of ``_detail``.

    **Example myapp/urls.py**::

        from django.urls import path

        from django.views.generic.dates import DateDetailView

        urlpatterns = [

            path('<int:year>/<str:month>/<int:day>/<int:pk>/',

                 DateDetailView.as_view(model=Article, date_field="pub_date"),

                 name="archive_date_detail"),

        ]

    **Example myapp/article_detail.html**:

    .. code-block:: html+django

        <h1>{{ object.title }}</h1>

.. note::

    All of the generic views listed above have matching ``Base`` views that

    only differ in that they do not include the

    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`

    (for the archive views) or

    :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`

    (for the :class:`DateDetailView`):

    .. class:: BaseArchiveIndexView

    .. class:: BaseYearArchiveView

    .. class:: BaseMonthArchiveView

    .. class:: BaseWeekArchiveView

    .. class:: BaseDayArchiveView

    .. class:: BaseTodayArchiveView

    .. class:: BaseDateDetailView