Debian Codegraph @

docs/ref/class-based-views/mixins-multiple-object.txt

raw
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``