Skip to main content

Displaying Data with Generic Views

To quickly implement views for listing collections of objects or displaying detailed information for a single model instance, use the generic ListView and DetailView classes.

Listing Objects with ListView​

To display a list of objects, subclass ListView and specify the model or queryset.

from django.views import generic
from .models import Author

class AuthorList(generic.ListView):
    # Option 1: Specify the model
    model = Author
    
    # Option 2: Specify a custom queryset
    # queryset = Author.objects.all()

By default, ListView provides the following context variables to your template:

  • object_list: The list of objects.
  • author_list: A model-specific name (e.g., <model_name>_list).

Customizing the List Context​

You can change the context variable name using context_object_name or add extra data by overriding get_context_data.

class AuthorList(generic.ListView):
    queryset = Author.objects.all()
    context_object_name = "authors"

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context["extra_content"] = "Total authors: %d" % Author.objects.count()
        return context

Displaying Single Object Details​

To display a single object, use DetailView. It automatically looks up an object based on a pk (primary key) or slug provided in the URL.

from django.views import generic
from .models import Author

class AuthorDetail(generic.DetailView):
    model = Author

URL Configuration for DetailView​

The URL pattern must include either a pk or slug keyword argument.

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path("author/<int:pk>/", views.AuthorDetail.as_view(), name="author_detail"),
    path("author/byslug/<slug:slug>/", views.AuthorDetail.as_view(), name="author_slug"),
]

Implementing Pagination​

Enable pagination in ListView by setting the paginate_by attribute. This determines how many items are shown per page.

class AuthorList(generic.ListView):
    queryset = Author.objects.all()
    paginate_by = 30
    # Optional: Allow the last page to have a few extra items instead of a new page
    paginate_orphans = 2

When paginate_by is set, the view adds paginator, page_obj, and is_paginated to the template context.

Customizing Querysets and Lookups​

For dynamic filtering (e.g., based on the current user or URL parameters), override get_queryset or get_object.

Dynamic List Filtering​

class AuthorList(generic.ListView):
    def get_queryset(self):
        # Filter authors whose name contains a specific string
        return Author.objects.filter(name__icontains='test')

Custom Object Lookup​

If you need to retrieve an object using logic other than standard pk or slug filtering, override get_object.

class CustomAuthorDetail(generic.DetailView):
    queryset = Author.objects.all()

    def get_object(self, queryset=None):
        # Custom logic to return a specific object
        return Author.objects.get(pk=1)

Template Discovery and Naming​

Generic views automatically look for templates based on the model name if template_name is not explicitly set.

  • ListView: Looks for <app_label>/<model_name>_list.html.
  • DetailView: Looks for <app_label>/<model_name>_detail.html.

Using a Model Field for Template Names​

DetailView can use a field on the model instance to determine which template to render via template_name_field.

class PageDetail(generic.DetailView):
    queryset = Page.objects.all()
    # If the Page model has a 'template' field, its value will be used as the template path
    template_name_field = "template"

Troubleshooting and Gotchas​

  • ImproperlyConfigured Error: This occurs if you fail to define model, queryset, or override get_queryset().
  • AttributeError in DetailView: Raised if the URLconf does not provide a pk or slug argument. You can customize these keyword names using pk_url_kwarg or slug_url_kwarg.
  • Empty Lists: By default, ListView displays an empty list if no objects are found. To raise a 404 instead, set allow_empty = False.
  • Invalid Page 404: If a user requests a page number that does not exist (e.g., ?page=999), ListView will raise a 404 error.
  • Ordering: If you need a specific order for your list, set the ordering attribute or override get_ordering(). 
    class AuthorList(generic.ListView):
        queryset = Author.objects.all()
        ordering = "name" # Or a tuple: ("name", "-id")