Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #18451 -- Vastly improved class based view documentation.

Many thanks to Daniel Greenfeld, James Aylett, Marc Tamlyn, Simon Williams, Danilo Bargen and Luke Plant for their work on this.
  • Loading branch information...
commit c4c7fbcc0d9264beb931b45969fc0d8d655c4f83 1 parent 1a10a06
@jezdez jezdez authored
Showing with 3,112 additions and 2,016 deletions.
  1. +5 −0 AUTHORS
  2. +8 −1 django/views/generic/base.py
  3. +13 −1 django/views/generic/dates.py
  4. +14 −2 django/views/generic/detail.py
  5. +35 −4 django/views/generic/edit.py
  6. +9 −0 django/views/generic/list.py
  7. +1 −1  docs/glossary.txt
  8. +1 −1  docs/howto/static-files.txt
  9. +4 −3 docs/index.txt
  10. +2 −2 docs/internals/deprecation.txt
  11. +1 −1  docs/intro/tutorial04.txt
  12. +1 −1  docs/misc/api-stability.txt
  13. +0 −1,367 docs/ref/class-based-views.txt
  14. +224 −0 docs/ref/class-based-views/base.txt
  15. +273 −0 docs/ref/class-based-views/generic-date-based.txt
  16. +86 −0 docs/ref/class-based-views/generic-display.txt
  17. +78 −0 docs/ref/class-based-views/generic-editing.txt
  18. +59 −0 docs/ref/class-based-views/index.txt
  19. +256 −0 docs/ref/class-based-views/mixins-date-based.txt
  20. +183 −0 docs/ref/class-based-views/mixins-editing.txt
  21. +175 −0 docs/ref/class-based-views/mixins-multiple-object.txt
  22. +60 −0 docs/ref/class-based-views/mixins-simple.txt
  23. +124 −0 docs/ref/class-based-views/mixins-single-object.txt
  24. +14 −0 docs/ref/class-based-views/mixins.txt
  25. +1 −1  docs/ref/index.txt
  26. +1 −1  docs/releases/1.3-alpha-1.txt
  27. +1 −1  docs/releases/1.3.txt
  28. +4 −3 docs/topics/auth.txt
  29. +0 −624 docs/topics/class-based-views.txt
  30. +432 −0 docs/topics/class-based-views/generic-display.txt
  31. +205 −0 docs/topics/class-based-views/generic-editing.txt
  32. +233 −0 docs/topics/class-based-views/index.txt
  33. +605 −0 docs/topics/class-based-views/mixins.txt
  34. +2 −0  docs/topics/forms/index.txt
  35. +1 −1  docs/topics/http/generic-views.txt
  36. +1 −1  docs/topics/index.txt
