Writing web applications can be monotonous, because we repeat certain patterns\nagain and again. Django tries to take away some of that monotony at the model\nand template layers, but web developers also experience this boredom at the\nview level.
\nDjango’s generic views were developed to ease that pain. They take certain\ncommon idioms and patterns found in view development and abstract them so that\nyou can quickly write common views of data without having to write too much\ncode.
\nWe can recognize certain common tasks, like displaying a list of objects, and\nwrite code that displays a list of any object. Then the model in question can\nbe passed as an extra argument to the URLconf.
\nDjango ships with generic views to do the following:
\nDisplay list and detail pages for a single object. If we were creating an\napplication to manage conferences then a TalkListView and a\nRegisteredUserListView would be examples of list views. A single\ntalk page is an example of what we call a «detail» view.
Present date-based objects in year/month/day archive pages,\nassociated detail, and «latest» pages.
Allow users to create, update, and delete objects – with or\nwithout authorization.
Taken together, these views provide interfaces to perform the most common tasks\ndevelopers encounter.
\nThere’s no question that using generic views can speed up development\nsubstantially. In most projects, however, there comes a moment when the\ngeneric views no longer suffice. Indeed, the most common question asked by new\nDjango developers is how to make generic views handle a wider array of\nsituations.
\nThis is one of the reasons generic views were redesigned for the 1.3 release -\npreviously, they were view functions with a bewildering array of options; now,\nrather than passing in a large amount of configuration in the URLconf, the\nrecommended way to extend generic views is to subclass them, and override their\nattributes or methods.
\nThat said, generic views will have a limit. If you find you’re struggling to\nimplement your view as a subclass of a generic view, then you may find it more\neffective to write just the code you need, using your own class-based or\nfunctional views.
\nMore examples of generic views are available in some third party applications,\nor you could write your own as needed.
\nTemplateView certainly is useful, but\nDjango’s generic views really shine when it comes to presenting views of your\ndatabase content. Because it’s such a common task, Django comes with a handful\nof built-in generic views to help generate list and detail views of objects.
Let’s start by looking at some examples of showing a list of objects or an\nindividual object.
\nWe’ll be using these models:
\n# models.py\nfrom django.db import models\n\n\nclass Publisher(models.Model):\n name = models.CharField(max_length=30)\n address = models.CharField(max_length=50)\n city = models.CharField(max_length=60)\n state_province = models.CharField(max_length=30)\n country = models.CharField(max_length=50)\n website = models.URLField()\n\n class Meta:\n ordering = ["-name"]\n\n def __str__(self):\n return self.name\n\n\nclass Author(models.Model):\n salutation = models.CharField(max_length=10)\n name = models.CharField(max_length=200)\n email = models.EmailField()\n headshot = models.ImageField(upload_to="author_headshots")\n\n def __str__(self):\n return self.name\n\n\nclass Book(models.Model):\n title = models.CharField(max_length=100)\n authors = models.ManyToManyField("Author")\n publisher = models.ForeignKey(Publisher, on_delete=models.CASCADE)\n publication_date = models.DateField()\nNow we need to define a view:
\n# views.py\nfrom django.views.generic import ListView\nfrom books.models import Publisher\n\n\nclass PublisherListView(ListView):\n model = Publisher\nFinally hook that view into your urls:
\n# urls.py\nfrom django.urls import path\nfrom books.views import PublisherListView\n\nurlpatterns = [\n path("publishers/", PublisherListView.as_view()),\n]\nThat’s all the Python code we need to write. We still need to write a template,\nhowever. We could explicitly tell the view which template to use by adding a\ntemplate_name attribute to the view, but in the absence of an explicit\ntemplate Django will infer one from the object’s name. In this case, the\ninferred template will be "books/publisher_list.html" – the «books» part\ncomes from the name of the app that defines the model, while the «publisher»\nbit is the lowercased version of the model’s name.
This template will be rendered against a context containing a variable called\nobject_list that contains all the publisher objects. A template might look\nlike this:
{% extends "base.html" %}\n\n{% block content %}\n <h2>Publishers</h2>\n <ul>\n {% for publisher in object_list %}\n <li>{{ publisher.name }}</li>\n {% endfor %}\n </ul>\n{% endblock %}\nThat’s really all there is to it. All the cool features of generic views come\nfrom changing the attributes set on the generic view. The\ngeneric views reference documents all the\ngeneric views and their options in detail; the rest of this document will\nconsider some of the common ways you might customize and extend generic views.
\nYou might have noticed that our sample publisher list template stores all the\npublishers in a variable named object_list. While this works just fine, it\nisn’t all that «friendly» to template authors: they have to «just know» that\nthey’re dealing with publishers here.
Well, if you’re dealing with a model object, this is already done for you. When\nyou are dealing with an object or queryset, Django is able to populate the\ncontext using the lowercased version of the model class” name. This is provided\nin addition to the default object_list entry, but contains exactly the same\ndata, i.e. publisher_list.
If this still isn’t a good match, you can manually set the name of the\ncontext variable. The context_object_name attribute on a generic view\nspecifies the context variable to use:
# views.py\nfrom django.views.generic import ListView\nfrom books.models import Publisher\n\n\nclass PublisherListView(ListView):\n model = Publisher\n context_object_name = "my_favorite_publishers"\nProviding a useful context_object_name is always a good idea. Your\ncoworkers who design templates will thank you.
Often you need to present some extra information beyond that provided by the\ngeneric view. For example, think of showing a list of all the books on each\npublisher detail page. The DetailView\ngeneric view provides the publisher to the context, but how do we get\nadditional information in that template?
The answer is to subclass DetailView\nand provide your own implementation of the get_context_data method.\nThe default implementation adds the object being displayed to the template, but\nyou can override it to send more:
from django.views.generic import DetailView\nfrom books.models import Book, Publisher\n\n\nclass PublisherDetailView(DetailView):\n model = Publisher\n\n def get_context_data(self, **kwargs):\n # Call the base implementation first to get a context\n context = super().get_context_data(**kwargs)\n # Add in a QuerySet of all the books\n context["book_list"] = Book.objects.all()\n return context\nNow let’s take a closer look at the model argument we’ve been\nusing all along. The model argument, which specifies the database\nmodel that the view will operate upon, is available on all the\ngeneric views that operate on a single object or a collection of\nobjects. However, the model argument is not the only way to\nspecify the objects that the view will operate upon – you can also\nspecify the list of objects using the queryset argument:
from django.views.generic import DetailView\nfrom books.models import Publisher\n\n\nclass PublisherDetailView(DetailView):\n context_object_name = "publisher"\n queryset = Publisher.objects.all()\nSpecifying model = Publisher is shorthand for saying queryset =\nPublisher.objects.all(). However, by using queryset to define a filtered\nlist of objects you can be more specific about the objects that will be visible\nin the view (see Making queries for more information about\nQuerySet objects, and see the\nclass-based views reference for the\ncomplete details).
To pick an example, we might want to order a list of books by publication date,\nwith the most recent first:
\nfrom django.views.generic import ListView\nfrom books.models import Book\n\n\nclass BookListView(ListView):\n queryset = Book.objects.order_by("-publication_date")\n context_object_name = "book_list"\nThat’s a pretty minimal example, but it illustrates the idea nicely. You’ll\nusually want to do more than just reorder objects. If you want to present a\nlist of books by a particular publisher, you can use the same technique:
\nfrom django.views.generic import ListView\nfrom books.models import Book\n\n\nclass AcmeBookListView(ListView):\n context_object_name = "book_list"\n queryset = Book.objects.filter(publisher__name="ACME Publishing")\n template_name = "books/acme_list.html"\nNotice that along with a filtered queryset, we’re also using a custom\ntemplate name. If we didn’t, the generic view would use the same template as\nthe «vanilla» object list, which might not be what we want.
Also notice that this isn’t a very elegant way of doing publisher-specific\nbooks. If we want to add another publisher page, we’d need another handful of\nlines in the URLconf, and more than a few publishers would get unreasonable.\nWe’ll deal with this problem in the next section.
\n\nAnother common need is to filter down the objects given in a list page by some\nkey in the URL. Earlier we hardcoded the publisher’s name in the URLconf, but\nwhat if we wanted to write a view that displayed all the books by some\narbitrary publisher?
\nHandily, the ListView has a\nget_queryset() method we\ncan override. By default, it returns the value of the queryset attribute,\nbut we can use it to add more logic.
The key part to making this work is that when class-based views are called,\nvarious useful things are stored on self; as well as the request\n(self.request) this includes the positional (self.args) and name-based\n(self.kwargs) arguments captured according to the URLconf.
Here, we have a URLconf with a single captured group:
\n# urls.py\nfrom django.urls import path\nfrom books.views import PublisherBookListView\n\nurlpatterns = [\n path("books/<publisher>/", PublisherBookListView.as_view()),\n]\nNext, we’ll write the PublisherBookListView view itself:
# views.py\nfrom django.shortcuts import get_object_or_404\nfrom django.views.generic import ListView\nfrom books.models import Book, Publisher\n\n\nclass PublisherBookListView(ListView):\n template_name = "books/books_by_publisher.html"\n\n def get_queryset(self):\n self.publisher = get_object_or_404(Publisher, name=self.kwargs["publisher"])\n return Book.objects.filter(publisher=self.publisher)\nUsing get_queryset to add logic to the queryset selection is as convenient\nas it is powerful. For instance, if we wanted, we could use\nself.request.user to filter using the current user, or other more complex\nlogic.
We can also add the publisher into the context at the same time, so we can\nuse it in the template:
\n# ...\n\n\ndef get_context_data(self, **kwargs):\n # Call the base implementation first to get a context\n context = super().get_context_data(**kwargs)\n # Add in the publisher\n context["publisher"] = self.publisher\n return context\nThe last common pattern we’ll look at involves doing some extra work before\nor after calling the generic view.
\nImagine we had a last_accessed field on our Author model that we were\nusing to keep track of the last time anybody looked at that author:
# models.py\nfrom django.db import models\n\n\nclass Author(models.Model):\n salutation = models.CharField(max_length=10)\n name = models.CharField(max_length=200)\n email = models.EmailField()\n headshot = models.ImageField(upload_to="author_headshots")\n last_accessed = models.DateTimeField()\nThe generic DetailView class wouldn’t know anything about this field, but\nonce again we could write a custom view to keep that field updated.
First, we’d need to add an author detail bit in the URLconf to point to a\ncustom view:
\nfrom django.urls import path\nfrom books.views import AuthorDetailView\n\nurlpatterns = [\n # ...\n path("authors/<int:pk>/", AuthorDetailView.as_view(), name="author-detail"),\n]\nThen we’d write our new view – get_object is the method that retrieves the\nobject – so we override it and wrap the call:
from django.utils import timezone\nfrom django.views.generic import DetailView\nfrom books.models import Author\n\n\nclass AuthorDetailView(DetailView):\n queryset = Author.objects.all()\n\n def get_object(self):\n obj = super().get_object()\n # Record the last accessed date\n obj.last_accessed = timezone.now()\n obj.save()\n return obj\n