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:

    (r'^objects/page(?P<page>[0-9]+)/$', PaginatedView.as_view())
    
  • Pass the page number via the page query-string parameter. For example, a URL would look like this:

    /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.

As a special case, you are also permitted to use last as a value for page:

/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

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().

queryset

A QuerySet that represents the objects. If provided, the value of MultipleObjectMixin.queryset supersedes the value provided for MultipleObjectMixin.model.

paginate_by

An integer specifying how many objects should be displayed per page. If this is given, the view will paginate objects with MultipleObjectMixin.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
New in Django 1.6: Please see the release notes

An integer specifying the number of “overflow” objects the last page can contain. This extends the MultipleObjectMixin.paginate_by limit on the last page by up to MultipleObjectMixin.paginate_orphans, in order to keep the last page from having a very small number of objects.

page_kwarg
New in Django 1.5: Please see the release notes

A string specifying the name to use for the page parameter. The view will expect this prameter 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 is used. If the custom paginator class doesn’t have the same constructor interface as django.core.paginator.Paginator, you will also need to provide an implementation for 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).

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 simply returns the value of 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.

get_paginate_by()
New in Django 1.6: Please see the release notes

An integer specifying the number of “overflow” objects the last page can contain. By default this simply returns the value of 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 is not set, the context name will be the object_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. If the page is not paginated, this context variable will be None.
  • page_obj: An instance of 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.

Extends

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)
  • <app_label>/<object_name><template_name_suffix>.html