View
5 AUTHORS
@@ -51,6 +51,7 @@ answer newbie questions, and generally made Django that much better:
Antoni Aloy
Daniel Alves Barbosa de Oliveira Vaz <danielvaz@gmail.com>
AgarFu <heaven@croasanaso.sytes.net>
+ James Aylett
Dagur Páll Ammendrup <dagurp@gmail.com>
Collin Anderson <cmawebsite@gmail.com>
Jeff Anderson <jefferya@programmerq.net>
@@ -85,6 +86,7 @@ answer newbie questions, and generally made Django that much better:
Esdras Beleza <linux@esdrasbeleza.com>
Chris Bennett <chrisrbennett@yahoo.com>
James Bennett
+ Danilo Bargen
Shai Berger <shai@platonix.com>
Julian Bez
Arvis Bickovskis <viestards.lists@gmail.com>
@@ -222,6 +224,7 @@ answer newbie questions, and generally made Django that much better:
pradeep.gowda@gmail.com
Collin Grady <collin@collingrady.com>
Gabriel Grant <g@briel.ca>
+ Daniel Greenfeld
Simon Greenhill <dev@simon.net.nz>
Owen Griffiths
Espen Grindhaug <http://grindhaug.org/>
@@ -507,6 +510,7 @@ answer newbie questions, and generally made Django that much better:
Aaron Swartz <http://www.aaronsw.com/>
Ville Säävuori <http://www.unessa.net/>
Mart Sõmermaa <http://mrts.pri.ee/>
+ Marc Tamlyn
Christian Tanzer <tanzer@swing.co.at>
Tyler Tarabula <tyler.tarabula@gmail.com>
Tyson Tate <tyson@fallingbullets.com>
@@ -555,6 +559,7 @@ answer newbie questions, and generally made Django that much better:
Mike Wiacek <mjwiacek@google.com>
Frank Wierzbicki
charly.wilhelm@gmail.com
+ Simon Williams
Derek Willis <http://blog.thescoop.org/>
Rachel Willmer <http://www.willmer.com/kb/>
Jakub Wilk <ubanus@users.sf.net>
View
9 django/views/generic/base.py
@@ -90,6 +90,9 @@ def http_method_not_allowed(self, request, *args, **kwargs):
return http.HttpResponseNotAllowed(self._allowed_methods())
def options(self, request, *args, **kwargs):
+ """
+ Handles responding to requests for the OPTIONS HTTP verb.
+ """
response = http.HttpResponse()
response['Allow'] = ', '.join(self._allowed_methods())
response['Content-Length'] = 0
@@ -108,7 +111,11 @@ class TemplateResponseMixin(object):
def render_to_response(self, context, **response_kwargs):
"""
- Returns a response with a template rendered with the given context.
+ Returns a response, using the `response_class` for this
+ view, with a template rendered with the given context.
+
+ If any keyword arguments are provided, they will be
+ passed to the constructor of the response class.
"""
return self.response_class(
request = self.request,
View
14 django/views/generic/dates.py
@@ -14,6 +14,9 @@
from django.views.generic.list import MultipleObjectMixin, MultipleObjectTemplateResponseMixin
class YearMixin(object):
+ """
+ Mixin for views manipulating year-based data.
+ """
year_format = '%Y'
year = None
@@ -67,6 +70,9 @@ def _get_current_year(self, date):
class MonthMixin(object):
+ """
+ Mixin for views manipulating month-based data.
+ """
month_format = '%b'
month = None
@@ -123,6 +129,9 @@ def _get_current_month(self, date):
class DayMixin(object):
+ """
+ Mixin for views manipulating day-based data.
+ """
day_format = '%d'
day = None
@@ -176,6 +185,9 @@ def _get_current_day(self, date):
class WeekMixin(object):
+ """
+ Mixin for views manipulating week-based data.
+ """
week_format = '%U'
week = None
@@ -312,7 +324,7 @@ def _make_single_date_lookup(self, date):
class BaseDateListView(MultipleObjectMixin, DateMixin, View):
"""
- Abstract base class for date-based views display a list of objects.
+ Abstract base class for date-based views displaying a list of objects.
"""
allow_empty = False
View
16 django/views/generic/detail.py
@@ -48,6 +48,7 @@ def get_object(self, queryset=None):
% self.__class__.__name__)
try:
+ # Get the single item from the filtered queryset
obj = queryset.get()
except ObjectDoesNotExist:
raise Http404(_("No %(verbose_name)s found matching the query") %
@@ -88,6 +89,9 @@ def get_context_object_name(self, obj):
return None
def get_context_data(self, **kwargs):
+ """
+ Insert the single object into the context dict.
+ """
context = {}
context_object_name = self.get_context_object_name(self.object)
if context_object_name:
@@ -97,6 +101,9 @@ def get_context_data(self, **kwargs):
class BaseDetailView(SingleObjectMixin, View):
+ """
+ A base view for displaying a single object
+ """
def get(self, request, *args, **kwargs):
self.object = self.get_object()
context = self.get_context_data(object=self.object)
@@ -109,8 +116,13 @@ class SingleObjectTemplateResponseMixin(TemplateResponseMixin):
def get_template_names(self):
"""
- Return a list of template names to be used for the request. Must return
- a list. May not be called if render_to_response is overridden.
+ Return a list of template names to be used for the request. May not be
+ called if render_to_response is overridden. Returns the following list:
+
+ * the value of ``template_name`` on the view (if provided)
+ * the contents of the ``template_name_field`` field on the
+ object instance that the view is operating upon (if available)
+ * ``<app_label>/<object_name><template_name_suffix>.html``
"""
try:
names = super(SingleObjectTemplateResponseMixin, self).get_template_names()
View
39 django/views/generic/edit.py
@@ -46,6 +46,9 @@ def get_form_kwargs(self):
return kwargs
def get_success_url(self):
+ """
+ Returns the supplied success URL.
+ """
if self.success_url:
url = self.success_url
else:
@@ -54,9 +57,16 @@ def get_success_url(self):
return url
def form_valid(self, form):
+ """
+ If the form is valid, redirect to the supplied URL.
+ """
return HttpResponseRedirect(self.get_success_url())
def form_invalid(self, form):
+ """
+ If the form is invalid, re-render the context data with the
+ data-filled form and errors.
+ """
return self.render_to_response(self.get_context_data(form=form))
@@ -67,7 +77,7 @@ class ModelFormMixin(FormMixin, SingleObjectMixin):
def get_form_class(self):
"""
- Returns the form class to use in this view
+ Returns the form class to use in this view.
"""
if self.form_class:
return self.form_class
@@ -94,6 +104,9 @@ def get_form_kwargs(self):
return kwargs
def get_success_url(self):
+ """
+ Returns the supplied URL.
+ """
if self.success_url:
url = self.success_url % self.object.__dict__
else:
@@ -106,10 +119,17 @@ def get_success_url(self):
return url
def form_valid(self, form):
+ """
+ If the form is valid, save the associated model.
+ """
self.object = form.save()
return super(ModelFormMixin, self).form_valid(form)
def get_context_data(self, **kwargs):
+ """
+ If an object has been supplied, inject it into the context with the
+ supplied context_object_name name.
+ """
context = {}
if self.object:
context['object'] = self.object
@@ -122,14 +142,21 @@ def get_context_data(self, **kwargs):
class ProcessFormView(View):
"""
- A mixin that processes a form on POST.
+ A mixin that renders a form on GET and processes it on POST.
"""
def get(self, request, *args, **kwargs):
+ """
+ Handles GET requests and instantiates a blank version of the form.
+ """
form_class = self.get_form_class()
form = self.get_form(form_class)
return self.render_to_response(self.get_context_data(form=form))
def post(self, request, *args, **kwargs):
+ """
+ Handles POST requests, instantiating a form instance with the passed
+ POST variables and then checked for validity.
+ """
form_class = self.get_form_class()
form = self.get_form(form_class)
if form.is_valid():
@@ -172,7 +199,7 @@ def post(self, request, *args, **kwargs):
class CreateView(SingleObjectTemplateResponseMixin, BaseCreateView):
"""
- View for creating an new object instance,
+ View for creating a new object instance,
with a response rendered by template.
"""
template_name_suffix = '_form'
@@ -196,7 +223,7 @@ def post(self, request, *args, **kwargs):
class UpdateView(SingleObjectTemplateResponseMixin, BaseUpdateView):
"""
View for updating an object,
- with a response rendered by template..
+ with a response rendered by template.
"""
template_name_suffix = '_form'
@@ -208,6 +235,10 @@ class DeletionMixin(object):
success_url = None
def delete(self, request, *args, **kwargs):
+ """
+ Calls the delete() method on the fetched object and then
+ redirects to the success URL.
+ """
self.object = self.get_object()
self.object.delete()
return HttpResponseRedirect(self.get_success_url())
View
9 django/views/generic/list.py
@@ -8,6 +8,9 @@
class MultipleObjectMixin(ContextMixin):
+ """
+ A mixin for views manipulating multiple objects.
+ """
allow_empty = True
queryset = None
model = None
@@ -111,6 +114,9 @@ def get_context_data(self, **kwargs):
class BaseListView(MultipleObjectMixin, View):
+ """
+ A base view for displaying a list of objects.
+ """
def get(self, request, *args, **kwargs):
self.object_list = self.get_queryset()
allow_empty = self.get_allow_empty()
@@ -132,6 +138,9 @@ def get(self, request, *args, **kwargs):
class MultipleObjectTemplateResponseMixin(TemplateResponseMixin):
+ """
+ Mixin for responding with a template and list of objects.
+ """
template_name_suffix = '_list'
def get_template_names(self):
View
2  docs/glossary.txt
@@ -16,7 +16,7 @@ Glossary
A higher-order :term:`view` function that provides an abstract/generic
implementation of a common idiom or pattern found in view development.
- See :doc:`/ref/class-based-views`.
+ See :doc:`/topics/class-based-views/index`.
model
Models store your application's data.
View
2  docs/howto/static-files.txt
@@ -175,7 +175,7 @@ using :class:`~django.template.RequestContext` when rendering the template.
As a brief refresher, context processors add variables into the contexts of
every template. However, context processors require that you use
:class:`~django.template.RequestContext` when rendering templates. This happens
-automatically if you're using a :doc:`generic view </ref/class-based-views>`,
+automatically if you're using a :doc:`generic view </ref/class-based-views/index>`,
but in views written by hand you'll need to explicitly use ``RequestContext``
To see how that works, and to read more details, check out
:ref:`subclassing-context-requestcontext`.
View
7 docs/index.txt
@@ -105,9 +105,10 @@ The view layer
:doc:`Managing files <topics/files>` |
:doc:`Custom storage <howto/custom-file-storage>`
-* **Generic views:**
- :doc:`Overview<topics/class-based-views>` |
- :doc:`Built-in generic views<ref/class-based-views>`
+* **Class-based views:**
+ :doc:`Overview<topics/class-based-views/index>` |
+ :doc:`Built-in class-based views<ref/class-based-views/index>` |
+ :doc:`Built-in view mixins<ref/class-based-views/mixins>`
* **Advanced:**
:doc:`Generating CSV <howto/outputting-csv>` |
View
4 docs/internals/deprecation.txt
@@ -134,7 +134,7 @@ these changes.
* The function-based generic view modules will be removed in favor of their
class-based equivalents, outlined :doc:`here
- </topics/class-based-views>`:
+ </topics/class-based-views/index>`:
* The :class:`~django.core.servers.basehttp.AdminMediaHandler` will be
removed. In its place use
@@ -221,7 +221,7 @@ these changes.
the 1.4 release. They will be removed.
* The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been
- refactored to use class based views with pluggable backends in 1.4.
+ refactored to use class-based views with pluggable backends in 1.4.
The previous implementation will be removed.
* Legacy ways of calling
View
2  docs/intro/tutorial04.txt
@@ -320,7 +320,7 @@ function anymore -- generic views can be (and are) used multiple times
Run the server, and use your new polling app based on generic views.
For full details on generic views, see the :doc:`generic views documentation
-</topics/class-based-views>`.
+</topics/class-based-views/index>`.
Coming soon
===========
View
2  docs/misc/api-stability.txt
@@ -54,7 +54,7 @@ of 1.0. This includes these APIs:
- :doc:`HTTP request/response handling </topics/http/index>`, including file
uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
-- :doc:`Generic views </topics/class-based-views>`.
+- :doc:`Generic views </topics/class-based-views/index>`.
- :doc:`Internationalization </topics/i18n/index>`.
View
1,367 docs/ref/class-based-views.txt
@@ -1,1367 +0,0 @@
-=========================
-Class-based generic views
-=========================
-
-.. versionadded:: 1.3
-
-.. note::
- Prior to Django 1.3, generic views were implemented as functions. The
- function-based implementation has been removed in favor of the
- class-based approach described here.
-
-Writing Web applications can be monotonous, because we repeat certain patterns
-again and again. Django tries to take away some of that monotony at the model
-and template layers, but Web developers also experience this boredom at the view
-level.
-
-A general introduction to class-based generic views can be found in the
-:doc:`topic guide </topics/class-based-views>`.
-
-This reference contains details of Django's built-in generic views, along with
-a list of the keyword arguments that each generic view expects. Remember that
-arguments may either come from the URL pattern or from the ``extra_context``
-additional-information dictionary.
-
-Most generic views require the ``queryset`` key, which is a ``QuerySet``
-instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
-objects.
-
-Mixins
-======
-
-A mixin class is a way of using the inheritance capabilities of
-classes to compose a class out of smaller pieces of behavior. Django's
-class-based generic views are constructed by composing mixins into
-usable generic views.
-
-For example, the :class:`~django.views.generic.base.detail.DetailView`
-is composed from:
-
-* :class:`~django.db.views.generic.base.View`, which provides the
- basic class-based behavior
-* :class:`~django.db.views.generic.detail.SingleObjectMixin`, which
- provides the utilities for retrieving and displaying a single object
-* :class:`~django.db.views.generic.detail.SingleObjectTemplateResponseMixin`,
- which provides the tools for rendering a single object into a
- template-based response.
-
-When combined, these mixins provide all the pieces necessary to
-provide a view over a single object that renders a template to produce
-a response.
-
-Django provides a range of mixins. If you want to write your own
-generic views, you can build classes that compose these mixins in
-interesting ways. Alternatively, you can just use the pre-mixed
-`Generic views`_ that Django provides.
-
-.. note::
-
- When the documentation for a view gives the list of mixins, that view
- inherits all the properties and methods of that mixin.
-
-Simple mixins
--------------
-
-.. currentmodule:: django.views.generic.base
-
-TemplateResponseMixin
-~~~~~~~~~~~~~~~~~~~~~
-.. class:: TemplateResponseMixin()
-
- .. attribute:: template_name
-
- The path to the template to use when rendering the view.
-
- .. attribute:: response_class
-
- The response class to be returned by ``render_to_response`` method.
- Default is
- :class:`TemplateResponse <django.template.response.TemplateResponse>`.
- The template and context of ``TemplateResponse`` instances can be
- altered later (e.g. in
- :ref:`template response middleware <template-response-middleware>`).
-
- If you need custom template loading or custom context object
- instantiation, create a ``TemplateResponse`` subclass and assign it to
- ``response_class``.
-
- .. method:: render_to_response(context, **response_kwargs)
-
- Returns a ``self.response_class`` instance.
-
- If any keyword arguments are provided, they will be
- passed to the constructor of the response class.
-
- Calls :meth:`~TemplateResponseMixin.get_template_names()` to obtain the
- list of template names that will be searched looking for an existent
- template.
-
- .. method:: get_template_names()
-
- Returns a list of template names to search for when rendering the
- template.
-
- If :attr:`TemplateResponseMixin.template_name` is specified, the
- default implementation will return a list containing
- :attr:`TemplateResponseMixin.template_name` (if it is specified).
-
-
-Single object mixins
---------------------
-
-.. currentmodule:: django.views.generic.detail
-
-SingleObjectMixin
-~~~~~~~~~~~~~~~~~
-.. class:: SingleObjectMixin()
-
- .. attribute:: model
-
- The model that this view will display data for. Specifying ``model
- = Foo`` is effectively the same as specifying ``queryset =
- Foo.objects.all()``.
-
- .. attribute:: queryset
-
- A ``QuerySet`` that represents the objects. If provided, the value of
- :attr:`SingleObjectMixin.queryset` supersedes the value provided for
- :attr:`SingleObjectMixin.model`.
-
- .. attribute:: slug_field
-
- The name of the field on the model that contains the slug. By default,
- ``slug_field`` is ``'slug'``.
-
- .. attribute:: slug_url_kwarg
-
- .. versionadded:: 1.4
-
- The name of the URLConf keyword argument that contains the slug. By
- default, ``slug_url_kwarg`` is ``'slug'``.
-
- .. attribute:: pk_url_kwarg
-
- .. versionadded:: 1.4
-
- The name of the URLConf keyword argument that contains the primary key.
- By default, ``pk_url_kwarg`` is ``'pk'``.
-
- .. attribute:: context_object_name
-
- Designates the name of the variable to use in the context.
-
- .. method:: get_object(queryset=None)
-
- Returns the single object that this view will display. If
- ``queryset`` is provided, that queryset will be used as the
- source of objects; otherwise,
- :meth:`~SingleObjectMixin.get_queryset` will be used.
- ``get_object()`` looks for a
- :attr:`SingleObjectMixin.pk_url_kwarg` argument in the arguments
- to the view; if this argument is found, this method performs a
- primary-key based lookup using that value. If this argument is not
- found, it looks for a :attr:`SingleObjectMixin.slug_url_kwarg`
- argument, and performs a slug lookup using the
- :attr:`SingleObjectMixin.slug_field`.
-
- .. method:: get_queryset()
-
- Returns the queryset that will be used to retrieve the object that
- this view will display. By default,
- :meth:`~SingleObjectMixin.get_queryset` returns the value of the
- :attr:`~SingleObjectMixin.queryset` attribute if it is set, otherwise
- it constructs a :class:`QuerySet` by calling the `all()` method on the
- :attr:`~SingleObjectMixin.model` attribute's default manager.
-
- .. method:: get_context_object_name(obj)
-
- Return the context variable name that will be used to contain the
- data that this view is manipulating. If
- :attr:`~SingleObjectMixin.context_object_name` is not set, the context
- name will be constructed from the ``object_name`` of the model that
- the queryset is composed from. For example, the model ``Article``
- would have context object named ``'article'``.
-
- .. method:: get_context_data(**kwargs)
-
- Returns context data for displaying the list of objects.
-
- **Context**
-
- * ``object``: The object that this view is displaying. If
- ``context_object_name`` is specified, that variable will also be
- set in the context, with the same value as ``object``.
-
-SingleObjectTemplateResponseMixin
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. class:: SingleObjectTemplateResponseMixin()
-
- A mixin class that performs template-based response rendering for views
- that operate upon a single object instance. Requires that the view it is
- mixed with provides ``self.object``, the object instance that the view is
- operating on. ``self.object`` will usually be, but is not required to be,
- an instance of a Django model. It may be ``None`` if the view is in the
- process of constructing a new instance.
-
- **Extends**
-
- * :class:`~django.views.generic.base.TemplateResponseMixin`
-
- .. attribute:: template_name_field
-
- The field on the current object instance that can be used to determine
- the name of a candidate template. If either ``template_name_field`` or
- the value of the ``template_name_field`` on the current object instance
- is ``None``, the object will not be interrogated for a candidate
- template name.
-
- .. attribute:: template_name_suffix
-
- The suffix to append to the auto-generated candidate template name.
- Default suffix is ``_detail``.
-
- .. method:: get_template_names()
-
- Returns a list of candidate template names. Returns the following list:
-
- * the value of ``template_name`` on the view (if provided)
- * the contents of the ``template_name_field`` field on the
- object instance that the view is operating upon (if available)
- * ``<app_label>/<object_name><template_name_suffix>.html``
-
-Multiple object mixins
-----------------------
-
-.. currentmodule:: django.views.generic.list
-
-MultipleObjectMixin
-~~~~~~~~~~~~~~~~~~~
-.. class:: MultipleObjectMixin()
-
- A mixin that can be used to display a list of objects.
-
- If ``paginate_by`` is specified, Django will paginate the results returned
- by this. You can specify the page number in the URL in one of two ways:
-
- * Use the ``page`` parameter in the URLconf. For example, this is what
- your URLconf might look like::
-
- (r'^objects/page(?P<page>[0-9]+)/$', PaginatedView.as_view())
-
- * Pass the page number via the ``page`` query-string parameter. For
- example, a URL would look like this::
-
- /objects/?page=3
-
- These values and lists are 1-based, not 0-based, so the first page would be
- represented as page ``1``.
-
- For more on pagination, read the :doc:`pagination documentation
- </topics/pagination>`.
-
- As a special case, you are also permitted to use ``last`` as a value for
- ``page``::
-
- /objects/?page=last
-
- This allows you to access the final page of results without first having to
- determine how many pages there are.
-
- Note that ``page`` *must* be either a valid page number or the value
- ``last``; any other value for ``page`` will result in a 404 error.
-
- .. attribute:: allow_empty
-
- A boolean specifying whether to display the page if no objects are
- available. If this is ``False`` and no objects are available, the view
- will raise a 404 instead of displaying an empty page. By default, this
- is ``True``.
-
- .. attribute:: model
-
- The model that this view will display data for. Specifying ``model
- = Foo`` is effectively the same as specifying ``queryset =
- Foo.objects.all()``.
-
- .. attribute:: queryset
-
- A ``QuerySet`` that represents the objects. If provided, the value of
- :attr:`MultipleObjectMixin.queryset` supersedes the value provided for
- :attr:`MultipleObjectMixin.model`.
-
- .. attribute:: paginate_by
-
- An integer specifying how many objects should be displayed per page. If
- this is given, the view will paginate objects with
- :attr:`MultipleObjectMixin.paginate_by` objects per page. The view will
- expect either a ``page`` query string parameter (via ``GET``) or a
- ``page`` variable specified in the URLconf.
-
- .. attribute:: paginator_class
-
- The paginator class to be used for pagination. By default,
- :class:`django.core.paginator.Paginator` is used. If the custom paginator
- class doesn't have the same constructor interface as
- :class:`django.core.paginator.Paginator`, you will also need to
- provide an implementation for :meth:`MultipleObjectMixin.get_paginator`.
-
- .. attribute:: context_object_name
-
- Designates the name of the variable to use in the context.
-
- .. method:: get_queryset()
-
- Returns the queryset that represents the data this view will display.
-
- .. method:: paginate_queryset(queryset, page_size)
-
- Returns a 4-tuple containing (``paginator``, ``page``, ``object_list``,
- ``is_paginated``).
-
- Constructed by paginating ``queryset`` into pages of size ``page_size``.
- If the request contains a ``page`` argument, either as a captured URL
- argument or as a GET argument, ``object_list`` will correspond to the
- objects from that page.
-
- .. method:: get_paginate_by(queryset)
-
- Returns the number of items to paginate by, or ``None`` for no
- pagination. By default this simply returns the value of
- :attr:`MultipleObjectMixin.paginate_by`.
-
- .. method:: get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True)
-
- Returns an instance of the paginator to use for this view. By default,
- instantiates an instance of :attr:`paginator_class`.
-
- .. method:: get_allow_empty()
-
- Return a boolean specifying whether to display the page if no objects
- are available. If this method returns ``False`` and no objects are
- available, the view will raise a 404 instead of displaying an empty
- page. By default, this is ``True``.
-
- .. method:: get_context_object_name(object_list)
-
- Return the context variable name that will be used to contain
- the list of data that this view is manipulating. If
- ``object_list`` is a queryset of Django objects and
- :attr:`~MultipleObjectMixin.context_object_name` is not set,
- the context name will be the ``object_name`` of the model that
- the queryset is composed from, with postfix ``'_list'``
- appended. For example, the model ``Article`` would have a
- context object named ``article_list``.
-
- .. method:: get_context_data(**kwargs)
-
- Returns context data for displaying the list of objects.
-
- **Context**
-
- * ``object_list``: The list of objects that this view is displaying. If
- ``context_object_name`` is specified, that variable will also be set
- in the context, with the same value as ``object_list``.
-
- * ``is_paginated``: A boolean representing whether the results are
- paginated. Specifically, this is set to ``False`` if no page size has
- been specified, or if the available objects do not span multiple
- pages.
-
- * ``paginator``: An instance of
- :class:`django.core.paginator.Paginator`. If the page is not
- paginated, this context variable will be ``None``.
-
- * ``page_obj``: An instance of
- :class:`django.core.paginator.Page`. If the page is not paginated,
- this context variable will be ``None``.
-
-MultipleObjectTemplateResponseMixin
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. class:: MultipleObjectTemplateResponseMixin()
-
- A mixin class that performs template-based response rendering for views
- that operate upon a list of object instances. Requires that the view it is
- mixed with provides ``self.object_list``, the list of object instances that
- the view is operating on. ``self.object_list`` may be, but is not required
- to be, a :class:`~django.db.models.query.QuerySet`.
-
- **Extends**
-
- * :class:`~django.views.generic.base.TemplateResponseMixin`
-
- .. attribute:: template_name_suffix
-
- The suffix to append to the auto-generated candidate template name.
- Default suffix is ``_list``.
-
- .. method:: get_template_names()
-
- Returns a list of candidate template names. Returns the following list:
-
- * the value of ``template_name`` on the view (if provided)
- * ``<app_label>/<object_name><template_name_suffix>.html``
-
-Editing mixins
---------------
-
-.. currentmodule:: django.views.generic.edit
-
-FormMixin
-~~~~~~~~~
-.. class:: FormMixin()
-
- A mixin class that provides facilities for creating and displaying forms.
-
- .. attribute:: initial
-
- A dictionary containing initial data for the form.
-
- .. attribute:: form_class
-
- The form class to instantiate.
-
- .. attribute:: success_url
-
- The URL to redirect to when the form is successfully processed.
-
- .. method:: get_initial()
-
- Retrieve initial data for the form. By default, returns a copy of
- :attr:`.initial`.
-
- .. admonition:: Changed in 1.4
-
- In Django 1.3, this method was returning the :attr:`initial` class
- variable itself.
-
- .. method:: get_form_class()
-
- Retrieve the form class to instantiate. By default
- :attr:`.form_class`.
-
- .. method:: get_form(form_class)
-
- Instantiate an instance of ``form_class`` using
- :meth:`.get_form_kwargs`.
-
- .. method:: get_form_kwargs()
-
- Build the keyword arguments required to instantiate the form.
-
- The ``initial`` argument is set to :meth:`.get_initial`. If the
- request is a ``POST`` or ``PUT``, the request data (``request.POST``
- and ``request.FILES``) will also be provided.
-
- .. method:: get_success_url()
-
- Determine the URL to redirect to when the form is successfully
- validated. Returns :attr:`.success_url` by default.
-
- .. method:: form_valid(form)
-
- Redirects to :meth:`.get_success_url`.
-
- .. method:: form_invalid(form)
-
- Renders a response, providing the invalid form as context.
-
- .. method:: get_context_data(**kwargs)
-
- Populates a context containing the contents of ``kwargs``.
-
- **Context**
-
- * ``form``: The form instance that was generated for the view.
-
- .. note::
-
- Views mixing :class:`FormMixin` must
- provide an implementation of :meth:`.form_valid` and
- :meth:`.form_invalid`.
-
-ModelFormMixin
-~~~~~~~~~~~~~~
-.. class:: ModelFormMixin()
-
- A form mixin that works on ModelForms, rather than a standalone form.
-
- Since this is a subclass of
- :class:`~django.views.generic.detail.SingleObjectMixin`, instances of this
- mixin have access to the :attr:`~SingleObjectMixin.model` and
- :attr:`~SingleObjectMixin.queryset` attributes, describing the type of
- object that the ModelForm is manipulating. The view also provides
- ``self.object``, the instance being manipulated. If the instance is being
- created, ``self.object`` will be ``None``.
-
- **Mixins**
-
- * :class:`django.views.generic.edit.FormMixin`
- * :class:`django.views.generic.detail.SingleObjectMixin`
-
- .. attribute:: success_url
-
- The URL to redirect to when the form is successfully processed.
-
- ``success_url`` may contain dictionary string formatting, which
- will be interpolated against the object's field attributes. For
- example, you could use ``success_url="/polls/%(slug)s/"`` to
- redirect to a URL composed out of the ``slug`` field on a model.
-
- .. method:: get_form_class()
-
- Retrieve the form class to instantiate. If
- :attr:`FormMixin.form_class` is provided, that class will be used.
- Otherwise, a ModelForm will be instantiated using the model associated
- with the :attr:`~SingleObjectMixin.queryset`, or with the
- :attr:`~SingleObjectMixin.model`, depending on which attribute is
- provided.
-
- .. method:: get_form_kwargs()
-
- Add the current instance (``self.object``) to the standard
- :meth:`FormMixin.get_form_kwargs`.
-
- .. method:: get_success_url()
-
- Determine the URL to redirect to when the form is successfully
- validated. Returns :attr:`FormMixin.success_url` if it is provided;
- otherwise, attempts to use the ``get_absolute_url()`` of the object.
-
- .. method:: form_valid(form)
-
- Saves the form instance, sets the current object for the view, and
- redirects to :meth:`.get_success_url`.
-
- .. method:: form_invalid()
-
- Renders a response, providing the invalid form as context.
-
-ProcessFormView
-~~~~~~~~~~~~~~~
-.. class:: ProcessFormView()
-
- A mixin that provides basic HTTP GET and POST workflow.
-
- .. method:: get(request, *args, **kwargs)
-
- Constructs a form, then renders a response using a context that
- contains that form.
-
- .. method:: post(request, *args, **kwargs)
-
- Constructs a form, checks the form for validity, and handles it
- accordingly.
-
- The PUT action is also handled, as an analog of POST.
-
-DeletionMixin
-~~~~~~~~~~~~~
-.. class:: DeletionMixin()
-
- Enables handling of the ``DELETE`` http action.
-
- .. attribute:: success_url
-
- The url to redirect to when the nominated object has been
- successfully deleted.
-
- .. method:: get_success_url(obj)
-
- Returns the url to redirect to when the nominated object has been
- successfully deleted. Returns
- :attr:`~django.views.generic.edit.DeletionMixin.success_url` by
- default.
-
-Date-based mixins
------------------
-
-.. currentmodule:: django.views.generic.dates
-
-YearMixin
-~~~~~~~~~
-.. class:: YearMixin()
-
- A mixin that can be used to retrieve and provide parsing information for a
- year component of a date.
-
- .. attribute:: year_format
-
- The :func:`~time.strftime` format to use when parsing the year.
- By default, this is ``'%Y'``.
-
- .. attribute:: year
-
- **Optional** The value for the year (as a string). By default, set to
- ``None``, which means the year will be determined using other means.
-
- .. method:: get_year_format()
-
- Returns the :func:`~time.strftime` format to use when parsing the year. Returns
- :attr:`YearMixin.year_format` by default.
-
- .. method:: get_year()
-
- Returns the year for which this view will display data. Tries the
- following sources, in order:
-
- * The value of the :attr:`YearMixin.year` attribute.
- * The value of the `year` argument captured in the URL pattern
- * The value of the `year` GET query argument.
-
- Raises a 404 if no valid year specification can be found.
-
-MonthMixin
-~~~~~~~~~~
-.. class:: MonthMixin()
-
- A mixin that can be used to retrieve and provide parsing information for a
- month component of a date.
-
- .. attribute:: month_format
-
- The :func:`~time.strftime` format to use when parsing the month. By default, this is
- ``'%b'``.
-
- .. attribute:: month
-
- **Optional** The value for the month (as a string). By default, set to
- ``None``, which means the month will be determined using other means.
-
- .. method:: get_month_format()
-
- Returns the :func:`~time.strftime` format to use when parsing the month. Returns
- :attr:`MonthMixin.month_format` by default.
-
- .. method:: get_month()
-
- Returns the month for which this view will display data. Tries the
- following sources, in order:
-
- * The value of the :attr:`MonthMixin.month` attribute.
- * The value of the `month` argument captured in the URL pattern
- * The value of the `month` GET query argument.
-
- Raises a 404 if no valid month specification can be found.
-
- .. method:: get_next_month(date)
-
- Returns a date object containing the first day of the month after the
- date provided. Returns ``None`` if mixed with a view that sets
- ``allow_future = False``, and the next month is in the future. If
- ``allow_empty = False``, returns the next month that contains data.
-
- .. method:: get_prev_month(date)
-
- Returns a date object containing the first day of the month before the
- date provided. If ``allow_empty = False``, returns the previous month
- that contained data.
-
-DayMixin
-~~~~~~~~~
-.. class:: DayMixin()
-
- A mixin that can be used to retrieve and provide parsing information for a
- day component of a date.
-
- .. attribute:: day_format
-
- The :func:`~time.strftime` format to use when parsing the day. By default, this is
- ``'%d'``.
-
- .. attribute:: day
-
- **Optional** The value for the day (as a string). By default, set to
- ``None``, which means the day will be determined using other means.
-
- .. method:: get_day_format()
-
- Returns the :func:`~time.strftime` format to use when parsing the day. Returns
- :attr:`DayMixin.day_format` by default.
-
- .. method:: get_day()
-
- Returns the day for which this view will display data. Tries the
- following sources, in order:
-
- * The value of the :attr:`DayMixin.day` attribute.
- * The value of the `day` argument captured in the URL pattern
- * The value of the `day` GET query argument.
-
- Raises a 404 if no valid day specification can be found.
-
- .. method:: get_next_day(date)
-
- Returns a date object containing the next day after the date provided.
- Returns ``None`` if mixed with a view that sets ``allow_future = False``,
- and the next day is in the future. If ``allow_empty = False``, returns
- the next day that contains data.
-
- .. method:: get_prev_day(date)
-
- Returns a date object containing the previous day. If
- ``allow_empty = False``, returns the previous day that contained data.
-
-WeekMixin
-~~~~~~~~~
-.. class:: WeekMixin()
-
- A mixin that can be used to retrieve and provide parsing information for a
- week component of a date.
-
- .. attribute:: week_format
-
- The :func:`~time.strftime` format to use when parsing the week. By default, this is
- ``'%U'``.
-
- .. attribute:: week
-
- **Optional** The value for the week (as a string). By default, set to
- ``None``, which means the week will be determined using other means.
-
- .. method:: get_week_format()
-
- Returns the :func:`~time.strftime` format to use when parsing the week. Returns
- :attr:`WeekMixin.week_format` by default.
-
- .. method:: get_week()
-
- Returns the week for which this view will display data. Tries the
- following sources, in order:
-
- * The value of the :attr:`WeekMixin.week` attribute.
- * The value of the `week` argument captured in the URL pattern
- * The value of the `week` GET query argument.
-
- Raises a 404 if no valid week specification can be found.
-
-
-DateMixin
-~~~~~~~~~
-.. class:: DateMixin()
-
- A mixin class providing common behavior for all date-based views.
-
- .. attribute:: date_field
-
- The name of the ``DateField`` or ``DateTimeField`` in the
- ``QuerySet``'s model that the date-based archive should use to
- determine the objects on the page.
-
- When :doc:`time zone support </topics/i18n/timezones>` is enabled and
- ``date_field`` is a ``DateTimeField``, dates are assumed to be in the
- current time zone. Otherwise, the queryset could include objects from
- the previous or the next day in the end user's time zone.
-
- .. warning::
-
- In this situation, if you have implemented per-user time zone
- selection, the same URL may show a different set of objects,
- depending on the end user's time zone. To avoid this, you should
- use a ``DateField`` as the ``date_field`` attribute.
-
- .. attribute:: allow_future
-
- A boolean specifying whether to include "future" objects on this page,
- where "future" means objects in which the field specified in
- ``date_field`` is greater than the current date/time. By default, this
- is ``False``.
-
- .. method:: get_date_field()
-
- Returns the name of the field that contains the date data that this
- view will operate on. Returns :attr:`DateMixin.date_field` by default.
-
- .. method:: get_allow_future()
-
- Determine whether to include "future" objects on this page, where
- "future" means objects in which the field specified in ``date_field``
- is greater than the current date/time. Returns
- :attr:`DateMixin.allow_future` by default.
-
-BaseDateListView
-~~~~~~~~~~~~~~~~
-.. class:: BaseDateListView()
-
- A base class that provides common behavior for all date-based views. There
- won't normally be a reason to instantiate
- :class:`~django.views.generic.dates.BaseDateListView`; instantiate one of
- the subclasses instead.
-
- While this view (and it's subclasses) are executing, ``self.object_list``
- will contain the list of objects that the view is operating upon, and
- ``self.date_list`` will contain the list of dates for which data is
- available.
-
- **Mixins**
-
- * :class:`~django.views.generic.dates.DateMixin`
- * :class:`~django.views.generic.list.MultipleObjectMixin`
-
- .. attribute:: allow_empty
-
- A boolean specifying whether to display the page if no objects are
- available. If this is ``True`` and no objects are available, the view
- will display an empty page instead of raising a 404. By default, this
- is ``False``.
-
- .. method:: get_dated_items():
-
- Returns a 3-tuple containing (``date_list``, ``object_list``,
- ``extra_context``).
-
- ``date_list`` is the list of dates for which data is available.
- ``object_list`` is the list of objects. ``extra_context`` is a
- dictionary of context data that will be added to any context data
- provided by the
- :class:`~django.views.generic.list.MultipleObjectMixin`.
-
- .. method:: get_dated_queryset(**lookup)
-
- Returns a queryset, filtered using the query arguments defined by
- ``lookup``. Enforces any restrictions on the queryset, such as
- ``allow_empty`` and ``allow_future``.
-
- .. method:: get_date_list(queryset, date_type)
-
- Returns the list of dates of type ``date_type`` for which
- ``queryset`` contains entries. For example, ``get_date_list(qs,
- 'year')`` will return the list of years for which ``qs`` has entries.
- See :meth:`~django.db.models.query.QuerySet.dates()` for the
- ways that the ``date_type`` argument can be used.
-
-
-Generic views
-=============
-
-Simple generic views
---------------------
-
-.. currentmodule:: django.views.generic.base
-
-View
-~~~~
-.. class:: View()
-
- The master class-based base view. All other generic class-based views
- inherit from this base class.
-
- Each request served by a :class:`~django.views.generic.base.View` has an
- independent state; therefore, it is safe to store state variables on the
- instance (i.e., ``self.foo = 3`` is a thread-safe operation).
-
- A class-based view is deployed into a URL pattern using the
- :meth:`~View.as_view()` classmethod::
-
- urlpatterns = patterns('',
- (r'^view/$', MyView.as_view(size=42)),
- )
-
- Any argument passed into :meth:`~View.as_view()` will be assigned onto the
- instance that is used to service a request. Using the previous example,
- this means that every request on ``MyView`` is able to interrogate
- ``self.size``.
-
- .. admonition:: Thread safety with view arguments
-
- Arguments passed to a view are shared between every instance of a view.
- This means that you shoudn't use a list, dictionary, or any other
- variable object as an argument to a view. If you did, the actions of
- one user visiting your view could have an effect on subsequent users
- visiting the same view.
-
- .. method:: dispatch(request, *args, **kwargs)
-
- The ``view`` part of the view -- the method that accepts a ``request``
- argument plus arguments, and returns a HTTP response.
-
- The default implementation will inspect the HTTP method and attempt to
- delegate to a method that matches the HTTP method; a ``GET`` will be
- delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`,
- and so on.
-
- 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.
-
- .. method:: http_method_not_allowed(request, *args, **kwargs)
-
- If the view was called with HTTP method it doesn't support, this method
- is called instead.
-
- The default implementation returns ``HttpResponseNotAllowed`` with list
- of allowed methods in plain text.
-
-TemplateView
-~~~~~~~~~~~~
-.. class:: TemplateView()
-
- Renders a given template, passing it a ``{{ params }}`` template variable,
- which is a dictionary of the parameters captured in the URL.
-
- **Mixins**
-
- * :class:`django.views.generic.base.TemplateResponseMixin`
-
- .. attribute:: template_name
-
- The full name of a template to use.
-
- .. method:: get_context_data(**kwargs)
-
- Return a context data dictionary consisting of the contents of
- ``kwargs`` stored in the context variable ``params``.
-
- **Context**
-
- * ``params``: The dictionary of keyword arguments captured from the URL
- pattern that served the view.
-
-RedirectView
-~~~~~~~~~~~~
-.. class:: RedirectView()
-
- Redirects to a given URL.
-
- The given URL may contain dictionary-style string formatting, which will be
- interpolated against the parameters captured in the URL. Because keyword
- interpolation is *always* done (even if no arguments are passed in), any
- ``"%"`` characters in the URL must be written as ``"%%"`` so that Python
- will convert them to a single percent sign on output.
-
- If the given URL is ``None``, Django will return an ``HttpResponseGone``
- (410).
-
- .. attribute:: url
-
- The URL to redirect to, as a string. Or ``None`` to raise a 410 (Gone)
- HTTP error.
-
- .. attribute:: permanent
-
- Whether the redirect should be permanent. The only difference here is
- the HTTP status code returned. If ``True``, then the redirect will use
- status code 301. If ``False``, then the redirect will use status code
- 302. By default, ``permanent`` is ``True``.
-
- .. attribute:: query_string
-
- Whether to pass along the GET query string to the new location. If
- ``True``, then the query string is appended to the URL. If ``False``,
- then the query string is discarded. By default, ``query_string`` is
- ``False``.
-
- .. method:: get_redirect_url(**kwargs)
-
- Constructs the target URL for redirection.
-
- The default implementation uses :attr:`~RedirectView.url` as a starting
- string, performs expansion of ``%`` parameters in that string, as well
- as the appending of query string if requested by
- :attr:`~RedirectView.query_string`. Subclasses may implement any
- behavior they wish, as long as the method returns a redirect-ready URL
- string.
-
-Detail views
-------------
-
-.. currentmodule:: django.views.generic.detail
-
-DetailView
-~~~~~~~~~~
-.. class:: BaseDetailView()
-.. class:: DetailView()
-
- A page representing an individual object.
-
- While this view is executing, ``self.object`` will contain the object that
- the view is operating upon.
-
- :class:`~django.views.generic.base.BaseDetailView` implements the same
- behavior as :class:`~django.views.generic.base.DetailView`, but doesn't
- include the
- :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.detail.SingleObjectMixin`
- * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
-
-List views
-----------
-
-.. currentmodule:: django.views.generic.list
-
-ListView
-~~~~~~~~
-.. class:: BaseListView()
-.. class:: ListView()
-
- A page representing a list of objects.
-
- While this view is executing, ``self.object_list`` will contain the list of
- objects (usually, but not necessarily a queryset) that the view is
- operating upon.
-
- :class:`~django.views.generic.list.BaseListView` implements the same
- behavior as :class:`~django.views.generic.list.ListView`, but doesn't
- include the
- :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.list.MultipleObjectMixin`
- * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
-
-
-Editing views
--------------
-
-.. currentmodule:: django.views.generic.edit
-
-FormView
-~~~~~~~~
-.. class:: BaseFormView()
-.. class:: FormView()
-
- A view that displays a form. On error, redisplays the form with validation
- errors; on success, redirects to a new URL.
-
- :class:`~django.views.generic.edit.BaseFormView` implements the same
- behavior as :class:`~django.views.generic.edit.FormView`, but doesn't
- include the :class:`~django.views.generic.base.TemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.edit.FormMixin`
- * :class:`django.views.generic.edit.ProcessFormView`
-
-CreateView
-~~~~~~~~~~
-.. class:: BaseCreateView()
-.. class:: CreateView()
-
- A view that displays a form for creating an object, redisplaying the form
- with validation errors (if there are any) and saving the object.
-
- :class:`~django.views.generic.edit.BaseCreateView` implements the same
- behavior as :class:`~django.views.generic.edit.CreateView`, but doesn't
- include the :class:`~django.views.generic.base.TemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.edit.ModelFormMixin`
- * :class:`django.views.generic.edit.ProcessFormView`
-
-UpdateView
-~~~~~~~~~~
-.. class:: BaseUpdateView()
-.. class:: UpdateView()
-
- A view that displays a form for editing an existing object, redisplaying
- the form with validation errors (if there are any) and saving changes to
- the object. This uses a form automatically generated from the object's
- model class (unless a form class is manually specified).
-
- :class:`~django.views.generic.edit.BaseUpdateView` implements the same
- behavior as :class:`~django.views.generic.edit.UpdateView`, but doesn't
- include the :class:`~django.views.generic.base.TemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.edit.ModelFormMixin`
- * :class:`django.views.generic.edit.ProcessFormView`
-
-DeleteView
-~~~~~~~~~~
-.. class:: BaseDeleteView()
-.. class:: DeleteView()
-
- A view that displays a confirmation page and deletes an existing object.
- The given object will only be deleted if the request method is ``POST``. If
- this view is fetched via ``GET``, it will display a confirmation page that
- should contain a form that POSTs to the same URL.
-
- :class:`~django.views.generic.edit.BaseDeleteView` implements the same
- behavior as :class:`~django.views.generic.edit.DeleteView`, but doesn't
- include the :class:`~django.views.generic.base.TemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.edit.DeletionMixin`
- * :class:`django.views.generic.detail.BaseDetailView`
-
- **Notes**
-
- * The delete confirmation page displayed to a GET request uses a
- ``template_name_suffix`` of ``'_confirm_delete'``.
-
-Date-based views
-----------------
-
-Date-based generic views (in the module :mod:`django.views.generic.dates`)
-are views for displaying drilldown pages for date-based data.
-
-.. currentmodule:: django.views.generic.dates
-
-ArchiveIndexView
-~~~~~~~~~~~~~~~~
-.. class:: BaseArchiveIndexView()
-.. class:: ArchiveIndexView()
-
- A top-level index page showing the "latest" objects, by date. Objects with
- a date in the *future* are not included unless you set ``allow_future`` to
- ``True``.
-
- :class:`~django.views.generic.dates.BaseArchiveIndexView` implements the
- same behavior as :class:`~django.views.generic.dates.ArchiveIndexView`, but
- doesn't include the
- :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.dates.BaseDateListView`
- * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
-
- **Notes**
-
- * Uses a default ``context_object_name`` of ``latest``.
- * Uses a default ``template_name_suffix`` of ``_archive``.
-
-YearArchiveView
-~~~~~~~~~~~~~~~
-.. class:: BaseYearArchiveView()
-.. class:: YearArchiveView()
-
- A yearly archive page showing all available months in a given year. Objects
- with a date in the *future* are not displayed unless you set
- ``allow_future`` to ``True``.
-
- :class:`~django.views.generic.dates.BaseYearArchiveView` implements the
- same behavior as :class:`~django.views.generic.dates.YearArchiveView`, but
- doesn't include the
- :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
- * :class:`django.views.generic.dates.YearMixin`
- * :class:`django.views.generic.dates.BaseDateListView`
-
- .. attribute:: make_object_list
-
- A boolean specifying whether to retrieve the full list of objects for
- this year and pass those to the template. If ``True``, the list of
- objects will be made available to the context. By default, this is
- ``False``.
-
- .. method:: get_make_object_list()
-
- Determine if an object list will be returned as part of the context. If
- ``False``, the ``None`` queryset will be used as the object list.
-
- **Context**
-
- In addition to the context provided by
- :class:`django.views.generic.list.MultipleObjectMixin` (via
- :class:`django.views.generic.dates.BaseDateListView`), the template's
- context will be:
-
- * ``date_list``: A ``DateQuerySet`` object containing all months that
- have objects available according to ``queryset``, represented as
- ``datetime.datetime`` objects, in ascending order.
-
- * ``year``: A ``datetime.date`` object representing the given year.
-
- * ``next_year``: A ``datetime.date`` object representing the first day
- of the next year. If the next year is in the future, this will be
- ``None``.
-
- * ``previous_year``: A ``datetime.date`` object representing the first
- day of the previous year. Unlike ``next_year``, this will never be
- ``None``.
-
- **Notes**
-
- * Uses a default ``template_name_suffix`` of ``_archive_year``.
-
-MonthArchiveView
-~~~~~~~~~~~~~~~~
-.. class:: BaseMonthArchiveView()
-.. class:: MonthArchiveView()
-
- A monthly archive page showing all objects in a given month. Objects with a
- date in the *future* are not displayed unless you set ``allow_future`` to
- ``True``.
-
- :class:`~django.views.generic.dates.BaseMonthArchiveView` implements
- the same behavior as
- :class:`~django.views.generic.dates.MonthArchiveView`, but doesn't
- include the
- :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
- * :class:`django.views.generic.dates.YearMixin`
- * :class:`django.views.generic.dates.MonthMixin`
- * :class:`django.views.generic.dates.BaseDateListView`
-
- **Context**
-
- In addition to the context provided by
- :class:`~django.views.generic.list.MultipleObjectMixin` (via
- :class:`~django.views.generic.dates.BaseDateListView`), the template's
- context will be:
-
- * ``date_list``: A ``DateQuerySet`` object containing all days that
- have objects available in the given month, according to ``queryset``,
- represented as ``datetime.datetime`` objects, in ascending order.
-
- * ``month``: A ``datetime.date`` object representing the given month.
-
- * ``next_month``: A ``datetime.date`` object representing the first day
- of the next month. If the next month is in the future, this will be
- ``None``.
-
- * ``previous_month``: A ``datetime.date`` object representing the first
- day of the previous month. Unlike ``next_month``, this will never be
- ``None``.
-
- **Notes**
-
- * Uses a default ``template_name_suffix`` of ``_archive_month``.
-
-WeekArchiveView
-~~~~~~~~~~~~~~~
-.. class:: BaseWeekArchiveView()
-.. class:: WeekArchiveView()
-
- A weekly archive page showing all objects in a given week. Objects with a
- date in the *future* are not displayed unless you set ``allow_future`` to
- ``True``.
-
- :class:`~django.views.generic.dates.BaseWeekArchiveView` implements the
- same behavior as :class:`~django.views.generic.dates.WeekArchiveView`, but
- doesn't include the
- :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
- * :class:`django.views.generic.dates.YearMixin`
- * :class:`django.views.generic.dates.MonthMixin`
- * :class:`django.views.generic.dates.BaseDateListView`
-
- **Context**
-
- In addition to the context provided by
- :class:`~django.views.generic.list.MultipleObjectMixin` (via
- :class:`~django.views.generic.dates.BaseDateListView`), the template's
- context will be:
-
- * ``week``: A ``datetime.date`` object representing the first day of
- the given week.
-
- * ``next_week``: A ``datetime.date`` object representing the first day
- of the next week. If the next week is in the future, this will be
- ``None``.
-
- * ``previous_week``: A ``datetime.date`` object representing the first
- day of the previous week. Unlike ``next_week``, this will never be
- ``None``.
-
- **Notes**
-
- * Uses a default ``template_name_suffix`` of ``_archive_week``.
-
-DayArchiveView
-~~~~~~~~~~~~~~
-.. class:: BaseDayArchiveView()
-.. class:: DayArchiveView()
-
- A day archive page showing all objects in a given day. Days in the future
- throw a 404 error, regardless of whether any objects exist for future days,
- unless you set ``allow_future`` to ``True``.
-
- :class:`~django.views.generic.dates.BaseDayArchiveView` implements the same
- behavior as :class:`~django.views.generic.dates.DayArchiveView`, but
- doesn't include the
- :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
- * :class:`django.views.generic.dates.YearMixin`
- * :class:`django.views.generic.dates.MonthMixin`
- * :class:`django.views.generic.dates.DayMixin`
- * :class:`django.views.generic.dates.BaseDateListView`
-
- **Context**
-
- In addition to the context provided by
- :class:`~django.views.generic.list.MultipleObjectMixin` (via
- :class:`~django.views.generic.dates.BaseDateListView`), the template's
- context will be:
-
- * ``day``: A ``datetime.date`` object representing the given day.
-
- * ``next_day``: A ``datetime.date`` object representing the next day.
- If the next day is in the future, this will be ``None``.
-
- * ``previous_day``: A ``datetime.date`` object representing the
- previous day. Unlike ``next_day``, this will never be ``None``.
-
- * ``next_month``: A ``datetime.date`` object representing the first day
- of the next month. If the next month is in the future, this will be
- ``None``.
-
- * ``previous_month``: A ``datetime.date`` object representing the first
- day of the previous month. Unlike ``next_month``, this will never be
- ``None``.
-
- **Notes**
-
- * Uses a default ``template_name_suffix`` of ``_archive_day``.
-
-TodayArchiveView
-~~~~~~~~~~~~~~~~
-.. class:: BaseTodayArchiveView()
-.. class:: TodayArchiveView()
-
- A day archive page showing all objects for *today*. This is exactly the
- same as :class:`django.views.generic.dates.DayArchiveView`, except today's
- date is used instead of the ``year``/``month``/``day`` arguments.
-
- :class:`~django.views.generic.dates.BaseTodayArchiveView` implements the
- same behavior as :class:`~django.views.generic.dates.TodayArchiveView`, but
- doesn't include the
- :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
- * :class:`django.views.generic.dates.BaseDayArchiveView`
-
-DateDetailView
-~~~~~~~~~~~~~~
-.. class:: BaseDateDetailView()
-.. class:: DateDetailView()
-
- A page representing an individual object. If the object has a date value in
- the future, the view will throw a 404 error by default, unless you set
- ``allow_future`` to ``True``.
-
- :class:`~django.views.generic.dates.BaseDateDetailView` implements the same
- behavior as :class:`~django.views.generic.dates.DateDetailView`, but
- doesn't include the
- :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
-
- **Mixins**
-
- * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
- * :class:`django.views.generic.detail.BaseDetailView`
- * :class:`django.views.generic.dates.DateMixin`
- * :class:`django.views.generic.dates.YearMixin`
- * :class:`django.views.generic.dates.MonthMixin`
- * :class:`django.views.generic.dates.DayMixin`
View
224 docs/ref/class-based-views/base.txt
@@ -0,0 +1,224 @@
+==========
+Base views
+==========
+
+The following three classes provide much of the functionality needed to create
+Django views. You may think of them as *parent* views, which can be used by
+themselves or inherited from. They may not provide all the capabilities
+required for projects, in which case there are Mixins and Generic class-based
+views.
+
+.. class:: django.views.generic.base.View
+
+ The master class-based base view. All other class-based views inherit from
+ this base class.
+
+ **Method Flowchart**
+
+ 1. :meth:`dispatch()`
+ 2. :meth:`http_method_not_allowed()`
+
+ **Example views.py**::
+
+ from django.http import HttpResponse
+ from django.views.generic import View
+
+ class MyView(View):
+
+ def get(self, request, *args, **kwargs):
+ return HttpResponse('Hello, World!')
+
+ **Example urls.py**::
+
+ from django.conf.urls import patterns, url
+
+ from myapp.views import MyView
+
+ urlpatterns = patterns('',
+ url(r'^mine/$', MyView.as_view(), name='my-view'),
+ )
+
+ **Methods**
+
+ .. method:: dispatch(request, *args, **kwargs)
+
+ The ``view`` part of the view -- the method that accepts a ``request``
+ argument plus arguments, and returns a HTTP response.
+
+ The default implementation will inspect the HTTP method and attempt to
+ delegate to a method that matches the HTTP method; a ``GET`` will be
+ delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`,
+ and so on.
+
+ 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.
+
+ .. method:: http_method_not_allowed(request, *args, **kwargs)
+
+ If the view was called with a HTTP method it doesn't support, this
+ method is called instead.
+
+ The default implementation returns ``HttpResponseNotAllowed`` with list
+ of allowed methods in plain text.
+
+ .. note::
+
+ Documentation on class-based views is a work in progress. As yet, only the
+ methods defined directly on the class are documented here, not methods
+ defined on superclasses.
+
+.. class:: django.views.generic.base.TemplateView
+
+ Renders a given template, passing it a ``{{ params }}`` template variable,
+ which is a dictionary of the parameters captured in the URL.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.base.TemplateView`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Method Flowchart**
+
+ 1. :meth:`dispatch()`
+ 2. :meth:`http_method_not_allowed()`
+ 3. :meth:`get_context_data()`
+
+ **Example views.py**::
+
+ from django.views.generic.base import TemplateView
+
+ from articles.models import Article
+
+ class HomePageView(TemplateView):
+
+ template_name = "home.html"
+
+ def get_context_data(self, **kwargs):
+ context = super(HomePageView, self).get_context_data(**kwargs)
+ context['latest_articles'] = Article.objects.all()[:5]
+ return context
+
+ **Example urls.py**::
+
+ from django.conf.urls import patterns, url
+
+ from myapp.views import HomePageView
+
+ urlpatterns = patterns('',
+ url(r'^$', HomePageView.as_view(), name='home'),
+ )
+
+ **Methods and Attributes**
+
+ .. attribute:: template_name
+
+ The full name of a template to use.
+
+ .. method:: get_context_data(**kwargs)
+
+ Return a context data dictionary consisting of the contents of
+ ``kwargs`` stored in the context variable ``params``.
+
+ **Context**
+
+ * ``params``: The dictionary of keyword arguments captured from the URL
+ pattern that served the view.
+
+ .. note::
+
+ Documentation on class-based views is a work in progress. As yet, only the
+ methods defined directly on the class are documented here, not methods
+ defined on superclasses.
+
+.. class:: django.views.generic.base.RedirectView
+
+ Redirects to a given URL.
+
+ The given URL may contain dictionary-style string formatting, which will be
+ interpolated against the parameters captured in the URL. Because keyword
+ interpolation is *always* done (even if no arguments are passed in), any
+ ``"%"`` characters in the URL must be written as ``"%%"`` so that Python
+ will convert them to a single percent sign on output.
+
+ If the given URL is ``None``, Django will return an ``HttpResponseGone``
+ (410).
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.base.View`
+
+ **Method Flowchart**
+
+ 1. :meth:`dispatch()`
+ 2. :meth:`http_method_not_allowed()`
+ 3. :meth:`get_redirect_url()`
+
+ **Example views.py**::
+
+ from django.shortcuts import get_object_or_404
+ from django.views.generic.base import RedirectView
+
+ from articles.models import Article
+
+ class ArticleCounterRedirectView(RedirectView):
+
+ permanent = False
+ query_string = True
+
+ def get_redirect_url(self, pk):
+ article = get_object_or_404(Article, pk=pk)
+ article.update_counter()
+ return reverse('product_detail', args=(pk,))
+
+ **Example urls.py**::
+
+ from django.conf.urls import patterns, url
+ from django.views.generic.base import RedirectView
+
+ from article.views import ArticleCounterRedirectView
+
+ urlpatterns = patterns('',
+
+ url(r'r^(?P<pk>\d+)/$', ArticleCounterRedirectView.as_view(), name='article-counter'),
+ url(r'^go-to-django/$', RedirectView.as_view(url='http://djangoproject.com'), name='go-to-django'),
+ )
+
+ **Methods and Attributes**
+
+ .. attribute:: url
+
+ The URL to redirect to, as a string. Or ``None`` to raise a 410 (Gone)
+ HTTP error.
+
+ .. attribute:: permanent
+
+ Whether the redirect should be permanent. The only difference here is
+ the HTTP status code returned. If ``True``, then the redirect will use
+ status code 301. If ``False``, then the redirect will use status code
+ 302. By default, ``permanent`` is ``True``.
+
+ .. attribute:: query_string
+
+ Whether to pass along the GET query string to the new location. If
+ ``True``, then the query string is appended to the URL. If ``False``,
+ then the query string is discarded. By default, ``query_string`` is
+ ``False``.
+
+ .. method:: get_redirect_url(**kwargs)
+
+ Constructs the target URL for redirection.
+
+ The default implementation uses :attr:`~RedirectView.url` as a starting
+ string, performs expansion of ``%`` parameters in that string, as well
+ as the appending of query string if requested by
+ :attr:`~RedirectView.query_string`. Subclasses may implement any
+ behavior they wish, as long as the method returns a redirect-ready URL
+ string.
+
+ .. note::
+
+ Documentation on class-based views is a work in progress. As yet, only the
+ methods defined directly on the class are documented here, not methods
+ defined on superclasses.
View
273 docs/ref/class-based-views/generic-date-based.txt
@@ -0,0 +1,273 @@
+==================
+Generic date views
+==================
+
+Date-based generic views (in the module :mod:`django.views.generic.dates`)
+are views for displaying drilldown pages for date-based data.
+
+.. class:: django.views.generic.dates.ArchiveIndexView
+
+ A top-level index page showing the "latest" objects, by date. Objects with
+ a date in the *future* are not included unless you set ``allow_future`` to
+ ``True``.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.dates.ArchiveIndexView`
+ * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.dates.BaseArchiveIndexView`
+ * :class:`django.views.generic.dates.BaseDateListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Notes**
+
+ * Uses a default ``context_object_name`` of ``latest``.
+ * Uses a default ``template_name_suffix`` of ``_archive``.
+
+.. class:: django.views.generic.dates.YearArchiveView
+
+ A yearly archive page showing all available months in a given year. Objects
+ with a date in the *future* are not displayed unless you set
+ ``allow_future`` to ``True``.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.dates.YearArchiveView`
+ * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.dates.BaseYearArchiveView`
+ * :class:`django.views.generic.dates.YearMixin`
+ * :class:`django.views.generic.dates.BaseDateListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.base.View`
+
+ .. attribute:: make_object_list
+
+ A boolean specifying whether to retrieve the full list of objects for
+ this year and pass those to the template. If ``True``, the list of
+ objects will be made available to the context. By default, this is
+ ``False``.
+
+ .. method:: get_make_object_list()
+
+ Determine if an object list will be returned as part of the context. If
+ ``False``, the ``None`` queryset will be used as the object list.
+
+ **Context**
+
+ In addition to the context provided by
+ :class:`django.views.generic.list.MultipleObjectMixin` (via
+ :class:`django.views.generic.dates.BaseDateListView`), the template's
+ context will be:
+
+ * ``date_list``: A
+ :meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object object
+ containing all months that have objects available according to
+ ``queryset``, represented as
+ :class:`datetime.datetime<python:datetime.datetime>` objects, in
+ ascending order.
+
+ * ``year``: A :class:`datetime.date<python:datetime.date>` object
+ representing the given year.
+
+ * ``next_year``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the next year. If the next year is in the
+ future, this will be ``None``.
+
+ * ``previous_year``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the previous year. Unlike ``next_year``,
+ this will never be ``None``.
+
+ **Notes**
+
+ * Uses a default ``template_name_suffix`` of ``_archive_year``.
+
+.. class:: django.views.generic.dates.MonthArchiveView
+
+ A monthly archive page showing all objects in a given month. Objects with a
+ date in the *future* are not displayed unless you set ``allow_future`` to
+ ``True``.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.dates.MonthArchiveView`
+ * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.dates.BaseMonthArchiveView`
+ * :class:`django.views.generic.dates.YearMixin`
+ * :class:`django.views.generic.dates.MonthMixin`
+ * :class:`django.views.generic.dates.BaseDateListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Context**
+
+ In addition to the context provided by
+ :class:`~django.views.generic.list.MultipleObjectMixin` (via
+ :class:`~django.views.generic.dates.BaseDateListView`), the template's
+ context will be:
+
+ * ``date_list``: A
+ :meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object
+ containing all days that have objects available in the given month,
+ according to ``queryset``, represented as
+ :class:`datetime.datetime<python:datetime.datetime>` objects, in
+ ascending order.
+
+ * ``month``: A :class:`datetime.date<python:datetime.date>` object
+ representing the given month.
+
+ * ``next_month``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the next month. If the next month is in the
+ future, this will be ``None``.
+
+ * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the previous month. Unlike ``next_month``,
+ this will never be ``None``.
+
+ **Notes**
+
+ * Uses a default ``template_name_suffix`` of ``_archive_month``.
+
+.. class:: django.views.generic.dates.WeekArchiveView
+
+ A weekly archive page showing all objects in a given week. Objects with a
+ date in the *future* are not displayed unless you set ``allow_future`` to
+ ``True``.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.dates.WeekArchiveView`
+ * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.dates.BaseWeekArchiveView`
+ * :class:`django.views.generic.dates.YearMixin`
+ * :class:`django.views.generic.dates.WeekMixin`
+ * :class:`django.views.generic.dates.BaseDateListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Context**
+
+ In addition to the context provided by
+ :class:`~django.views.generic.list.MultipleObjectMixin` (via
+ :class:`~django.views.generic.dates.BaseDateListView`), the template's
+ context will be:
+
+ * ``week``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the given week.
+
+ * ``next_week``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the next week. If the next week is in the
+ future, this will be ``None``.
+
+ * ``previous_week``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the previous week. Unlike ``next_week``,
+ this will never be ``None``.
+
+ **Notes**
+
+ * Uses a default ``template_name_suffix`` of ``_archive_week``.
+
+.. class:: django.views.generic.dates.DayArchiveView
+
+ A day archive page showing all objects in a given day. Days in the future
+ throw a 404 error, regardless of whether any objects exist for future days,
+ unless you set ``allow_future`` to ``True``.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.dates.DayArchiveView`
+ * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.dates.BaseDayArchiveView`
+ * :class:`django.views.generic.dates.YearMixin`
+ * :class:`django.views.generic.dates.MonthMixin`
+ * :class:`django.views.generic.dates.DayMixin`
+ * :class:`django.views.generic.dates.BaseDateListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Context**
+
+ In addition to the context provided by
+ :class:`~django.views.generic.list.MultipleObjectMixin` (via
+ :class:`~django.views.generic.dates.BaseDateListView`), the template's
+ context will be:
+
+ * ``day``: A :class:`datetime.date<python:datetime.date>` object
+ representing the given day.
+
+ * ``next_day``: A :class:`datetime.date<python:datetime.date>` object
+ representing the next day. If the next day is in the future, this will be
+ ``None``.
+
+ * ``previous_day``: A :class:`datetime.date<python:datetime.date>` object
+ representing the previous day. Unlike ``next_day``, this will never be
+ ``None``.
+
+ * ``next_month``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the next month. If the next month is in the
+ future, this will be ``None``.
+
+ * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object
+ representing the first day of the previous month. Unlike ``next_month``,
+ this will never be ``None``.
+
+ **Notes**
+
+ * Uses a default ``template_name_suffix`` of ``_archive_day``.
+
+.. class:: django.views.generic.dates.TodayArchiveView
+
+ A day archive page showing all objects for *today*. This is exactly the
+ same as :class:`django.views.generic.dates.DayArchiveView`, except today's
+ date is used instead of the ``year``/``month``/``day`` arguments.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.dates.TodayArchiveView`
+ * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.dates.BaseTodayArchiveView`
+ * :class:`django.views.generic.dates.BaseDayArchiveView`
+ * :class:`django.views.generic.dates.YearMixin`
+ * :class:`django.views.generic.dates.MonthMixin`
+ * :class:`django.views.generic.dates.DayMixin`
+ * :class:`django.views.generic.dates.BaseDateListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.base.View`
+
+.. class:: django.views.generic.dates.DateDetailView
+
+ A page representing an individual object. If the object has a date value in
+ the future, the view will throw a 404 error by default, unless you set
+ ``allow_future`` to ``True``.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.dates.DateDetailView`
+ * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.dates.BaseDateDetailView`
+ * :class:`django.views.generic.dates.YearMixin`
+ * :class:`django.views.generic.dates.MonthMixin`
+ * :class:`django.views.generic.dates.DayMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.detail.BaseDetailView`
+ * :class:`django.views.generic.detail.SingleObjectMixin`
+ * :class:`django.views.generic.base.View`
+
+.. note::
+
+ All of the generic views listed above have matching Base* views that only
+ differ in that the they do not include the
+ :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
View
86 docs/ref/class-based-views/generic-display.txt
@@ -0,0 +1,86 @@
+=====================
+Generic display views
+=====================
+
+The two following generic class-based views are designed to display data. On
+many projects they are typically the most commonly used views.
+
+.. class:: django.views.generic.detail.DetailView
+
+ While this view is executing, ``self.object`` will contain the object that
+ the view is operating upon.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.detail.BaseDetailView`
+ * :class:`django.views.generic.detail.SingleObjectMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Method Flowchart**
+
+ 1. :meth:`dispatch()`
+ 2. :meth:`http_method_not_allowed()`
+ 3. :meth:`get_template_names()`
+ 4. :meth:`get_slug_field()`
+ 5. :meth:`get_queryset()`
+ 6. :meth:`get_object()`
+ 7. :meth:`get_context_object_name()`
+ 8. :meth:`get_context_data()`
+ 9. :meth:`get()`
+ 10. :meth:`render_to_response()`
+
+ **Example views.py**::
+
+ from django.views.generic.detail import DetailView
+ from django.utils import timezone
+
+ from articles.models import Article
+
+ class ArticleDetailView(DetailView):
+
+ model = Article
+
+ def get_context_data(self, **kwargs):
+ context = super(ArticleDetailView, self).get_context_data(**kwargs)
+ context['now'] = timezone.now()
+ return context
+
+ **Example urls.py**::
+
+ from django.conf.urls import patterns, url
+
+ from article.views import ArticleDetailView
+
+ urlpatterns = patterns('',
+ url(r'^(?P<slug>[-_\w]+)/$', ArticleDetailView.as_view(), 'article-detail'),
+ )
+
+.. class:: django.views.generic.list.ListView
+
+ A page representing a list of objects.
+
+ While this view is executing, ``self.object_list`` will contain the list of
+ objects (usually, but not necessarily a queryset) that the view is
+ operating upon.
+
+ **Mixins**
+
+ * :class:`django.views.generic.list.ListView`
+ * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.list.BaseListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Method Flowchart**
+
+ 1. :meth:`dispatch():`
+ 2. :meth:`http_method_not_allowed():`
+ 3. :meth:`get_template_names():`
+ 4. :meth:`get_queryset():`
+ 5. :meth:`get_objects():`
+ 6. :meth:`get_context_data():`
+ 7. :meth:`get():`
+ 8. :meth:`render_to_response():`
View
78 docs/ref/class-based-views/generic-editing.txt
@@ -0,0 +1,78 @@
+=====================
+Generic editing views
+=====================
+
+The views described here provide a foundation for editing content.
+
+.. class:: django.views.generic.edit.FormView
+
+ A view that displays a form. On error, redisplays the form with validation
+ errors; on success, redirects to a new URL.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.edit.FormView`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.edit.BaseFormView`
+ * :class:`django.views.generic.edit.FormMixin`
+ * :class:`django.views.generic.edit.ProcessFormView`
+ * :class:`django.views.generic.base.View`
+
+.. class:: django.views.generic.edit.CreateView
+
+ A view that displays a form for creating an object, redisplaying the form
+ with validation errors (if there are any) and saving the object.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.edit.CreateView`
+ * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.edit.BaseCreateView`
+ * :class:`django.views.generic.edit.ModelFormMixin`
+ * :class:`django.views.generic.edit.FormMixin`
+ * :class:`django.views.generic.detail.SingleObjectMixin`
+ * :class:`django.views.generic.edit.ProcessFormView`
+ * :class:`django.views.generic.base.View`
+
+.. class:: django.views.generic.edit.UpdateView
+
+ A view that displays a form for editing an existing object, redisplaying
+ the form with validation errors (if there are any) and saving changes to
+ the object. This uses a form automatically generated from the object's
+ model class (unless a form class is manually specified).
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.edit.UpdateView`
+ * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.edit.BaseUpdateView`
+ * :class:`django.views.generic.edit.ModelFormMixin`
+ * :class:`django.views.generic.edit.FormMixin`
+ * :class:`django.views.generic.detail.SingleObjectMixin`
+ * :class:`django.views.generic.edit.ProcessFormView`
+ * :class:`django.views.generic.base.View`
+
+.. class:: django.views.generic.edit.DeleteView
+
+ A view that displays a confirmation page and deletes an existing object.
+ The given object will only be deleted if the request method is ``POST``. If
+ this view is fetched via ``GET``, it will display a confirmation page that
+ should contain a form that POSTs to the same URL.
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.edit.DeleteView`
+ * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.edit.BaseDeleteView`
+ * :class:`django.views.generic.edit.DeletionMixin`
+ * :class:`django.views.generic.detail.BaseDetailView`
+ * :class:`django.views.generic.detail.SingleObjectMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Notes**
+
+ * The delete confirmation page displayed to a GET request uses a
+ ``template_name_suffix`` of ``'_confirm_delete'``.
View
59 docs/ref/class-based-views/index.txt
@@ -0,0 +1,59 @@
+=================
+Class-based views
+=================
+
+Class-based views API reference. For introductory material, see
+:doc:`/topics/class-based-views/index`.
+
+.. toctree::
+ :maxdepth: 1
+
+ base
+ generic-display
+ generic-editing
+ generic-date-based
+ mixins
+
+Specification
+-------------
+
+Each request served by a class-based view has an independent state; therefore,
+it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
+a thread-safe operation).
+
+A class-based view is deployed into a URL pattern using the
+:meth:`~View.as_view()` classmethod::
+
+ urlpatterns = patterns('',
+ (r'^view/$', MyView.as_view(size=42)),
+ )
+
+.. admonition:: Thread safety with view arguments
+
+ Arguments passed to a view are shared between every instance of a view.
+ This means that you shoudn't use a list, dictionary, or any other
+ variable object as an argument to a view. If you did, the actions of
+ one user visiting your view could have an effect on subsequent users
+ visiting the same view.
+
+Any argument passed into :meth:`~View.as_view()` will be assigned onto the
+instance that is used to service a request. Using the previous example,
+this means that every request on ``MyView`` is able to use ``self.size``.
+
+Base vs Generic views
+---------------------
+
+Base class-based views can be thought of as *parent* views, which can be
+used by themselves or inherited from. They may not provide all the
+capabilities required for projects, in which case there are Mixins which
+extend what base views can do.
+
+Django’s generic views are built off of those base views, and were developed
+as a shortcut for common usage patterns such as displaying the details of an
+object. They take certain common idioms and patterns found in view
+development and abstract them so that you can quickly write common views of
+data without having to repeat yourself.
+
+Most generic views require the ``queryset`` key, which is a ``QuerySet``
+instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
+objects.
View
256 docs/ref/class-based-views/mixins-date-based.txt
@@ -0,0 +1,256 @@
+=================
+Date-based mixins
+=================
+
+
+.. class:: django.views.generic.dates.YearMixin
+
+ A mixin that can be used to retrieve and provide parsing information for a
+ year component of a date.
+
+ **Methods and Attributes**
+
+ .. attribute:: year_format
+
+ The :func:`~time.strftime` format to use when parsing the year.
+ By default, this is ``'%Y'``.
+
+ .. attribute:: year
+
+ **Optional** The value for the year (as a string). By default, set to
+ ``None``, which means the year will be determined using other means.
+
+ .. method:: get_year_format()
+
+ Returns the :func:`~time.strftime` format to use when parsing the year. Returns
+ :attr:`YearMixin.year_format` by default.
+
+ .. method:: get_year()
+
+ Returns the year for which this view will display data. Tries the
+ following sources, in order:
+
+ * The value of the :attr:`YearMixin.year` attribute.
+ * The value of the `year` argument captured in the URL pattern
+ * The value of the `year` GET query argument.
+
+ Raises a 404 if no valid year specification can be found.
+
+.. class:: django.views.generic.dates.MonthMixin
+
+ A mixin that can be used to retrieve and provide parsing information for a