Using mixins with class-based views

Caution

This is an advanced topic. A working knowledge of Django'sclass-based views is advised before exploring thesetechniques.

Django's built-in class-based views provide a lot of functionality,but some of it you may want to use separately. For instance, you maywant to write a view that renders a template to make the HTTPresponse, but you can't useTemplateView; perhaps you need torender a template only on POST, with GET doing something elseentirely. While you could useTemplateResponse directly, thiswill likely result in duplicate code.

For this reason, Django also provides a number of mixins that providemore discrete functionality. Template rendering, for instance, isencapsulated in theTemplateResponseMixin. The Djangoreference documentation contains full documentation of all themixins.

Context and template responses

Two central mixins are provided that help in providing a consistentinterface to working with templates in class-based views.

• TemplateResponseMixin
• Every built in view which returns aTemplateResponse will call therender_to_response()method that TemplateResponseMixin provides. Most of the time thiswill be called for you (for instance, it is called by the get() methodimplemented by both TemplateView andDetailView); similarly, it's unlikelythat you'll need to override it, although if you want your response toreturn something not rendered via a Django template then you'll want to doit. For an example of this, see the JSONResponseMixin example.

render_to_response() itself callsget_template_names(),which by default will just look uptemplate_name onthe class-based view; two other mixins(SingleObjectTemplateResponseMixinandMultipleObjectTemplateResponseMixin)override this to provide more flexible defaults when dealing with actualobjects.

• ContextMixin
• Every built in view which needs context data, such as for rendering atemplate (including TemplateResponseMixin above), should callget_context_data() passingany data they want to ensure is in there as keyword arguments.get_context_data() returns a dictionary; in ContextMixin itsimply returns its keyword arguments, but it is common to override this toadd more members to the dictionary. You can also use theextra_context attribute.

Building up Django's generic class-based views

Let's look at how two of Django's generic class-based views are builtout of mixins providing discrete functionality. We'll considerDetailView, which renders a"detail" view of an object, andListView, which will render a listof objects, typically from a queryset, and optionally paginatethem. This will introduce us to four mixins which between them provideuseful functionality when working with either a single Django object,or multiple objects.

There are also mixins involved in the generic edit views(FormView, and the model-specificviews CreateView,UpdateView andDeleteView), and in thedate-based generic views. These arecovered in the mixin referencedocumentation.

DetailView: working with a single Django object

To show the detail of an object, we basically need to do two things:we need to look up the object and then we need to make aTemplateResponse with a suitable template,and that object as context.

To get the object, DetailViewrelies on SingleObjectMixin,which provides aget_object()method that figures out the object based on the URL of the request (itlooks for pk and slug keyword arguments as declared in theURLConf, and looks the object up either from themodel attributeon the view, or thequerysetattribute if that's provided). SingleObjectMixin also overridesget_context_data(),which is used across all Django's built in class-based views to supplycontext data for template renders.

To then make a TemplateResponse,DetailView usesSingleObjectTemplateResponseMixin,which extends TemplateResponseMixin,overridingget_template_names()as discussed above. It actually provides a fairly sophisticated set of options,but the main one that most people are going to use is<app_label>/<model_name>_detail.html. The _detail part can be changedby settingtemplate_name_suffixon a subclass to something else. (For instance, the generic editviews use _form for create and update views, and_confirm_delete for delete views.)

ListView: working with many Django objects

Lists of objects follow roughly the same pattern: we need a (possiblypaginated) list of objects, typically aQuerySet, and then we need to make aTemplateResponse with a suitable templateusing that list of objects.

To get the objects, ListView usesMultipleObjectMixin, whichprovides bothget_queryset()andpaginate_queryset(). Unlikewith SingleObjectMixin, there's no needto key off parts of the URL to figure out the queryset to work with, so thedefault just uses thequeryset ormodel attributeon the view class. A common reason to overrideget_queryset()here would be to dynamically vary the objects, such as depending onthe current user or to exclude posts in the future for a blog.

MultipleObjectMixin also overridesget_context_data() toinclude appropriate context variables for pagination (providingdummies if pagination is disabled). It relies on object_list beingpassed in as a keyword argument, which ListView arranges forit.

To make a TemplateResponse,ListView then usesMultipleObjectTemplateResponseMixin;as with SingleObjectTemplateResponseMixinabove, this overrides get_template_names() to provide a range ofoptions,with the most commonly-used being<app_label>/<model_name>_list.html, with the _list part againbeing taken from thetemplate_name_suffixattribute. (The date based generic views use suffixes such as _archive,_archive_year and so on to use different templates for the variousspecialized date-based list views.)

Using Django's class-based view mixins

Now we've seen how Django's generic class-based views use the providedmixins, let's look at other ways we can combine them. Of course we'restill going to be combining them with either built-in class-basedviews, or other generic class-based views, but there are a range ofrarer problems you can solve than are provided for by Django out ofthe box.

Warning

Not all mixins can be used together, and not all generic classbased views can be used with all other mixins. Here we present afew examples that do work; if you want to bring together otherfunctionality then you'll have to consider interactions betweenattributes and methods that overlap between the different classesyou're using, and how method resolution order will affect whichversions of the methods will be called in what order.

The reference documentation for Django's class-basedviews and class-based viewmixins will help you inunderstanding which attributes and methods are likely to causeconflict between different classes and mixins.

If in doubt, it's often better to back off and base your work onView or TemplateView, perhaps withSingleObjectMixin andMultipleObjectMixin. Although youwill probably end up writing more code, it is more likely to be clearlyunderstandable to someone else coming to it later, and with fewerinteractions to worry about you will save yourself some thinking. (Ofcourse, you can always dip into Django's implementation of the genericclass-based views for inspiration on how to tackle problems.)

