--- title: "Multiple object mixins" version: 5.2 locale: en source: https://docs.djangoproject.com/en/5.2/ref/class-based-views/mixins-multiple-object/ canonical: https://djangodocs.dev/en/5.2/ref/class-based-views/mixins-multiple-object/ --- # Multiple object mixins ## `MultipleObjectMixin` #### `class django.views.generic.list.MultipleObjectMixin` A mixin that can be used to display a list of objects. If `paginate_by` is specified, Django will paginate the results returned by this. You can specify the page number in the URL in one of two ways: - Use the `page` parameter in the URLconf. For example, this is what your URLconf might look like: ``` path("objects/page/", PaginatedView.as_view()), ``` - Pass the page number via the `page` query-string parameter. For example, a URL would look like this: ```text /objects/?page=3 ``` These values and lists are 1-based, not 0-based, so the first page would be represented as page `1`. For more on pagination, read the [pagination documentation](/en/5.2/topics/pagination/). As a special case, you are also permitted to use `last` as a value for `page`: ```text /objects/?page=last ``` This allows you to access the final page of results without first having to determine how many pages there are. Note that `page` *must* be either a valid page number or the value `last`; any other value for `page` will result in a 404 error. **Extends** - [`django.views.generic.base.ContextMixin`](/en/5.2/ref/class-based-views/mixins-simple/#django.views.generic.base.ContextMixin) **Methods and Attributes** #### `allow_empty` A boolean specifying whether to display the page if no objects are available. If this is `False` and no objects are available, the view will raise a 404 instead of displaying an empty page. By default, this is `True`. #### `model` The model that this view will display data for. Specifying `model = Foo` is effectively the same as specifying `queryset = Foo.objects.all()`, where `objects` stands for `Foo`’s [default manager](/en/5.2/topics/db/managers/#default-managers). #### `queryset` A `QuerySet` that represents the objects. If provided, the value of `queryset` supersedes the value provided for [`model`](#django.views.generic.list.MultipleObjectMixin.model). > **Warning** > > `queryset` is a class attribute with a *mutable* value so care > must be taken when using it directly. Before using it, either call > its [`all()`](/en/5.2/ref/models/querysets/#django.db.models.query.QuerySet.all) method or > retrieve it with [`get_queryset()`](#django.views.generic.list.MultipleObjectMixin.get_queryset) which takes care of the > cloning behind the scenes. #### `ordering` A string or list of strings specifying the ordering to apply to the `queryset`. Valid values are the same as those for [`order_by()`](/en/5.2/ref/models/querysets/#django.db.models.query.QuerySet.order_by). #### `paginate_by` An integer specifying how many objects should be displayed per page. If this is given, the view will paginate objects with `paginate_by` objects per page. The view will expect either a `page` query string parameter (via `request.GET`) or a `page` variable specified in the URLconf. #### `paginate_orphans` An integer specifying the number of “overflow” objects the last page can contain. This extends the [`paginate_by`](#django.views.generic.list.MultipleObjectMixin.paginate_by) limit on the last page by up to `paginate_orphans`, in order to keep the last page from having a very small number of objects. #### `page_kwarg` A string specifying the name to use for the page parameter. The view will expect this parameter to be available either as a query string parameter (via `request.GET`) or as a kwarg variable specified in the URLconf. Defaults to `page`. #### `paginator_class` The paginator class to be used for pagination. By default, [`django.core.paginator.Paginator`](/en/5.2/ref/paginator/#django.core.paginator.Paginator) is used. If the custom paginator class doesn’t have the same constructor interface as [`django.core.paginator.Paginator`](/en/5.2/ref/paginator/#django.core.paginator.Paginator), you will also need to provide an implementation for [`get_paginator()`](#django.views.generic.list.MultipleObjectMixin.get_paginator). #### `context_object_name` Designates the name of the variable to use in the context. #### `get_queryset()` Get the list of items for this view. This must be an iterable and may be a queryset (in which queryset-specific behavior will be enabled). #### `get_ordering()` Returns a string (or iterable of strings) that defines the ordering that will be applied to the `queryset`. Returns [`ordering`](#django.views.generic.list.MultipleObjectMixin.ordering) by default. #### `paginate_queryset(queryset, page_size)` Returns a 4-tuple containing (`paginator`, `page`, `object_list`, `is_paginated`). Constructed by paginating `queryset` into pages of size `page_size`. If the request contains a `page` argument, either as a captured URL argument or as a GET argument, `object_list` will correspond to the objects from that page. #### `get_paginate_by(queryset)` Returns the number of items to paginate by, or `None` for no pagination. By default this returns the value of [`paginate_by`](#django.views.generic.list.MultipleObjectMixin.paginate_by). #### `get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True)` Returns an instance of the paginator to use for this view. By default, instantiates an instance of [`paginator_class`](#django.views.generic.list.MultipleObjectMixin.paginator_class). #### `get_paginate_orphans()` An integer specifying the number of “overflow” objects the last page can contain. By default this returns the value of [`paginate_orphans`](#django.views.generic.list.MultipleObjectMixin.paginate_orphans). #### `get_allow_empty()` Return a boolean specifying whether to display the page if no objects are available. If this method returns `False` and no objects are available, the view will raise a 404 instead of displaying an empty page. By default, this is `True`. #### `get_context_object_name(object_list)` Return the context variable name that will be used to contain the list of data that this view is manipulating. If `object_list` is a queryset of Django objects and [`context_object_name`](#django.views.generic.list.MultipleObjectMixin.context_object_name) is not set, the context name will be the `model_name` of the model that the queryset is composed from, with postfix `'_list'` appended. For example, the model `Article` would have a context object named `article_list`. #### `get_context_data(**kwargs)` Returns context data for displaying the list of objects. **Context** - `object_list`: The list of objects that this view is displaying. If `context_object_name` is specified, that variable will also be set in the context, with the same value as `object_list`. - `is_paginated`: A boolean representing whether the results are paginated. Specifically, this is set to `False` if no page size has been specified, or if the available objects do not span multiple pages. - `paginator`: An instance of [`django.core.paginator.Paginator`](/en/5.2/ref/paginator/#django.core.paginator.Paginator). If the page is not paginated, this context variable will be `None`. - `page_obj`: An instance of [`django.core.paginator.Page`](/en/5.2/ref/paginator/#django.core.paginator.Page). If the page is not paginated, this context variable will be `None`. ## `MultipleObjectTemplateResponseMixin` #### `class django.views.generic.list.MultipleObjectTemplateResponseMixin` A mixin class that performs template-based response rendering for views that operate upon a list of object instances. Requires that the view it is mixed with provides `self.object_list`, the list of object instances that the view is operating on. `self.object_list` may be, but is not required to be, a [`QuerySet`](/en/5.2/ref/models/querysets/#django.db.models.query.QuerySet). **Extends** - [`TemplateResponseMixin`](/en/5.2/ref/class-based-views/mixins-simple/#django.views.generic.base.TemplateResponseMixin) **Methods and Attributes** #### `template_name_suffix` The suffix to append to the auto-generated candidate template name. Default suffix is `_list`. #### `get_template_names()` Returns a list of candidate template names. Returns the following list: - the value of `template_name` on the view (if provided) - `/.html`