diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index 954aee7c3d..cc9aa852f1 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -71,6 +71,11 @@ View delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`, and so on. + By default, a ``HEAD`` request will be delegated to :meth:`~View.get()`. + If you need to handle ``HEAD`` requests in a different way than ``GET``, + you can override the :meth:`~View.head()` method. See + :ref:`supporting-other-http-methods` for an example. + The default implementation also sets ``request``, ``args`` and ``kwargs`` as instance variables, so any method on the view can know the full details of the request that was made to invoke the view. diff --git a/docs/topics/class-based-views/index.txt b/docs/topics/class-based-views/index.txt index 6637bd5fcb..2d3e00ab4c 100644 --- a/docs/topics/class-based-views/index.txt +++ b/docs/topics/class-based-views/index.txt @@ -84,6 +84,50 @@ function-like entry to class-based views:: For more information on how to use the built in generic views, consult the next topic on :doc:`generic class based views`. +.. _supporting-other-http-methods: + +Supporting other HTTP methods +----------------------------- + +Suppose somebody wants to access our book library over HTTP using the views +as an API. The API client would connect every now and then and download book +data for the books published since last visit. But if no new books appeared +since then, it is a waste of CPU time and bandwidth to fetch the books from the +database, render a full response and send it to the client. It might be +preferable to ask the API when the most recent book was published. + +We map the URL to book list view in the URLconf:: + + from django.conf.urls import patterns + from books.views import BookListView + + urlpatterns = patterns('', + (r'^books/$', BookListView.as_view()), + ) + +And the view:: + + from django.http import HttpResponse + from django.views.generic import ListView + from books.models import Book + + class BookListView(ListView): + model = Book + + def head(self, *args, **kwargs): + last_book = self.get_queryset().latest('publication_date') + response = HttpResponse('') + # RFC 1123 date format + response['Last-Modified'] = last_book.publication_date.strftime('%a, %d %b %Y %H:%M:%S GMT') + return response + +If the view is accessed from a ``GET`` request, a plain-and-simple object +list is returned in the response (using ``book_list.html`` template). But if +the client issues a ``HEAD`` request, the response has an empty body and +the ``Last-Modified`` header indicates when the most recent book was published. +Based on this information, the client may or may not download the full object +list. + Decorating class-based views ============================