Using SingleObjectMixin with View

If we want to write a simple class-based view that responds only toPOST, we'll subclass View andwrite a post() method in the subclass. However if we want ourprocessing to work on a particular object, identified from the URL,we'll want the functionality provided bySingleObjectMixin.

We'll demonstrate this with the Author model we used in thegeneric class-based views introduction.

views.py

from django.http import HttpResponseForbidden, HttpResponseRedirect
from django.urls import reverse
from django.views import View
from django.views.generic.detail import SingleObjectMixin
from books.models import Author
 
class RecordInterest(SingleObjectMixin, View):
    """Records the current user's interest in an author."""
    model = Author
 
    def post(self, request, *args, **kwargs):
        if not request.user.is_authenticated:
            return HttpResponseForbidden()
 
        # Look up the author we're interested in.
        self.object = self.get_object()
        # Actually record interest somehow here!
 
        return HttpResponseRedirect(reverse('author-detail', kwargs={'pk': self.object.pk}))

In practice you'd probably want to record the interest in a key-valuestore rather than in a relational database, so we've left that bitout. The only bit of the view that needs to worry about usingSingleObjectMixin is where we want tolook up the author we're interested in, which it just does with a simple callto self.get_object(). Everything else is taken care of for us by themixin.

We can hook this into our URLs easily enough:

urls.py

from django.urls import path
from books.views import RecordInterest
 
urlpatterns = [
    #...
    path('author/<int:pk>/interest/', RecordInterest.as_view(), name='author-interest'),
]

Note the pk named group, whichget_object() usesto look up the Author instance. You could also use a slug, orany of the other features ofSingleObjectMixin.

Using SingleObjectMixin with ListView

ListView provides built-inpagination, but you might want to paginate a list of objects that areall linked (by a foreign key) to another object. In our publishingexample, you might want to paginate through all the books by aparticular publisher.

One way to do this is to combine ListView withSingleObjectMixin, so that the querysetfor the paginated list of books can hang off the publisher found as the singleobject. In order to do this, we need to have two different querysets:

• Book queryset for use by ListView
• Since we have access to the Publisher whose books we want to list, wesimply override get_queryset() and use the Publisher’sreverse foreign key manager.
• Publisher queryset for use in get_object()
• We'll rely on the default implementation of get_object() to fetch thecorrect Publisher object.However, we need to explicitly pass a queryset argument becauseotherwise the default implementation of get_object() would callget_queryset() which we have overridden to return Book objectsinstead of Publisher ones.

Note

We have to think carefully about get_context_data().Since both SingleObjectMixin andListView willput things in the context data under the value ofcontext_object_name if it's set, we'll instead explicitlyensure the Publisher is in the context data. ListViewwill add in the suitable page_obj and paginator for usproviding we remember to call super().

Now we can write a new PublisherDetail:

from django.views.generic import ListView
from django.views.generic.detail import SingleObjectMixin
from books.models import Publisher
 
class PublisherDetail(SingleObjectMixin, ListView):
    paginate_by = 2
    template_name = "books/publisher_detail.html"
 
    def get(self, request, *args, **kwargs):
        self.object = self.get_object(queryset=Publisher.objects.all())
        return super().get(request, *args, **kwargs)
 
    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context['publisher'] = self.object
        return context
 
    def get_queryset(self):
        return self.object.book_set.all()

Notice how we set self.object within get() so wecan use it again later in get_context_data() and get_queryset().If you don't set template_name, the template will default to the normalListView choice, which in this case would be"books/book_list.html" because it's a list of books;ListView knows nothing aboutSingleObjectMixin, so it doesn't haveany clue this view is anything to do with a Publisher.

The paginate_by is deliberately small in the example so you don'thave to create lots of books to see the pagination working! Here's thetemplate you'd want to use:

{% extends "base.html" %}
 
