mirror of https://github.com/django/django.git
Contains several fixes for docs/ref/class-based-views, as follows:
Restored the section headings which duplicate the class directives (removed in [14264]) so that a full table of contents is still generated. Thanks to Jacob for the suggestion. Fixed a handful of typos, and corrected a method directive that was mistakenly labeled as an attribute. Expanded method descriptions for SingleObjectMixin to better explain the default behaviors. Reformatted ProcessFormView docs to be consistent. Added missing description of MultipleObjectMixin.get_paginate_by. git-svn-id: http://code.djangoproject.com/svn/django/trunk@14266 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Gabriel Hurley
parent
c498d2f9b4
commit
cc9e5213f8
|
|
@ -9,20 +9,20 @@ Class-based generic views
|
|||
function-based implementation has been deprecated in favor of the
|
||||
class-based approach described here.
|
||||
|
||||
For the reference to the old on details on the old implementation,
|
||||
For details on the previous generic views implementation,
|
||||
see the :doc:`topic guide </topics/generic-views>` and
|
||||
:doc:`detailed reference </topics/generic-views>`.
|
||||
|
||||
Writing Web applications can be monotonous, because we repeat certain patterns
|
||||
again and again. In Django, the most common of these patterns have been
|
||||
abstracted into "generic views" that let you quickly provide common views of
|
||||
an object without actually needing to write any Python code.
|
||||
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 generic views can be found in the :doc:`topic guide
|
||||
</topics/class-based-views>`.
|
||||
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 all keyword arguments that a generic view expects. Remember that
|
||||
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.
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ 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 a mixins into
|
||||
class-based generic views are constructed by composing mixins into
|
||||
usable generic views.
|
||||
|
||||
For example, the :class:`~django.views.generic.base.detail.DetailView`
|
||||
|
|
@ -53,19 +53,23 @@ 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.
|
||||
|
||||
When the documentation for a view gives the list of mixins, that view
|
||||
inherits all the properties and methods of that mixin.
|
||||
|
||||
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
|
||||
|
|
@ -77,7 +81,7 @@ Simple mixins
|
|||
Returns a full composed HttpResponse instance, ready to be returned to
|
||||
the user.
|
||||
|
||||
Calls, :meth:`~TemplateResponseMixin.render_template()` to build the
|
||||
Calls :meth:`~TemplateResponseMixin.render_template()` to build the
|
||||
content of the response, and
|
||||
:meth:`~TemplateResponseMixin.get_response()` to construct the
|
||||
:class:`~django.http.HttpResponse` object.
|
||||
|
|
@ -112,7 +116,8 @@ Simple mixins
|
|||
|
||||
.. method:: get_template_names()
|
||||
|
||||
The list of template names to search for when rendering the template.
|
||||
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
|
||||
|
|
@ -128,6 +133,8 @@ Single object mixins
|
|||
|
||||
.. currentmodule:: django.views.generic.detail
|
||||
|
||||
SingleObjectMixin
|
||||
~~~~~~~~~~~~~~~~~
|
||||
.. class:: SingleObjectMixin()
|
||||
|
||||
.. attribute:: model
|
||||
|
|
@ -153,15 +160,21 @@ Single object mixins
|
|||
|
||||
.. method:: get_queryset()
|
||||
|
||||
Returns the queryset that will be used to retrieve the object that this
|
||||
view will display.
|
||||
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(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, the context name will be verbose plural name of the
|
||||
model that the queryset is composed from.
|
||||
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
|
||||
:class:`QuerySet` of Django objects and
|
||||
:attr:`~SingleObjectMixin.context_object_name` is not set, the context
|
||||
name will be constructed from the verbose plural name of the model that
|
||||
the queryset is composed from.
|
||||
|
||||
.. method:: get_context_data(**kwargs)
|
||||
|
||||
|
|
@ -173,6 +186,9 @@ Single object mixins
|
|||
``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
|
||||
|
|
@ -213,6 +229,8 @@ Multiple object mixins
|
|||
|
||||
.. currentmodule:: django.views.generic.list
|
||||
|
||||
MultipleObjectMixin
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
.. class:: MultipleObjectMixin()
|
||||
|
||||
A mixin that can be used to display a list of objects.
|
||||
|
|
@ -293,6 +311,10 @@ Multiple object mixins
|
|||
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_allow_empty()
|
||||
|
||||
|
|
@ -331,6 +353,8 @@ Multiple object mixins
|
|||
: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
|
||||
|
|
@ -360,6 +384,8 @@ Editing mixins
|
|||
|
||||
.. currentmodule:: django.views.generic.edit
|
||||
|
||||
FormMixin
|
||||
~~~~~~~~~
|
||||
.. class:: FormMixin()
|
||||
|
||||
A mixin class that provides facilities for creating and displaying forms.
|
||||
|
|
@ -413,12 +439,14 @@ Editing mixins
|
|||
|
||||
* ``form``: The form instance that was generated for the view.
|
||||
|
||||
**Notes**
|
||||
.. note::
|
||||
|
||||
* Views mixing :class:`~django.views.generic.edit.FormMixin` must
|
||||
provide an implementation of :meth:`~FormMixin.form_valid()` and
|
||||
:meth:`~FormMixin.form_invalid()`.
|
||||
Views mixing :class:`~django.views.generic.edit.FormMixin` must
|
||||
provide an implementation of :meth:`~FormMixin.form_valid` and
|
||||
:meth:`~FormMixin.form_invalid`.
|
||||
|
||||
ModelFormMixin
|
||||
~~~~~~~~~~~~~~
|
||||
.. class:: ModelFormMixin()
|
||||
|
||||
A form mixin that works on ModelForms, rather than a standalone form.
|
||||
|
|
@ -471,20 +499,26 @@ Editing mixins
|
|||
|
||||
Renders a response, providing the invalid form as context.
|
||||
|
||||
ProcessFormView
|
||||
~~~~~~~~~~~~~~~
|
||||
.. class:: ProcessFormView()
|
||||
|
||||
A mixin that provides basic HTTP GET and POST workflow.
|
||||
|
||||
On GET:
|
||||
* Construct a form
|
||||
* Render a response using a context that contains that form
|
||||
.. method:: get(request, *args, **kwargs)
|
||||
|
||||
Constructs a form, then renders a response using a context that
|
||||
contains that form.
|
||||
|
||||
On POST:
|
||||
* Construct a form
|
||||
* Check the form for validity, and handle accordingly.
|
||||
.. 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.
|
||||
|
|
@ -494,7 +528,7 @@ Editing mixins
|
|||
The url to redirect to when the nominated object has been
|
||||
successfully deleted.
|
||||
|
||||
.. attribute:: get_success_url(obj)
|
||||
.. method:: get_success_url(obj)
|
||||
|
||||
Returns the url to redirect to when the nominated object has been
|
||||
successfully deleted. Returns
|
||||
|
|
@ -506,6 +540,8 @@ 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
|
||||
|
|
@ -539,6 +575,8 @@ Date-based mixins
|
|||
|
||||
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
|
||||
|
|
@ -583,6 +621,8 @@ Date-based mixins
|
|||
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
|
||||
|
|
@ -626,6 +666,8 @@ Date-based mixins
|
|||
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
|
||||
|
|
@ -658,6 +700,8 @@ Date-based mixins
|
|||
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.
|
||||
|
|
@ -687,6 +731,8 @@ Date-based mixins
|
|||
is greater than the current date/time. Returns
|
||||
:attr:`DateMixin.date_field` by default.
|
||||
|
||||
BaseDateListView
|
||||
~~~~~~~~~~~~~~~~
|
||||
.. class:: BaseDateListView()
|
||||
|
||||
A base class that provides common behavior for all date-based views. There
|
||||
|
|
@ -745,6 +791,8 @@ Simple generic views
|
|||
|
||||
.. currentmodule:: django.views.generic.base
|
||||
|
||||
View
|
||||
~~~~
|
||||
.. class:: View()
|
||||
|
||||
The master class-based base view. All other generic class-based views
|
||||
|
|
@ -796,6 +844,8 @@ Simple generic views
|
|||
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,
|
||||
|
|
@ -819,6 +869,8 @@ Simple generic views
|
|||
* ``params``: The dictionary of keyword arguments captured from the URL
|
||||
pattern that served the view.
|
||||
|
||||
RedirectView
|
||||
~~~~~~~~~~~~
|
||||
.. class:: RedirectView()
|
||||
|
||||
Redirects to a given URL.
|
||||
|
|
@ -867,6 +919,8 @@ Detail views
|
|||
|
||||
.. currentmodule:: django.views.generic.detail
|
||||
|
||||
DetailView
|
||||
~~~~~~~~~~
|
||||
.. class:: BaseDetailView()
|
||||
.. class:: DetailView()
|
||||
|
||||
|
|
@ -890,6 +944,8 @@ List views
|
|||
|
||||
.. currentmodule:: django.views.generic.list
|
||||
|
||||
ListView
|
||||
~~~~~~~~
|
||||
.. class:: BaseListView()
|
||||
.. class:: ListView()
|
||||
|
||||
|
|
@ -915,6 +971,8 @@ Editing views
|
|||
|
||||
.. currentmodule:: django.views.generic.edit
|
||||
|
||||
FormView
|
||||
~~~~~~~~
|
||||
.. class:: BaseFormView()
|
||||
.. class:: FormView()
|
||||
|
||||
|
|
@ -930,6 +988,8 @@ Editing views
|
|||
* :class:`django.views.generic.edit.FormMixin`
|
||||
* :class:`django.views.generic.edit.ProcessFormView`
|
||||
|
||||
CreateView
|
||||
~~~~~~~~~~
|
||||
.. class:: BaseCreateView()
|
||||
.. class:: CreateView()
|
||||
|
||||
|
|
@ -945,6 +1005,8 @@ Editing views
|
|||
* :class:`django.views.generic.edit.ModelFormMixin`
|
||||
* :class:`django.views.generic.edit.ProcessFormView`
|
||||
|
||||
UpdateView
|
||||
~~~~~~~~~~
|
||||
.. class:: BaseUpdateView()
|
||||
.. class:: UpdateView()
|
||||
|
||||
|
|
@ -962,6 +1024,8 @@ Editing views
|
|||
* :class:`django.views.generic.edit.ModelFormMixin`
|
||||
* :class:`django.views.generic.edit.ProcessFormView`
|
||||
|
||||
DeleteView
|
||||
~~~~~~~~~~
|
||||
.. class:: BaseDeleteView()
|
||||
.. class:: DeleteView()
|
||||
|
||||
|
|
@ -992,6 +1056,8 @@ are views for displaying drilldown pages for date-based data.
|
|||
|
||||
.. currentmodule:: django.views.generic.dates
|
||||
|
||||
ArchiveIndexView
|
||||
~~~~~~~~~~~~~~~~
|
||||
.. class:: BaseArchiveIndexView()
|
||||
.. class:: ArchiveIndexView()
|
||||
|
||||
|
|
@ -1012,9 +1078,10 @@ are views for displaying drilldown pages for date-based data.
|
|||
**Notes**
|
||||
|
||||
* Uses a default ``context_object_name`` of ``latest``.
|
||||
|
||||
* Uses a default ``template_name_suffix`` of ``_archive``.
|
||||
|
||||
YearArchiveView
|
||||
~~~~~~~~~~~~~~~
|
||||
.. class:: BaseYearArchiveView()
|
||||
.. class:: YearArchiveView()
|
||||
|
||||
|
|
@ -1062,6 +1129,8 @@ are views for displaying drilldown pages for date-based data.
|
|||
|
||||
* Uses a default ``template_name_suffix`` of ``_archive_year``.
|
||||
|
||||
MonthArchiveView
|
||||
~~~~~~~~~~~~~~~~
|
||||
.. class:: BaseMonthArchiveView()
|
||||
.. class:: MonthArchiveView()
|
||||
|
||||
|
|
@ -1107,6 +1176,8 @@ are views for displaying drilldown pages for date-based data.
|
|||
|
||||
* Uses a default ``template_name_suffix`` of ``_archive_month``.
|
||||
|
||||
WeekArchiveView
|
||||
~~~~~~~~~~~~~~~
|
||||
.. class:: BaseWeekArchiveView()
|
||||
.. class:: WeekArchiveView()
|
||||
|
||||
|
|
@ -1140,6 +1211,8 @@ are views for displaying drilldown pages for date-based data.
|
|||
|
||||
* Uses a default ``template_name_suffix`` of ``_archive_week``.
|
||||
|
||||
DayArchiveView
|
||||
~~~~~~~~~~~~~~
|
||||
.. class:: BaseDayArchiveView()
|
||||
.. class:: DayArchiveView()
|
||||
|
||||
|
|
@ -1187,6 +1260,8 @@ are views for displaying drilldown pages for date-based data.
|
|||
|
||||
* Uses a default ``template_name_suffix`` of ``_archive_day``.
|
||||
|
||||
TodayArchiveView
|
||||
~~~~~~~~~~~~~~~~
|
||||
.. class:: BaseTodayArchiveView()
|
||||
.. class:: TodayArchiveView()
|
||||
|
||||
|
|
@ -1203,6 +1278,8 @@ are views for displaying drilldown pages for date-based data.
|
|||
|
||||
* :class:`django.views.generic.dates.DayArchiveView`
|
||||
|
||||
DateDetailView
|
||||
~~~~~~~~~~~~~~
|
||||
.. class:: BaseDateDetailView()
|
||||
.. class:: DateDetailView()
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue