generic-date-based.txt

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

        .. versionadded:: 3.2

            Support for the ``'%V'`` week format was added.

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