Fixed #15906 - Documented HEAD method in CBVs; thanks zsiciarz for the patch.

2 files changed, 49 insertions, 0 deletions

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</topics/class-based-views/generic-display>`.
 
+.. _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
 ============================