diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index 42448ebc80..e717a89b1f 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -8,6 +8,11 @@ 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. +Many of Django's built-in class-based views inherit from other class-based +views or various mixins. Because this inheritence chain is very important, the +ancestor classes are documented under the section title of **Ancestors (MRO)**. +MRO is an acronym for Method Resolution Order. + View ---- @@ -20,6 +25,7 @@ View 1. :meth:`dispatch()` 2. :meth:`http_method_not_allowed()` + 3. :meth:`options()` **Example views.py**:: @@ -41,6 +47,12 @@ View url(r'^mine/$', MyView.as_view(), name='my-view'), ) + **Attributes** + + .. attribute:: http_method_names = ['get', 'post', 'put', 'delete', 'head', 'options', 'trace'] + + The default list of HTTP method names that this view will accept. + **Methods** .. classmethod:: as_view(**initkwargs) @@ -68,14 +80,13 @@ View 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. + The default implementation returns ``HttpResponseNotAllowed`` with a + list of allowed methods in plain text. - .. note:: + .. method:: options(request, *args, **kwargs) - 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. + Handles responding to requests for the OPTIONS HTTP verb. Returns a + list of the allowed HTTP method names for the view. TemplateView ------------ @@ -87,6 +98,8 @@ TemplateView **Ancestors (MRO)** + This view inherits methods and attributes from the following views: + * :class:`django.views.generic.base.TemplateView` * :class:`django.views.generic.base.TemplateResponseMixin` * :class:`django.views.generic.base.View` @@ -122,28 +135,11 @@ TemplateView 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. - RedirectView ------------ @@ -162,6 +158,8 @@ RedirectView **Ancestors (MRO)** + This view inherits methods and attributes from the following view: + * :class:`django.views.generic.base.View` **Method Flowchart** @@ -200,7 +198,7 @@ RedirectView url(r'^go-to-django/$', RedirectView.as_view(url='http://djangoproject.com'), name='go-to-django'), ) - **Methods and Attributes** + **Attributes** .. attribute:: url @@ -221,6 +219,8 @@ RedirectView then the query string is discarded. By default, ``query_string`` is ``False``. + **Methods** + .. method:: get_redirect_url(**kwargs) Constructs the target URL for redirection. @@ -231,9 +231,3 @@ RedirectView :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. diff --git a/docs/ref/class-based-views/generic-display.txt b/docs/ref/class-based-views/generic-display.txt index ef3bc179ee..12603ff0df 100644 --- a/docs/ref/class-based-views/generic-display.txt +++ b/docs/ref/class-based-views/generic-display.txt @@ -15,6 +15,8 @@ DetailView **Ancestors (MRO)** + This view inherits methods and attributes from the following views: + * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` * :class:`django.views.generic.base.TemplateResponseMixin` * :class:`django.views.generic.detail.BaseDetailView` @@ -71,7 +73,9 @@ ListView objects (usually, but not necessarily a queryset) that the view is operating upon. - **Mixins** + **Ancestors (MRO)** + + This view inherits methods and attributes from the following views: * :class:`django.views.generic.list.ListView` * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` @@ -90,3 +94,54 @@ ListView 6. :meth:`get_context_data()` 7. :meth:`get()` 8. :meth:`render_to_response()` + + + **Example views.py**:: + + from django.views.generic.list import ListView + from django.utils import timezone + + from articles.models import Article + + class ArticleListView(ListView): + + model = Article + + def get_context_data(self, **kwargs): + context = super(ArticleListView, 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 ArticleListView + + urlpatterns = patterns('', + url(r'^$', ArticleListView.as_view(), name='article-list'), + ) + +.. class:: django.views.generic.list.BaseListView + + A base view for displaying a list of objects. It is not intended to be used + directly, but rather as a parent class of the + :class:`django.views.generic.list.ListView` or other views representing + lists of objects. + + **Ancestors (MRO)** + + This view inherits methods and attributes from the following views: + + * :class:`django.views.generic.list.MultipleObjectMixin` + * :class:`django.views.generic.base.View` + + **Methods** + + .. method:: get(request, *args, **kwargs) + + Adds :attr:`object_list` to the context. If + :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` + is True then display an empty list. If + :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` is + False then raise a 404 error. diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt index 8bc613b887..cdb743fcbd 100644 --- a/docs/ref/class-based-views/mixins-multiple-object.txt +++ b/docs/ref/class-based-views/mixins-multiple-object.txt @@ -86,7 +86,8 @@ MultipleObjectMixin .. method:: get_queryset() - Returns the queryset that represents the data this view will display. + Get the list of items for this view. This must be an iterable and may + be a queryset (in which queryset-specific behavior will be enabled). .. method:: paginate_queryset(queryset, page_size) diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt index 61fc945cd3..d2f0df241e 100644 --- a/docs/ref/class-based-views/mixins-simple.txt +++ b/docs/ref/class-based-views/mixins-simple.txt @@ -9,16 +9,17 @@ ContextMixin .. versionadded:: 1.5 - **classpath** - - ``django.views.generic.base.ContextMixin`` - **Methods** .. method:: get_context_data(**kwargs) Returns a dictionary representing the template context. The keyword - arguments provided will make up the returned context. + arguments provided will make up the returned context. Example usage:: + + def get_context_data(self, **kwargs): + context = super(RandomNumberView, self).get_context_data(**kwargs) + context['number'] = random.randrange(1, 100) + return context The template context of all class-based generic views include a ``view`` variable that points to the ``View`` instance. @@ -42,7 +43,13 @@ TemplateResponseMixin suitable context. The template to use is configurable and can be further customized by subclasses. - **Methods and Attributes** + **Attributes** + + .. attribute:: template_name + + The full name of a template to use as defined by a string. Not defining + a template_name will raise a + :class:`django.core.exceptions.ImproperlyConfigured` exception. .. attribute:: response_class @@ -57,12 +64,14 @@ TemplateResponseMixin instantiation, create a ``TemplateResponse`` subclass and assign it to ``response_class``. + **Methods** + .. 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. + 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