================== 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.core.urlresolvers 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.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. **Example views.py**:: from django.conf.urls import patterns, url from django.views.generic.dates import ArchiveIndexView from myapp.models import Article urlpatterns = patterns('', url(r'^archive/$', ArchiveIndexView.as_view(model=Article, date_field="pub_date"), name="article_archive"), ) **Example myapp/article_archive.html**: .. code-block:: html+django 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.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` object 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. .. versionchanged:: 1.5 Previously, this returned a string. * ``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`. .. versionadded:: 1.5 * ``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`. .. versionadded:: 1.5 **Notes** * Uses a default ``template_name_suffix`` of ``_archive_year``. **Example 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 urls.py**:: from django.conf.urls import patterns, url from myapp.views import ArticleYearArchiveView urlpatterns = patterns('', url(r'^(?P\d{4})/$', ArticleYearArchiveView.as_view(), name="article_year_archive"), ) **Example myapp/article_archive_year.html**: .. code-block:: html+django
    {% for date in date_list %}
  • {{ date|date }}
    • {% endfor %}

All Articles for {{ year|date:"Y" }}

{% for obj in object_list %}

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

{% endfor %}
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` 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 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" make_object_list = True allow_future = True **Example urls.py**:: from django.conf.urls import patterns, url from myapp.views import ArticleMonthArchiveView urlpatterns = patterns('', # Example: /2012/aug/ url(r'^(?P\d{4})/(?P[-\w]+)/$', ArticleMonthArchiveView.as_view(), name="archive_month"), # Example: /2012/08/ url(r'^(?P\d{4})/(?P\d+)/$', ArticleMonthArchiveView.as_view(month_format='%m'), name="archive_month_numeric"), ) **Example myapp/article_archive_month.html**: .. code-block:: html+django
    {% for article in object_list %}
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • {% endfor %}

{% if previous_month %} Previous Month: {{ previous_month|date:"F Y" }} {% endif %} {% if next_month %} Next Month: {{ next_month|date:"F Y" }} {% endif %}

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``. **Example 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" make_object_list = True week_format = "%W" allow_future = True **Example urls.py**:: from django.conf.urls import patterns, url from myapp.views import ArticleWeekArchiveView urlpatterns = patterns('', # Example: /2012/week/23/ url(r'^(?P\d{4})/week/(?P\d+)/$', ArticleWeekArchiveView.as_view(), name="archive_week"), ) **Example myapp/article_archive_week.html**: .. code-block:: html+django

Week {{ week|date:'W' }}

    {% for article in object_list %}
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • {% endfor %}

{% if previous_week %} Previous Week: {{ previous_week|date:"F Y" }} {% endif %} {% if previous_week and next_week %}--{% endif %} {% if next_week %} Next week: {{ next_week|date:"F Y" }} {% endif %}

In this example, you are outputting the week number. The default ``week_format`` in the ``WeekArchiveView`` uses week format ``'%U'`` which is based on the United States week system where the week begins on a Sunday. The ``'%W'`` format uses the ISO week format and its week begins on a Monday. The ``'%W'`` format is the same in both the :func:`~time.strftime` and the :tfilter:`date`. However, the :tfilter:`date` template filter does not have an equivalent output format that supports the US based week system. The :tfilter:`date` filter ``'%U'`` outputs the number of seconds since the Unix epoch. 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``. **Example 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" make_object_list = True allow_future = True **Example urls.py**:: from django.conf.urls import patterns, url from myapp.views import ArticleDayArchiveView urlpatterns = patterns('', # Example: /2012/nov/10/ url(r'^(?P\d{4})/(?P[-\w]+)/(?P\d+)/$', ArticleDayArchiveView.as_view(), name="archive_day"), ) **Example myapp/article_archive_day.html**: .. code-block:: html+django

{{ day }}

    {% for article in object_list %}
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • {% endfor %}

{% if previous_day %} Previous Day: {{ previous_day }} {% endif %} {% if previous_day and next_day %}--{% endif %} {% if next_day %} Next Day: {{ next_day }} {% endif %}

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` **Notes** * Uses a default ``template_name_suffix`` of ``_archive_today``. **Example 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" make_object_list = True allow_future = True **Example urls.py**:: from django.conf.urls import patterns, url from myapp.views import ArticleTodayArchiveView urlpatterns = patterns('', url(r'^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.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` * ``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 urls.py**:: from django.conf.urls import patterns, url from django.views.generic.dates import DateDetailView urlpatterns = patterns('', url(r'^(?P\d+)/(?P[-\w]+)/(?P\d+)/(?P\d+)/$', DateDetailView.as_view(model=Article, date_field="pub_date"), name="archive_date_detail"), ) **Example myapp/article_detail.html**: .. code-block:: html+django

{{ object.title }}

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