{% block content %}
    <h2>Publisher {{ publisher.name }}</h2>
 
    <ol>
      {% for book in page_obj %}
        <li>{{ book.title }}</li>
      {% endfor %}
    </ol>
 
    <div class="pagination">
        <span class="step-links">
            {% if page_obj.has_previous %}
                <a href="?page={{ page_obj.previous_page_number }}">previous</a>
            {% endif %}
 
            <span class="current">
                Page {{ page_obj.number }} of {{ paginator.num_pages }}.
            </span>
 
            {% if page_obj.has_next %}
                <a href="?page={{ page_obj.next_page_number }}">next</a>
            {% endif %}
        </span>
    </div>
{% endblock %}

Avoid anything more complex

Generally you can useTemplateResponseMixin andSingleObjectMixin when you needtheir functionality. As shown above, with a bit of care you can evencombine SingleObjectMixin withListView. However things getincreasingly complex as you try to do so, and a good rule of thumb is:

Hint

Each of your views should use only mixins or views from one of thegroups of generic class-based views: detail,list, editing anddate. For example it's fine to combineTemplateView (built in view) withMultipleObjectMixin (generic list), butyou're likely to have problems combining SingleObjectMixin (genericdetail) with MultipleObjectMixin (generic list).

To show what happens when you try to get more sophisticated, we showan example that sacrifices readability and maintainability when thereis a simpler solution. First, let's look at a naive attempt to combineDetailView withFormMixin to enable us toPOST a Django Form to the same URL as we'redisplaying an object using DetailView.

Using FormMixin with DetailView

Think back to our earlier example of using View andSingleObjectMixin together. We wererecording a user's interest in a particular author; say now that we want tolet them leave a message saying why they like them. Again, let's assume we'renot going to store this in a relational database but instead insomething more esoteric that we won't worry about here.

At this point it's natural to reach for a Form toencapsulate the information sent from the user's browser to Django. Say alsothat we're heavily invested in REST, so we want to use the same URL fordisplaying the author as for capturing the message from theuser. Let's rewrite our AuthorDetailView to do that.

We'll keep the GET handling from DetailView, althoughwe'll have to add a Form into the context data so we canrender it in the template. We'll also want to pull in form processingfrom FormMixin, and write a bit ofcode so that on POST the form gets called appropriately.

Note

We use FormMixin and implementpost() ourselves rather than try to mix DetailView withFormView (which provides a suitable post() already) becauseboth of the views implement get(), and things would get much moreconfusing.

Our new AuthorDetail looks like this:

# CAUTION: you almost certainly do not want to do this.
# It is provided as part of a discussion of problems you can
# run into when combining different generic class-based view
# functionality that is not designed to be used together.
 
from django import forms
from django.http import HttpResponseForbidden
from django.urls import reverse
from django.views.generic import DetailView
from django.views.generic.edit import FormMixin
from books.models import Author
 
class AuthorInterestForm(forms.Form):
    message = forms.CharField()
 
class AuthorDetail(FormMixin, DetailView):
    model = Author
    form_class = AuthorInterestForm
 
    def get_success_url(self):
        return reverse('author-detail', kwargs={'pk': self.object.pk})
 
    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context['form'] = self.get_form()
        return context
 
    def post(self, request, *args, **kwargs):
        if not request.user.is_authenticated:
            return HttpResponseForbidden()
        self.object = self.get_object()
        form = self.get_form()
        if form.is_valid():
            return self.form_valid(form)
        else:
            return self.form_invalid(form)
 
    def form_valid(self, form):
        # Here, we would record the user's interest using the message
        # passed in form.cleaned_data['message']
        return super().form_valid(form)

get_success_url() is just providing somewhere to redirect to,which gets used in the default implementation ofform_valid(). We have to provide our own post() asnoted earlier, and override get_context_data() to make theForm available in the context data.

A better solution

It should be obvious that the number of subtle interactions betweenFormMixin and DetailView isalready testing our ability to manage things. It's unlikely you'd want towrite this kind of class yourself.

In this case, it would be fairly easy to just write the post()method yourself, keeping DetailView as the only genericfunctionality, although writing Form handling codeinvolves a lot of duplication.

Alternatively, it would still be easier than the above approach tohave a separate view for processing the form, which could useFormView distinct fromDetailView without concerns.

An alternative better solution

What we're really trying to do here is to use two different classbased views from the same URL. So why not do just that? We have a veryclear division here: GET requests should get theDetailView (with the Form added to the contextdata), and POST requests should get the FormView. Let'sset up those views first.

The AuthorDisplay view is almost the same as when wefirst introduced AuthorDetail; we have towrite our own get_context_data() to make theAuthorInterestForm available to the template. We'll skip theget_object() override from before for clarity:

from django import forms
from django.views.generic import DetailView
from books.models import Author
 
