innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Updated docs for dates generic views. 

Fixes #18245. Refs #3542.
This commit is contained in:
Aymeric Augustin 2012-09-08 12:20:20 -04:00
parent 3da43c1111
commit 7207327dd3
3 changed files with 196 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
django/views/generic/dates.py
View File

@ -372,6 +372,9 @@ class BaseDateListView(MultipleObjectMixin, DateMixin, View):
return qs return qs
def get_date_list_period(self): def get_date_list_period(self):
"""
Get the aggregation period for the list of dates: 'year', 'month', or 'day'.
"""
return self.date_list_period return self.date_list_period
def get_date_list(self, queryset, date_type=None): def get_date_list(self, queryset, date_type=None):

128
docs/ref/class-based-views/generic-date-based.txt
View File

@ -2,13 +2,15 @@
Generic date views Generic date views
================== ==================
Date-based generic views (in the module :mod:`django.views.generic.dates`) .. module:: django.views.generic.dates
are views for displaying drilldown pages for date-based data.
Date-based generic views, provided in :mod:`django.views.generic.dates`, are
views for displaying drilldown pages for date-based data.
ArchiveIndexView ArchiveIndexView
---------------- ----------------
.. class:: django.views.generic.dates.ArchiveIndexView .. class:: ArchiveIndexView
A top-level index page showing the "latest" objects, by date. Objects with 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 a date in the *future* are not included unless you set ``allow_future`` to
@ -36,7 +38,7 @@ ArchiveIndexView
YearArchiveView YearArchiveView
--------------- ---------------
.. class:: django.views.generic.dates.YearArchiveView .. class:: YearArchiveView
A yearly archive page showing all available months in a given year. Objects 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 with a date in the *future* are not displayed unless you set
@ -58,13 +60,15 @@ YearArchiveView
A boolean specifying whether to retrieve the full list of objects for 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 this year and pass those to the template. If ``True``, the list of
objects will be made available to the context. By default, this is 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``. ``False``.
.. method:: get_make_object_list() .. method:: get_make_object_list()
Determine if an object list will be returned as part of the context. If Determine if an object list will be returned as part of the context.
``False``, the ``None`` queryset will be used as the object list. Returns :attr:`~YearArchiveView.make_object_list` by default.
**Context** **Context**
@ -80,16 +84,18 @@ YearArchiveView
:class:`datetime.datetime<python:datetime.datetime>` objects, in :class:`datetime.datetime<python:datetime.datetime>` objects, in
ascending order. ascending order.
* ``year``: A :class:`datetime.date<python:datetime.date>` object * ``year``: A :class:`~datetime.date` object
representing the given year. representing the given year.
* ``next_year``: A :class:`datetime.date<python:datetime.date>` object * ``next_year``: A :class:`~datetime.date` object
representing the first day of the next year. If the next year is in the representing the first day of the next year, according to
future, this will be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_year``: A :class:`datetime.date<python:datetime.date>` object * ``previous_year``: A :class:`~datetime.date` object
representing the first day of the previous year. Unlike ``next_year``, representing the first day of the previous year, according to
this will never be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes** **Notes**
@ -98,7 +104,7 @@ YearArchiveView
MonthArchiveView MonthArchiveView
---------------- ----------------
.. class:: django.views.generic.dates.MonthArchiveView .. class:: MonthArchiveView
A monthly archive page showing all objects in a given month. Objects with a 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 date in the *future* are not displayed unless you set ``allow_future`` to
@ -131,16 +137,18 @@ MonthArchiveView
:class:`datetime.datetime<python:datetime.datetime>` objects, in :class:`datetime.datetime<python:datetime.datetime>` objects, in
ascending order. ascending order.
* ``month``: A :class:`datetime.date<python:datetime.date>` object * ``month``: A :class:`~datetime.date` object
representing the given month. representing the given month.
* ``next_month``: A :class:`datetime.date<python:datetime.date>` object * ``next_month``: A :class:`~datetime.date` object
representing the first day of the next month. If the next month is in the representing the first day of the next month, according to
future, this will be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_month``: A :class:`datetime.date<python:datetime.date>` object * ``previous_month``: A :class:`~datetime.date` object
representing the first day of the previous month. Unlike ``next_month``, representing the first day of the previous month, according to
this will never be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes** **Notes**
@ -149,7 +157,7 @@ MonthArchiveView
WeekArchiveView WeekArchiveView
--------------- ---------------
.. class:: django.views.generic.dates.WeekArchiveView .. class:: WeekArchiveView
A weekly archive page showing all objects in a given week. Objects with a 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 date in the *future* are not displayed unless you set ``allow_future`` to
@ -175,16 +183,18 @@ WeekArchiveView
:class:`~django.views.generic.dates.BaseDateListView`), the template's :class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be: context will be:
* ``week``: A :class:`datetime.date<python:datetime.date>` object * ``week``: A :class:`~datetime.date` object
representing the first day of the given week. representing the first day of the given week.
* ``next_week``: A :class:`datetime.date<python:datetime.date>` object * ``next_week``: A :class:`~datetime.date` object
representing the first day of the next week. If the next week is in the representing the first day of the next week, according to
future, this will be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_week``: A :class:`datetime.date<python:datetime.date>` object * ``previous_week``: A :class:`~datetime.date` object
representing the first day of the previous week. Unlike ``next_week``, representing the first day of the previous week, according to
this will never be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes** **Notes**
@ -193,7 +203,7 @@ WeekArchiveView
DayArchiveView DayArchiveView
-------------- --------------
.. class:: django.views.generic.dates.DayArchiveView .. class:: DayArchiveView
A day archive page showing all objects in a given day. Days in the future 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, throw a 404 error, regardless of whether any objects exist for future days,
@ -220,24 +230,28 @@ DayArchiveView
:class:`~django.views.generic.dates.BaseDateListView`), the template's :class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be: context will be:
* ``day``: A :class:`datetime.date<python:datetime.date>` object * ``day``: A :class:`~datetime.date` object
representing the given day. representing the given day.
* ``next_day``: A :class:`datetime.date<python:datetime.date>` object * ``next_day``: A :class:`~datetime.date` object
representing the next day. If the next day is in the future, this will be representing the next day, according to
``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_day``: A :class:`datetime.date<python:datetime.date>` object * ``previous_day``: A :class:`~datetime.date` object
representing the previous day. Unlike ``next_day``, this will never be representing the previous day, according to
``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``next_month``: A :class:`datetime.date<python:datetime.date>` object * ``next_month``: A :class:`~datetime.date` object
representing the first day of the next month. If the next month is in the representing the first day of the next month, according to
future, this will be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
* ``previous_month``: A :class:`datetime.date<python:datetime.date>` object * ``previous_month``: A :class:`~datetime.date` object
representing the first day of the previous month. Unlike ``next_month``, representing the first day of the previous month, according to
this will never be ``None``. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
**Notes** **Notes**
@ -246,7 +260,7 @@ DayArchiveView
TodayArchiveView TodayArchiveView
---------------- ----------------
.. class:: django.views.generic.dates.TodayArchiveView .. class:: TodayArchiveView
A day archive page showing all objects for *today*. This is exactly the A day archive page showing all objects for *today*. This is exactly the
same as :class:`django.views.generic.dates.DayArchiveView`, except today's same as :class:`django.views.generic.dates.DayArchiveView`, except today's
@ -271,7 +285,7 @@ TodayArchiveView
DateDetailView DateDetailView
-------------- --------------
.. class:: django.views.generic.dates.DateDetailView .. class:: DateDetailView
A page representing an individual object. If the object has a date value in 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 the future, the view will throw a 404 error by default, unless you set
@ -293,6 +307,22 @@ DateDetailView
.. note:: .. note::
All of the generic views listed above have matching Base* views that only All of the generic views listed above have matching ``Base`` views that
differ in that the they do not include the only differ in that the they do not include the
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`. :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`:
.. class:: BaseArchiveIndexView
.. class:: BaseYearArchiveView
.. class:: BaseMonthArchiveView
.. class:: BaseWeekArchiveView
.. class:: BaseDayArchiveView
.. class:: BaseTodayArchiveView
.. class:: BaseDateDetailView

