mirror of https://github.com/django/django.git
275 lines
9.2 KiB
Plaintext
275 lines
9.2 KiB
Plaintext
=================
|
|
Date-based mixins
|
|
=================
|
|
|
|
|
|
YearMixin
|
|
---------
|
|
|
|
.. class:: django.views.generic.dates.YearMixin
|
|
|
|
A mixin that can be used to retrieve and provide parsing information for a
|
|
year component of a date.
|
|
|
|
**Methods and Attributes**
|
|
|
|
.. attribute:: year_format
|
|
|
|
The :func:`~time.strftime` format to use when parsing the year.
|
|
By default, this is ``'%Y'``.
|
|
|
|
.. attribute:: year
|
|
|
|
**Optional** The value for the year (as a string). By default, set to
|
|
``None``, which means the year will be determined using other means.
|
|
|
|
.. method:: get_year_format()
|
|
|
|
Returns the :func:`~time.strftime` format to use when parsing the year. Returns
|
|
:attr:`YearMixin.year_format` by default.
|
|
|
|
.. method:: get_year()
|
|
|
|
Returns the year for which this view will display data. Tries the
|
|
following sources, in order:
|
|
|
|
* The value of the :attr:`YearMixin.year` attribute.
|
|
* The value of the `year` argument captured in the URL pattern
|
|
* The value of the `year` GET query argument.
|
|
|
|
Raises a 404 if no valid year specification can be found.
|
|
|
|
MonthMixin
|
|
----------
|
|
|
|
.. class:: django.views.generic.dates.MonthMixin
|
|
|
|
A mixin that can be used to retrieve and provide parsing information for a
|
|
month component of a date.
|
|
|
|
**Methods and Attributes**
|
|
|
|
.. attribute:: month_format
|
|
|
|
The :func:`~time.strftime` format to use when parsing the month. By default, this is
|
|
``'%b'``.
|
|
|
|
.. attribute:: month
|
|
|
|
**Optional** The value for the month (as a string). By default, set to
|
|
``None``, which means the month will be determined using other means.
|
|
|
|
.. method:: get_month_format()
|
|
|
|
Returns the :func:`~time.strftime` format to use when parsing the month. Returns
|
|
:attr:`MonthMixin.month_format` by default.
|
|
|
|
.. method:: get_month()
|
|
|
|
Returns the month for which this view will display data. Tries the
|
|
following sources, in order:
|
|
|
|
* The value of the :attr:`MonthMixin.month` attribute.
|
|
* The value of the `month` argument captured in the URL pattern
|
|
* The value of the `month` GET query argument.
|
|
|
|
Raises a 404 if no valid month specification can be found.
|
|
|
|
.. method:: get_next_month(date)
|
|
|
|
Returns a date object containing the first day of the month after the
|
|
date provided. Returns ``None`` if mixed with a view that sets
|
|
``allow_future = False``, and the next month is in the future. If
|
|
``allow_empty = False``, returns the next month that contains data.
|
|
|
|
.. method:: get_prev_month(date)
|
|
|
|
Returns a date object containing the first day of the month before the
|
|
date provided. If ``allow_empty = False``, returns the previous month
|
|
that contained data.
|
|
|
|
DayMixin
|
|
--------
|
|
|
|
.. class:: django.views.generic.dates.DayMixin
|
|
|
|
A mixin that can be used to retrieve and provide parsing information for a
|
|
day component of a date.
|
|
|
|
**Methods and Attributes**
|
|
|
|
.. attribute:: day_format
|
|
|
|
The :func:`~time.strftime` format to use when parsing the day. By default, this is
|
|
``'%d'``.
|
|
|
|
.. attribute:: day
|
|
|
|
**Optional** The value for the day (as a string). By default, set to
|
|
``None``, which means the day will be determined using other means.
|
|
|
|
.. method:: get_day_format()
|
|
|
|
Returns the :func:`~time.strftime` format to use when parsing the day. Returns
|
|
:attr:`DayMixin.day_format` by default.
|
|
|
|
.. method:: get_day()
|
|
|
|
Returns the day for which this view will display data. Tries the
|
|
following sources, in order:
|
|
|
|
* The value of the :attr:`DayMixin.day` attribute.
|
|
* The value of the `day` argument captured in the URL pattern
|
|
* The value of the `day` GET query argument.
|
|
|
|
Raises a 404 if no valid day specification can be found.
|
|
|
|
.. method:: get_next_day(date)
|
|
|
|
Returns a date object containing the next day after the date provided.
|
|
Returns ``None`` if mixed with a view that sets ``allow_future = False``,
|
|
and the next day is in the future. If ``allow_empty = False``, returns
|
|
the next day that contains data.
|
|
|
|
.. method:: get_prev_day(date)
|
|
|
|
Returns a date object containing the previous day. If
|
|
``allow_empty = False``, returns the previous day that contained data.
|
|
|
|
WeekMixin
|
|
---------
|
|
|
|
.. class:: django.views.generic.dates.WeekMixin
|
|
|
|
A mixin that can be used to retrieve and provide parsing information for a
|
|
week component of a date.
|
|
|
|
**Methods and Attributes**
|
|
|
|
.. attribute:: week_format
|
|
|
|
The :func:`~time.strftime` format to use when parsing the week. By default, this is
|
|
``'%U'``.
|
|
|
|
.. attribute:: week
|
|
|
|
**Optional** The value for the week (as a string). By default, set to
|
|
``None``, which means the week will be determined using other means.
|
|
|
|
.. method:: get_week_format()
|
|
|
|
Returns the :func:`~time.strftime` format to use when parsing the week. Returns
|
|
:attr:`WeekMixin.week_format` by default.
|
|
|
|
.. method:: get_week()
|
|
|
|
Returns the week for which this view will display data. Tries the
|
|
following sources, in order:
|
|
|
|
* The value of the :attr:`WeekMixin.week` attribute.
|
|
* The value of the `week` argument captured in the URL pattern
|
|
* The value of the `week` GET query argument.
|
|
|
|
Raises a 404 if no valid week specification can be found.
|
|
|
|
|
|
DateMixin
|
|
---------
|
|
|
|
.. class:: django.views.generic.dates.DateMixin
|
|
|
|
A mixin class providing common behavior for all date-based views.
|
|
|
|
**Methods and Attributes**
|
|
|
|
.. attribute:: date_field
|
|
|
|
The name of the ``DateField`` or ``DateTimeField`` in the
|
|
``QuerySet``'s model that the date-based archive should use to
|
|
determine the objects on the page.
|
|
|
|
When :doc:`time zone support </topics/i18n/timezones>` is enabled and
|
|
``date_field`` is a ``DateTimeField``, dates are assumed to be in the
|
|
current time zone. Otherwise, the queryset could include objects from
|
|
the previous or the next day in the end user's time zone.
|
|
|
|
.. warning::
|
|
|
|
In this situation, if you have implemented per-user time zone
|
|
selection, the same URL may show a different set of objects,
|
|
depending on the end user's time zone. To avoid this, you should
|
|
use a ``DateField`` as the ``date_field`` attribute.
|
|
|
|
.. attribute:: allow_future
|
|
|
|
A boolean specifying whether to include "future" objects on this page,
|
|
where "future" means objects in which the field specified in
|
|
``date_field`` is greater than the current date/time. By default, this
|
|
is ``False``.
|
|
|
|
.. method:: get_date_field()
|
|
|
|
Returns the name of the field that contains the date data that this
|
|
view will operate on. Returns :attr:`DateMixin.date_field` by default.
|
|
|
|
.. method:: get_allow_future()
|
|
|
|
Determine whether to include "future" objects on this page, where
|
|
"future" means objects in which the field specified in ``date_field``
|
|
is greater than the current date/time. Returns
|
|
:attr:`DateMixin.allow_future` by default.
|
|
|
|
BaseDateListView
|
|
----------------
|
|
|
|
.. class:: django.views.generic.dates.BaseDateListView
|
|
|
|
A base class that provides common behavior for all date-based views. There
|
|
won't normally be a reason to instantiate
|
|
:class:`~django.views.generic.dates.BaseDateListView`; instantiate one of
|
|
the subclasses instead.
|
|
|
|
While this view (and it's subclasses) are executing, ``self.object_list``
|
|
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
|
|
available.
|
|
|
|
**Mixins**
|
|
|
|
* :class:`~django.views.generic.dates.DateMixin`
|
|
* :class:`~django.views.generic.list.MultipleObjectMixin`
|
|
|
|
**Methods and Attributes**
|
|
|
|
.. attribute:: allow_empty
|
|
|
|
A boolean specifying whether to display the page if no objects are
|
|
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
|
|
is ``False``.
|
|
|
|
.. method:: get_dated_items():
|
|
|
|
Returns a 3-tuple containing (``date_list``, ``object_list``,
|
|
``extra_context``).
|
|
|
|
``date_list`` is the list of dates for which data is available.
|
|
``object_list`` is the list of objects. ``extra_context`` is a
|
|
dictionary of context data that will be added to any context data
|
|
provided by the
|
|
:class:`~django.views.generic.list.MultipleObjectMixin`.
|
|
|
|
.. method:: get_dated_queryset(**lookup)
|
|
|
|
Returns a queryset, filtered using the query arguments defined by
|
|
``lookup``. Enforces any restrictions on the queryset, such as
|
|
``allow_empty`` and ``allow_future``.
|
|
|
|
.. method:: get_date_list(queryset, date_type)
|
|
|
|
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.
|
|
See :meth:`~django.db.models.query.QuerySet.dates()` for the
|
|
ways that the ``date_type`` argument can be used.
|