mirror of https://github.com/django/django.git
647 lines
21 KiB
Plaintext
647 lines
21 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.
|
|
|
|
* ``'%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
|