173
docs/ref/class-based-views/mixins-date-based.txt
View File

@ -2,11 +2,12 @@
Date-based mixins Date-based mixins
================= =================
.. currentmodule:: django.views.generic.dates
YearMixin YearMixin
--------- ---------
.. class:: django.views.generic.dates.YearMixin .. class:: YearMixin
A mixin that can be used to retrieve and provide parsing information for a A mixin that can be used to retrieve and provide parsing information for a
year component of a date. year component of a date.
@ -20,29 +21,45 @@ YearMixin
.. attribute:: year .. attribute:: year
**Optional** The value for the year (as a string). By default, set to **Optional** The value for the year, as a string. By default, set to
``None``, which means the year will be determined using other means. ``None``, which means the year will be determined using other means.
.. method:: get_year_format() .. method:: get_year_format()
Returns the :func:`~time.strftime` format to use when parsing the year. Returns Returns the :func:`~time.strftime` format to use when parsing the
:attr:`YearMixin.year_format` by default. year. Returns :attr:`~YearMixin.year_format` by default.
.. method:: get_year() .. method:: get_year()
Returns the year for which this view will display data. Tries the Returns the year for which this view will display data, as a string.
following sources, in order: Tries the following sources, in order:
* The value of the :attr:`YearMixin.year` attribute. * The value of the :attr:`YearMixin.year` attribute.
* The value of the `year` argument captured in the URL pattern * The value of the `year` argument captured in the URL pattern.
* The value of the `year` GET query argument. * The value of the `year` GET query argument.
Raises a 404 if no valid year specification can be found. Raises a 404 if no valid year specification can be found.
.. method:: get_next_year(date)
Returns a date object containing the first day of the year after the
date provided. This function can also return ``None`` or raise an
:class:`~django.http.Http404` exception, depending on the values of
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
.. method:: get_previous_year(date)
Returns a date object containing the first day of the year before the
date provided. This function can also return ``None`` or raise an
:class:`~django.http.Http404` exception, depending on the values of
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
MonthMixin MonthMixin
---------- ----------
.. class:: django.views.generic.dates.MonthMixin .. class:: MonthMixin
A mixin that can be used to retrieve and provide parsing information for a A mixin that can be used to retrieve and provide parsing information for a
month component of a date. month component of a date.
@ -51,26 +68,26 @@ MonthMixin
.. attribute:: month_format .. attribute:: month_format
The :func:`~time.strftime` format to use when parsing the month. By default, this is The :func:`~time.strftime` format to use when parsing the month. By
``'%b'``. default, this is ``'%b'``.
.. attribute:: month .. attribute:: month
**Optional** The value for the month (as a string). By default, set to **Optional** The value for the month, as a string. By default, set to
``None``, which means the month will be determined using other means. ``None``, which means the month will be determined using other means.
.. method:: get_month_format() .. method:: get_month_format()
Returns the :func:`~time.strftime` format to use when parsing the month. Returns Returns the :func:`~time.strftime` format to use when parsing the
:attr:`MonthMixin.month_format` by default. month. Returns :attr:`~MonthMixin.month_format` by default.
.. method:: get_month() .. method:: get_month()
Returns the month for which this view will display data. Tries the Returns the month for which this view will display data, as a string.
following sources, in order: Tries the following sources, in order:
* The value of the :attr:`MonthMixin.month` attribute. * The value of the :attr:`MonthMixin.month` attribute.
* The value of the `month` argument captured in the URL pattern * The value of the `month` argument captured in the URL pattern.
* The value of the `month` GET query argument. * The value of the `month` GET query argument.
Raises a 404 if no valid month specification can be found. Raises a 404 if no valid month specification can be found.
@ -78,20 +95,23 @@ MonthMixin
.. method:: get_next_month(date) .. method:: get_next_month(date)
Returns a date object containing the first day of the month after the Returns a date object containing the first day of the month after the
date provided. Returns ``None`` if mixed with a view that sets date provided. This function can also return ``None`` or raise an
``allow_future = False``, and the next month is in the future. If :class:`~django.http.Http404` exception, depending on the values of
``allow_empty = False``, returns the next month that contains data. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
.. method:: get_prev_month(date) .. method:: get_prev_month(date)
Returns a date object containing the first day of the month before the Returns a date object containing the first day of the month before the
date provided. If ``allow_empty = False``, returns the previous month date provided. This function can also return ``None`` or raise an
that contained data. :class:`~django.http.Http404` exception, depending on the values of
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
DayMixin DayMixin
-------- --------
.. class:: django.views.generic.dates.DayMixin .. class:: DayMixin
A mixin that can be used to retrieve and provide parsing information for a A mixin that can be used to retrieve and provide parsing information for a
day component of a date. day component of a date.
@ -100,46 +120,50 @@ DayMixin
.. attribute:: day_format .. attribute:: day_format
The :func:`~time.strftime` format to use when parsing the day. By default, this is The :func:`~time.strftime` format to use when parsing the day. By
``'%d'``. default, this is ``'%d'``.
.. attribute:: day .. attribute:: day
**Optional** The value for the day (as a string). By default, set to **Optional** The value for the day, as a string. By default, set to
``None``, which means the day will be determined using other means. ``None``, which means the day will be determined using other means.
.. method:: get_day_format() .. method:: get_day_format()
Returns the :func:`~time.strftime` format to use when parsing the day. Returns Returns the :func:`~time.strftime` format to use when parsing the day.
:attr:`DayMixin.day_format` by default. Returns :attr:`~DayMixin.day_format` by default.
.. method:: get_day() .. method:: get_day()
Returns the day for which this view will display data. Tries the Returns the day for which this view will display data, as a string.
following sources, in order: Tries the following sources, in order:
* The value of the :attr:`DayMixin.day` attribute. * The value of the :attr:`DayMixin.day` attribute.
* The value of the `day` argument captured in the URL pattern * The value of the `day` argument captured in the URL pattern.
* The value of the `day` GET query argument. * The value of the `day` GET query argument.
Raises a 404 if no valid day specification can be found. Raises a 404 if no valid day specification can be found.
.. method:: get_next_day(date) .. method:: get_next_day(date)
Returns a date object containing the next day after the date provided. Returns a date object containing the next valid day after the date
Returns ``None`` if mixed with a view that sets ``allow_future = False``, provided. This function can also return ``None`` or raise an
and the next day is in the future. If ``allow_empty = False``, returns :class:`~django.http.Http404` exception, depending on the values of
the next day that contains data. :attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
.. method:: get_prev_day(date) .. method:: get_prev_day(date)
Returns a date object containing the previous day. If Returns a date object containing the previous valid day. This function
``allow_empty = False``, returns the previous day that contained data. can also return ``None`` or raise an :class:`~django.http.Http404`
exception, depending on the values of
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
WeekMixin WeekMixin
--------- ---------
.. class:: django.views.generic.dates.WeekMixin .. class:: WeekMixin
A mixin that can be used to retrieve and provide parsing information for a A mixin that can be used to retrieve and provide parsing information for a
week component of a date. week component of a date.
@ -148,23 +172,24 @@ WeekMixin
.. attribute:: week_format .. attribute:: week_format
The :func:`~time.strftime` format to use when parsing the week. By default, this is The :func:`~time.strftime` format to use when parsing the week. By
``'%U'``. default, this is ``'%U'``, which means the week starts on Sunday. Set
it to ``'%W'`` if your week starts on Monday.
.. attribute:: week .. attribute:: week
**Optional** The value for the week (as a string). By default, set to **Optional** The value for the week, as a string. By default, set to
``None``, which means the week will be determined using other means. ``None``, which means the week will be determined using other means.
.. method:: get_week_format() .. method:: get_week_format()
Returns the :func:`~time.strftime` format to use when parsing the week. Returns Returns the :func:`~time.strftime` format to use when parsing the
:attr:`WeekMixin.week_format` by default. week. Returns :attr:`~WeekMixin.week_format` by default.
.. method:: get_week() .. method:: get_week()
Returns the week for which this view will display data. Tries the Returns the week for which this view will display data, as a string.
following sources, in order: Tries the following sources, in order:
* The value of the :attr:`WeekMixin.week` attribute. * The value of the :attr:`WeekMixin.week` attribute.
* The value of the `week` argument captured in the URL pattern * The value of the `week` argument captured in the URL pattern
@ -172,11 +197,26 @@ WeekMixin
Raises a 404 if no valid week specification can be found. Raises a 404 if no valid week specification can be found.
.. method:: get_next_week(date)
Returns a date object containing the first day of the week after the
date provided. This function can also return ``None`` or raise an
:class:`~django.http.Http404` exception, depending on the values of
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
.. method:: get_prev_week(date)
Returns a date object containing the first day of the week before the
date provided. This function can also return ``None`` or raise an
:class:`~django.http.Http404` exception, depending on the values of
:attr:`~BaseDateListView.allow_empty` and
:attr:`~DateMixin.allow_future`.
DateMixin DateMixin
--------- ---------
.. class:: django.views.generic.dates.DateMixin .. class:: DateMixin
A mixin class providing common behavior for all date-based views. A mixin class providing common behavior for all date-based views.
@ -186,7 +226,7 @@ DateMixin
The name of the ``DateField`` or ``DateTimeField`` in the The name of the ``DateField`` or ``DateTimeField`` in the
``QuerySet``'s model that the date-based archive should use to ``QuerySet``'s model that the date-based archive should use to
determine the objects on the page. determine the list of objects to display on the page.
When :doc:`time zone support </topics/i18n/timezones>` is enabled and When :doc:`time zone support </topics/i18n/timezones>` is enabled and
``date_field`` is a ``DateTimeField``, dates are assumed to be in the ``date_field`` is a ``DateTimeField``, dates are assumed to be in the
@ -210,26 +250,26 @@ DateMixin
.. method:: get_date_field() .. method:: get_date_field()
Returns the name of the field that contains the date data that this Returns the name of the field that contains the date data that this
view will operate on. Returns :attr:`DateMixin.date_field` by default. view will operate on. Returns :attr:`~DateMixin.date_field` by default.
.. method:: get_allow_future() .. method:: get_allow_future()
Determine whether to include "future" objects on this page, where Determine whether to include "future" objects on this page, where
"future" means objects in which the field specified in ``date_field`` "future" means objects in which the field specified in ``date_field``
is greater than the current date/time. Returns is greater than the current date/time. Returns
:attr:`DateMixin.allow_future` by default. :attr:`~DateMixin.allow_future` by default.
BaseDateListView BaseDateListView
---------------- ----------------
.. class:: django.views.generic.dates.BaseDateListView .. class:: BaseDateListView
A base class that provides common behavior for all date-based views. There A base class that provides common behavior for all date-based views. There
won't normally be a reason to instantiate won't normally be a reason to instantiate
:class:`~django.views.generic.dates.BaseDateListView`; instantiate one of :class:`~django.views.generic.dates.BaseDateListView`; instantiate one of
the subclasses instead. the subclasses instead.
While this view (and it's subclasses) are executing, ``self.object_list`` While this view (and its subclasses) are executing, ``self.object_list``
will contain the list of objects that the view is operating upon, and will contain the list of objects that the view is operating upon, and
``self.date_list`` will contain the list of dates for which data is ``self.date_list`` will contain the list of dates for which data is
available. available.
@ -245,10 +285,18 @@ BaseDateListView
A boolean specifying whether to display the page if no objects are A boolean specifying whether to display the page if no objects are
available. If this is ``True`` and no objects are available, the view available. If this is ``True`` and no objects are available, the view
will display an empty page instead of raising a 404. By default, this will display an empty page instead of raising a 404.
is ``False``.
.. method:: get_dated_items(): This is identical to :attr:`MultipleObjectMixin.allow_empty`, except
for the default value, which is ``False``.
.. attribute:: date_list_period
**Optional** A string defining the aggregation period for
``date_list``. It must be one of ``'year'`` (default), ``'month'``, or
``'day'``.
.. method:: get_dated_items()
Returns a 3-tuple containing (``date_list``, ``object_list``, Returns a 3-tuple containing (``date_list``, ``object_list``,
``extra_context``). ``extra_context``).
@ -265,10 +313,17 @@ BaseDateListView
``lookup``. Enforces any restrictions on the queryset, such as ``lookup``. Enforces any restrictions on the queryset, such as
``allow_empty`` and ``allow_future``. ``allow_empty`` and ``allow_future``.
.. method:: get_date_list(queryset, date_type) .. method:: get_date_list_period()
Returns the list of dates of type ``date_type`` for which Returns the aggregation period for ``date_list``. Returns
``queryset`` contains entries. For example, ``get_date_list(qs, :attr:`~BaseDateListView.date_list_period` by default.
'year')`` will return the list of years for which ``qs`` has entries.
See :meth:`~django.db.models.query.QuerySet.dates()` for the .. method:: get_date_list(queryset, date_type=None)
ways that the ``date_type`` argument can be used.
Returns the list of dates of type ``date_type`` for which ``queryset``
contains entries. For example, ``get_date_list(qs, 'year')`` will
return the list of years for which ``qs`` has entries. If
``date_type`` isn't provided, the result of
:meth:`BaseDateListView.get_date_list_period` is used. See
:meth:`~django.db.models.query.QuerySet.dates()` for the ways that the
``date_type`` argument can be used.