class AuthorInterestForm(forms.Form):
    message = forms.CharField()
 
class AuthorDisplay(DetailView):
    model = Author
 
    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context['form'] = AuthorInterestForm()
        return context

Then the AuthorInterest is a simple FormView, but wehave to bring in SingleObjectMixin so wecan find the author we're talking about, and we have to remember to settemplate_name to ensure that form errors will render the sametemplate as AuthorDisplay is using on GET:

from django.http import HttpResponseForbidden
from django.urls import reverse
from django.views.generic import FormView
from django.views.generic.detail import SingleObjectMixin
 
class AuthorInterest(SingleObjectMixin, FormView):
    template_name = 'books/author_detail.html'
    form_class = AuthorInterestForm
    model = Author
 
    def post(self, request, *args, **kwargs):
        if not request.user.is_authenticated:
            return HttpResponseForbidden()
        self.object = self.get_object()
        return super().post(request, *args, **kwargs)
 
    def get_success_url(self):
        return reverse('author-detail', kwargs={'pk': self.object.pk})

Finally we bring this together in a new AuthorDetail view. Wealready know that calling as_view() ona class-based view gives us something that behaves exactly like a functionbased view, so we can do that at the point we choose between the two subviews.

You can of course pass through keyword arguments toas_view() in the same way youwould in your URLconf, such as if you wanted the AuthorInterest behaviorto also appear at another URL but using a different template:

from django.views import View
 
class AuthorDetail(View):
 
    def get(self, request, *args, **kwargs):
        view = AuthorDisplay.as_view()
        return view(request, *args, **kwargs)
 
    def post(self, request, *args, **kwargs):
        view = AuthorInterest.as_view()
        return view(request, *args, **kwargs)

This approach can also be used with any other generic class-basedviews or your own class-based views inheriting directly fromView or TemplateView, as it keeps the differentviews as separate as possible.

More than just HTML

Where class-based views shine is when you want to do the same thing many times.Suppose you're writing an API, and every view should return JSON instead ofrendered HTML.

We can create a mixin class to use in all of our views, handling theconversion to JSON once.

For example, a simple JSON mixin might look something like this:

from django.http import JsonResponse
 
class JSONResponseMixin:
    """
    A mixin that can be used to render a JSON response.
    """
    def render_to_json_response(self, context, **response_kwargs):
        """
        Returns a JSON response, transforming 'context' to make the payload.
        """
        return JsonResponse(
            self.get_data(context),
            **response_kwargs
        )
 
    def get_data(self, context):
        """
        Returns an object that will be serialized as JSON by json.dumps().
        """
        # Note: This is *EXTREMELY* naive; in reality, you'll need
        # to do much more complex handling to ensure that arbitrary
        # objects -- such as Django model instances or querysets
        # -- can be serialized as JSON.
        return context

Note

Check out the Serializing Django objects documentation for moreinformation on how to correctly transform Django models and querysets intoJSON.

This mixin provides a render_to_json_response() method with the same signatureas render_to_response().To use it, we simply need to mix it into a TemplateView for example,and override render_to_response() to call render_to_json_response() instead:

from django.views.generic import TemplateView
 
class JSONView(JSONResponseMixin, TemplateView):
    def render_to_response(self, context, **response_kwargs):
        return self.render_to_json_response(context, **response_kwargs)

Equally we could use our mixin with one of the generic views. We can make ourown version of DetailView by mixingJSONResponseMixin with thedjango.views.generic.detail.BaseDetailView — (theDetailView before templaterendering behavior has been mixed in):

from django.views.generic.detail import BaseDetailView
 
class JSONDetailView(JSONResponseMixin, BaseDetailView):
    def render_to_response(self, context, **response_kwargs):
        return self.render_to_json_response(context, **response_kwargs)

This view can then be deployed in the same way as any otherDetailView, with exactly thesame behavior — except for the format of the response.

If you want to be really adventurous, you could even mix aDetailView subclass that is ableto return both HTML and JSON content, depending on some property ofthe HTTP request, such as a query argument or a HTTP header. Just mixin both the JSONResponseMixin and aSingleObjectTemplateResponseMixin,and override the implementation ofrender_to_response()to defer to the appropriate rendering method depending on the type of responsethat the user requested:

from django.views.generic.detail import SingleObjectTemplateResponseMixin
 
class HybridDetailView(JSONResponseMixin, SingleObjectTemplateResponseMixin, BaseDetailView):
    def render_to_response(self, context):
        # Look for a 'format=json' GET argument
        if self.request.GET.get('format') == 'json':
            return self.render_to_json_response(context)
        else:
            return super().render_to_response(context)

Because of the way that Python resolves method overloading, the call tosuper().render_to_response(context) ends up calling therender_to_response()implementation of TemplateResponseMixin.