mirror of
https://github.com/django/django.git
synced 2024-12-27 03:25:58 +00:00
df41b5a05d
Thanks Aymeric Augustin for shepherding the DEP and patch review. Thanks Marten Kenbeek and Tim Graham for contributing to the code. Thanks Tom Christie, Shai Berger, and Tim Graham for the docs.
631 lines
20 KiB
Plaintext
631 lines
20 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.
|
|
|
|
.. 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.
|
|
|
|
**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`
|
|
* ``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
|