| 1 |
====================== |
| 2 |
Multiple object mixins |
| 3 |
====================== |
| 4 |
|
| 5 |
``MultipleObjectMixin`` |
| 6 |
======================= |
| 7 |
|
| 8 |
.. class:: django.views.generic.list.MultipleObjectMixin |
| 9 |
|
| 10 |
A mixin that can be used to display a list of objects. |
| 11 |
|
| 12 |
If ``paginate_by`` is specified, Django will paginate the results returned |
| 13 |
by this. You can specify the page number in the URL in one of two ways: |
| 14 |
|
| 15 |
* Use the ``page`` parameter in the URLconf. For example, this is what |
| 16 |
your URLconf might look like:: |
| 17 |
|
| 18 |
path("objects/page<int:page>/", PaginatedView.as_view()), |
| 19 |
|
| 20 |
* Pass the page number via the ``page`` query-string parameter. For |
| 21 |
example, a URL would look like this: |
| 22 |
|
| 23 |
.. code-block:: text |
| 24 |
|
| 25 |
/objects/?page=3 |
| 26 |
|
| 27 |
These values and lists are 1-based, not 0-based, so the first page would be |
| 28 |
represented as page ``1``. |
| 29 |
|
| 30 |
For more on pagination, read the :doc:`pagination documentation |
| 31 |
</topics/pagination>`. |
| 32 |
|
| 33 |
As a special case, you are also permitted to use ``last`` as a value for |
| 34 |
``page``: |
| 35 |
|
| 36 |
.. code-block:: text |
| 37 |
|
| 38 |
/objects/?page=last |
| 39 |
|
| 40 |
This allows you to access the final page of results without first having to |
| 41 |
determine how many pages there are. |
| 42 |
|
| 43 |
Note that ``page`` *must* be either a valid page number or the value |
| 44 |
``last``; any other value for ``page`` will result in a 404 error. |
| 45 |
|
| 46 |
**Extends** |
| 47 |
|
| 48 |
* :class:`django.views.generic.base.ContextMixin` |
| 49 |
|
| 50 |
**Methods and Attributes** |
| 51 |
|
| 52 |
.. attribute:: allow_empty |
| 53 |
|
| 54 |
A boolean specifying whether to display the page if no objects are |
| 55 |
available. If this is ``False`` and no objects are available, the view |
| 56 |
will raise a 404 instead of displaying an empty page. By default, this |
| 57 |
is ``True``. |
| 58 |
|
| 59 |
.. attribute:: model |
| 60 |
|
| 61 |
The model that this view will display data for. Specifying ``model |
| 62 |
= Foo`` is effectively the same as specifying ``queryset = |
| 63 |
Foo.objects.all()``, where ``objects`` stands for ``Foo``’s |
| 64 |
:ref:`default manager <default-managers>`. |
| 65 |
|
| 66 |
.. attribute:: queryset |
| 67 |
|
| 68 |
A ``QuerySet`` that represents the objects. If provided, the value of |
| 69 |
``queryset`` supersedes the value provided for :attr:`model`. |
| 70 |
|
| 71 |
.. warning:: |
| 72 |
|
| 73 |
``queryset`` is a class attribute with a *mutable* value so care |
| 74 |
must be taken when using it directly. Before using it, either call |
| 75 |
its :meth:`~django.db.models.query.QuerySet.all` method or |
| 76 |
retrieve it with :meth:`get_queryset` which takes care of the |
| 77 |
cloning behind the scenes. |
| 78 |
|
| 79 |
.. attribute:: ordering |
| 80 |
|
| 81 |
A string or list of strings specifying the ordering to apply to the ``queryset``. |
| 82 |
Valid values are the same as those for :meth:`~django.db.models.query.QuerySet.order_by`. |
| 83 |
|
| 84 |
.. attribute:: paginate_by |
| 85 |
|
| 86 |
An integer specifying how many objects should be displayed per page. If |
| 87 |
this is given, the view will paginate objects with |
| 88 |
``paginate_by`` objects per page. The view will |
| 89 |
expect either a ``page`` query string parameter (via ``request.GET``) |
| 90 |
or a ``page`` variable specified in the URLconf. |
| 91 |
|
| 92 |
.. attribute:: paginate_orphans |
| 93 |
|
| 94 |
An integer specifying the number of "overflow" objects the last page |
| 95 |
can contain. This extends the :attr:`paginate_by` limit on the last |
| 96 |
page by up to ``paginate_orphans``, in order to keep the last page from |
| 97 |
having a very small number of objects. |
| 98 |
|
| 99 |
.. attribute:: page_kwarg |
| 100 |
|
| 101 |
A string specifying the name to use for the page parameter. |
| 102 |
The view will expect this parameter to be available either as a query |
| 103 |
string parameter (via ``request.GET``) or as a kwarg variable specified |
| 104 |
in the URLconf. Defaults to ``page``. |
| 105 |
|
| 106 |
.. attribute:: paginator_class |
| 107 |
|
| 108 |
The paginator class to be used for pagination. By default, |
| 109 |
:class:`django.core.paginator.Paginator` is used. If the custom paginator |
| 110 |
class doesn't have the same constructor interface as |
| 111 |
:class:`django.core.paginator.Paginator`, you will also need to |
| 112 |
provide an implementation for :meth:`get_paginator`. |
| 113 |
|
| 114 |
.. attribute:: context_object_name |
| 115 |
|
| 116 |
Designates the name of the variable to use in the context. |
| 117 |
|
| 118 |
.. method:: get_queryset() |
| 119 |
|
| 120 |
Get the list of items for this view. This must be an iterable and may |
| 121 |
be a queryset (in which queryset-specific behavior will be enabled). |
| 122 |
|
| 123 |
.. method:: get_ordering() |
| 124 |
|
| 125 |
Returns a string (or iterable of strings) that defines the ordering that |
| 126 |
will be applied to the ``queryset``. |
| 127 |
|
| 128 |
Returns :attr:`ordering` by default. |
| 129 |
|
| 130 |
.. method:: paginate_queryset(queryset, page_size) |
| 131 |
|
| 132 |
Returns a 4-tuple containing (``paginator``, ``page``, ``object_list``, |
| 133 |
``is_paginated``). |
| 134 |
|
| 135 |
Constructed by paginating ``queryset`` into pages of size ``page_size``. |
| 136 |
If the request contains a ``page`` argument, either as a captured URL |
| 137 |
argument or as a GET argument, ``object_list`` will correspond to the |
| 138 |
objects from that page. |
| 139 |
|
| 140 |
.. method:: get_paginate_by(queryset) |
| 141 |
|
| 142 |
Returns the number of items to paginate by, or ``None`` for no |
| 143 |
pagination. By default this returns the value of :attr:`paginate_by`. |
| 144 |
|
| 145 |
.. method:: get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True) |
| 146 |
|
| 147 |
Returns an instance of the paginator to use for this view. By default, |
| 148 |
instantiates an instance of :attr:`paginator_class`. |
| 149 |
|
| 150 |
.. method:: get_paginate_orphans() |
| 151 |
|
| 152 |
An integer specifying the number of "overflow" objects the last page |
| 153 |
can contain. By default this returns the value of |
| 154 |
:attr:`paginate_orphans`. |
| 155 |
|
| 156 |
.. method:: get_allow_empty() |
| 157 |
|
| 158 |
Return a boolean specifying whether to display the page if no objects |
| 159 |
are available. If this method returns ``False`` and no objects are |
| 160 |
available, the view will raise a 404 instead of displaying an empty |
| 161 |
page. By default, this is ``True``. |
| 162 |
|
| 163 |
.. method:: get_context_object_name(object_list) |
| 164 |
|
| 165 |
Return the context variable name that will be used to contain |
| 166 |
the list of data that this view is manipulating. If |
| 167 |
``object_list`` is a queryset of Django objects and |
| 168 |
:attr:`context_object_name` is not set, |
| 169 |
the context name will be the ``model_name`` of the model that |
| 170 |
the queryset is composed from, with postfix ``'_list'`` |
| 171 |
appended. For example, the model ``Article`` would have a |
| 172 |
context object named ``article_list``. |
| 173 |
|
| 174 |
.. method:: get_context_data(**kwargs) |
| 175 |
|
| 176 |
Returns context data for displaying the list of objects. |
| 177 |
|
| 178 |
**Context** |
| 179 |
|
| 180 |
* ``object_list``: The list of objects that this view is displaying. If |
| 181 |
``context_object_name`` is specified, that variable will also be set |
| 182 |
in the context, with the same value as ``object_list``. |
| 183 |
|
| 184 |
* ``is_paginated``: A boolean representing whether the results are |
| 185 |
paginated. Specifically, this is set to ``False`` if no page size has |
| 186 |
been specified, or if the available objects do not span multiple |
| 187 |
pages. |
| 188 |
|
| 189 |
* ``paginator``: An instance of |
| 190 |
:class:`django.core.paginator.Paginator`. If the page is not |
| 191 |
paginated, this context variable will be ``None``. |
| 192 |
|
| 193 |
* ``page_obj``: An instance of |
| 194 |
:class:`django.core.paginator.Page`. If the page is not paginated, |
| 195 |
this context variable will be ``None``. |
| 196 |
|
| 197 |
|
| 198 |
``MultipleObjectTemplateResponseMixin`` |
| 199 |
======================================= |
| 200 |
|
| 201 |
.. class:: django.views.generic.list.MultipleObjectTemplateResponseMixin |
| 202 |
|
| 203 |
A mixin class that performs template-based response rendering for views |
| 204 |
that operate upon a list of object instances. Requires that the view it is |
| 205 |
mixed with provides ``self.object_list``, the list of object instances that |
| 206 |
the view is operating on. ``self.object_list`` may be, but is not required |
| 207 |
to be, a :class:`~django.db.models.query.QuerySet`. |
| 208 |
|
| 209 |
**Extends** |
| 210 |
|
| 211 |
* :class:`~django.views.generic.base.TemplateResponseMixin` |
| 212 |
|
| 213 |
**Methods and Attributes** |
| 214 |
|
| 215 |
.. attribute:: template_name_suffix |
| 216 |
|
| 217 |
The suffix to append to the auto-generated candidate template name. |
| 218 |
Default suffix is ``_list``. |
| 219 |
|
| 220 |
.. method:: get_template_names() |
| 221 |
|
| 222 |
Returns a list of candidate template names. Returns the following list: |
| 223 |
|
| 224 |
* the value of ``template_name`` on the view (if provided) |
| 225 |
* ``<app_label>/<model_name><template_name_suffix>.html`` |