Commits

Samuel Martin  committed 4be69dd

Ajout fichers manquants ref

  • Participants
  • Parent commits d0091c4

Comments (0)

Files changed (71)

File ref/class-based-views.txt

+=========================
+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 deprecated in favor of the
+    class-based approach described here.
+
+    For details on the previous generic views implementation,
+    see the :doc:`topic guide </topics/generic-views>` and
+    :doc:`detailed reference </ref/generic-views>`.
+
+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>`).
+
+        Create TemplateResponse subclass and pass set it to
+        ``template_response_class`` if you need custom template loading or
+        custom context object instantiation.
+
+    .. method:: render_to_response(context, **response_kwargs)
+
+        Returns a ``self.template_response_class`` instance.
+
+        If any keyword arguments are provided, they will be
+        passed to the constructor of the response instance.
+
+        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:: 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.
+        :meth:`~SingleObjectMixin.get_object` looks for a ``pk``
+        argument in the arguments to the view; if ``pk`` is found,
+        this method performs a primary-key based lookup using that
+        value. If no ``pk`` argument is found, it looks for a ``slug``
+        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.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
+        :attr:`.initial`.
+
+    .. 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 requried to instanciate an 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()
+
+        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 strftime_ format to use when parsing the year. By default, this is
+        ``'%Y'``.
+
+    .. _strftime: http://docs.python.org/library/time.html#time.strftime
+
+    .. 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 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 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 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 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 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 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 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.
+
+    .. 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.date_field` 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 ``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_dated_items():
+
+        Returns a 3-tuple containing (``date_list``, ``latest``,
+        ``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.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.ModelFormMixin`
+      * :class:`django.views.generic.edit.ProcessFormView`
+
+    **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``: The given year, as a four-character string.
+
+    **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.
+
+    **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 ``archive_day``, except the ``year``/``month``/``day`` arguments
+    are not used,
+
+    :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.dates.DayArchiveView`
+
+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.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`

File ref/contrib/admin/_images/.svn/all-wcprops

+K 25
+svn:wc:ra_dav:version-url
+V 63
+/svn/!svn/ver/12107/django/trunk/docs/ref/contrib/admin/_images
+END
+user_actions.png
+K 25
+svn:wc:ra_dav:version-url
+V 80
+/svn/!svn/ver/12107/django/trunk/docs/ref/contrib/admin/_images/user_actions.png
+END
+flatfiles_admin.png
+K 25
+svn:wc:ra_dav:version-url
+V 83
+/svn/!svn/ver/10121/django/trunk/docs/ref/contrib/admin/_images/flatfiles_admin.png
+END
+users_changelist.png
+K 25
+svn:wc:ra_dav:version-url
+V 84
+/svn/!svn/ver/10121/django/trunk/docs/ref/contrib/admin/_images/users_changelist.png
+END
+article_actions.png
+K 25
+svn:wc:ra_dav:version-url
+V 83
+/svn/!svn/ver/12107/django/trunk/docs/ref/contrib/admin/_images/article_actions.png
+END
+article_actions_message.png
+K 25
+svn:wc:ra_dav:version-url
+V 91
+/svn/!svn/ver/12107/django/trunk/docs/ref/contrib/admin/_images/article_actions_message.png
+END

File ref/contrib/admin/_images/.svn/entries

+10
+
+dir
+16243
+http://code.djangoproject.com/svn/django/trunk/docs/ref/contrib/admin/_images
+http://code.djangoproject.com/svn
+
+
+
+2010-01-05T18:24:27.742068Z
+12107
+jezdez
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+bcc190cf-cafb-0310-a4f2-bffc1f526a37
+
+user_actions.png
+file
+
+
+
+
+2011-03-24T19:51:10.360450Z
+e627a392b26802c5cf2474cbd0ebf834
+2010-01-05T18:24:27.742068Z
+12107
+jezdez
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+27047
+
+flatfiles_admin.png
+file
+
+
+
+
+2011-03-24T19:51:10.360450Z
+0523b6df409c2d990d04ddc7346b79d1
+2009-03-23T20:22:56.201328Z
+10121
+jacob
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+42243
+
+users_changelist.png
+file
+
+
+
+
+2011-03-24T19:51:10.360450Z
+43f94018c74ed669af11405c42bc0a82
+2009-03-23T20:22:56.201328Z
+10121
+jacob
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+59355
+
+article_actions.png
+file
+
+
+
+
+2011-03-24T19:51:10.360450Z
+738c6a40b8c26d6b642defa9c219da1b
+2010-01-05T18:24:27.742068Z
+12107
+jezdez
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+38545
+
+article_actions_message.png
+file
+
+
+
+
+2011-03-24T19:51:10.360450Z
+ba50597d14be9ad5ef57007e1f472f3d
+2010-01-05T18:24:27.742068Z
+12107
+jezdez
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+22098
+

File ref/contrib/admin/_images/.svn/text-base/article_actions.png.svn-base

Binary file added.

File ref/contrib/admin/_images/.svn/text-base/article_actions_message.png.svn-base

Binary file added.

File ref/contrib/admin/_images/.svn/text-base/flatfiles_admin.png.svn-base

Binary file added.

File ref/contrib/admin/_images/.svn/text-base/user_actions.png.svn-base

Binary file added.

File ref/contrib/admin/_images/.svn/text-base/users_changelist.png.svn-base

Binary file added.

File ref/contrib/admin/_images/article_actions.png

Added
New image

File ref/contrib/admin/_images/article_actions_message.png

Added
New image

File ref/contrib/admin/_images/flatfiles_admin.png

Added
New image

File ref/contrib/admin/_images/user_actions.png

Added
New image

File ref/contrib/admin/_images/users_changelist.png

Added
New image

File ref/contrib/admin/actions.txt

+=============
+Admin actions
+=============
+
+.. currentmodule:: django.contrib.admin
+
+The basic workflow of Django's admin is, in a nutshell, "select an object,
+then change it." This works well for a majority of use cases. However, if you
+need to make the same change to many objects at once, this workflow can be
+quite tedious.
+
+In these cases, Django's admin lets you write and register "actions" -- simple
+functions that get called with a list of objects selected on the change list
+page.
+
+If you look at any change list in the admin, you'll see this feature in
+action; Django ships with a "delete selected objects" action available to all
+models. For example, here's the user module from Django's built-in
+:mod:`django.contrib.auth` app:
+
+.. image:: _images/user_actions.png
+
+.. warning::
+
+    The "delete selected objects" action uses :meth:`QuerySet.delete()
+    <django.db.models.QuerySet.delete>` for efficiency reasons, which has an
+    important caveat: your model's ``delete()`` method will not be called.
+    
+    If you wish to override this behavior, simply write a custom action which
+    accomplishes deletion in your preferred manner -- for example, by calling
+    ``Model.delete()`` for each of the selected items.
+    
+    For more background on bulk deletion, see the documentation on :ref:`object
+    deletion <topics-db-queries-delete>`.
+
+Read on to find out how to add your own actions to this list.
+
+Writing actions
+===============
+
+The easiest way to explain actions is by example, so let's dive in.
+
+A common use case for admin actions is the bulk updating of a model. Imagine a
+simple news application with an ``Article`` model::
+
+    from django.db import models
+
+    STATUS_CHOICES = (
+        ('d', 'Draft'),
+        ('p', 'Published'),
+        ('w', 'Withdrawn'),
+    )
+
+    class Article(models.Model):
+        title = models.CharField(max_length=100)
+        body = models.TextField()
+        status = models.CharField(max_length=1, choices=STATUS_CHOICES)
+    
+        def __unicode__(self):
+            return self.title
+        
+A common task we might perform with a model like this is to update an
+article's status from "draft" to "published". We could easily do this in the
+admin one article at a time, but if we wanted to bulk-publish a group of
+articles, it'd be tedious. So, let's write an action that lets us change an
+article's status to "published."
+
+Writing action functions
+------------------------
+
+First, we'll need to write a function that gets called when the action is
+trigged from the admin. Action functions are just regular functions that take
+three arguments: 
+    
+    * The current :class:`ModelAdmin`
+    * An :class:`~django.http.HttpRequest` representing the current request,
+    * A :class:`~django.db.models.QuerySet` containing the set of objects
+      selected by the user.
+
+Our publish-these-articles function won't need the :class:`ModelAdmin` or the
+request object, but we will use the queryset::
+
+    def make_published(modeladmin, request, queryset):
+        queryset.update(status='p')
+        
+.. note::
+
+    For the best performance, we're using the queryset's :ref:`update method
+    <topics-db-queries-update>`. Other types of actions might need to deal
+    with each object individually; in these cases we'd just iterate over the
+    queryset::
+    
+        for obj in queryset:
+            do_something_with(obj)
+            
+That's actually all there is to writing an action! However, we'll take one
+more optional-but-useful step and give the action a "nice" title in the admin.
+By default, this action would appear in the action list as "Make published" --
+the function name, with underscores replaced by spaces. That's fine, but we
+can provide a better, more human-friendly name by giving the
+``make_published`` function a ``short_description`` attribute::
+
+    def make_published(modeladmin, request, queryset):
+        queryset.update(status='p')
+    make_published.short_description = "Mark selected stories as published"
+    
+.. note::
+
+    This might look familiar; the admin's ``list_display`` option uses the
+    same technique to provide human-readable descriptions for callback
+    functions registered there, too.
+    
+Adding actions to the :class:`ModelAdmin`
+-----------------------------------------
+
+Next, we'll need to inform our :class:`ModelAdmin` of the action. This works
+just like any other configuration option. So, the complete ``admin.py`` with
+the action and its registration would look like::
+
+    from django.contrib import admin
+    from myapp.models import Article
+
+    def make_published(modeladmin, request, queryset):
+        queryset.update(status='p')
+    make_published.short_description = "Mark selected stories as published"
+
+    class ArticleAdmin(admin.ModelAdmin):
+        list_display = ['title', 'status']
+        ordering = ['title']
+        actions = [make_published]
+
+    admin.site.register(Article, ArticleAdmin)
+    
+That code will give us an admin change list that looks something like this:
+
+.. image:: _images/article_actions.png
+    
+That's really all there is to it! If you're itching to write your own actions,
+you now know enough to get started. The rest of this document just covers more
+advanced techniques.
+
+Advanced action techniques
+==========================
+
+There's a couple of extra options and possibilities you can exploit for more
+advanced options.
+
+Actions as :class:`ModelAdmin` methods
+--------------------------------------
+
+The example above shows the ``make_published`` action defined as a simple
+function. That's perfectly fine, but it's not perfect from a code design point
+of view: since the action is tightly coupled to the ``Article`` object, it
+makes sense to hook the action to the ``ArticleAdmin`` object itself.
+
+That's easy enough to do::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        ...
+        
+        actions = ['make_published']
+
+        def make_published(self, request, queryset):
+            queryset.update(status='p')
+        make_published.short_description = "Mark selected stories as published"
+        
+Notice first that we've moved ``make_published`` into a method and renamed the
+`modeladmin` parameter to `self`, and second that we've now put the string
+``'make_published'`` in ``actions`` instead of a direct function reference. This
+tells the :class:`ModelAdmin` to look up the action as a method.
+
+Defining actions as methods gives the action more straightforward, idiomatic
+access to the :class:`ModelAdmin` itself, allowing the action to call any of the
+methods provided by the admin.
+
+.. _custom-admin-action:
+
+For example, we can use ``self`` to flash a message to the user informing her
+that the action was successful::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        ...
+
+        def make_published(self, request, queryset):
+            rows_updated = queryset.update(status='p')
+            if rows_updated == 1:
+                message_bit = "1 story was"
+            else:
+                message_bit = "%s stories were" % rows_updated
+            self.message_user(request, "%s successfully marked as published." % message_bit)
+
+This make the action match what the admin itself does after successfully
+performing an action:
+
+.. image:: _images/article_actions_message.png
+    
+Actions that provide intermediate pages
+---------------------------------------
+
+By default, after an action is performed the user is simply redirected back
+to the original change list page. However, some actions, especially more
+complex ones, will need to return intermediate pages. For example, the
+built-in delete action asks for confirmation before deleting the selected
+objects.
+
+To provide an intermediary page, simply return an
+:class:`~django.http.HttpResponse` (or subclass) from your action. For
+example, you might write a simple export function that uses Django's
+:doc:`serialization functions </topics/serialization>` to dump some selected
+objects as JSON::
+
+    from django.http import HttpResponse
+    from django.core import serializers
+
+    def export_as_json(modeladmin, request, queryset):
+        response = HttpResponse(mimetype="text/javascript")
+        serializers.serialize("json", queryset, stream=response)
+        return response
+
+Generally, something like the above isn't considered a great idea. Most of the
+time, the best practice will be to return an
+:class:`~django.http.HttpResponseRedirect` and redirect the user to a view
+you've written, passing the list of selected objects in the GET query string.
+This allows you to provide complex interaction logic on the intermediary
+pages. For example, if you wanted to provide a more complete export function,
+you'd want to let the user choose a format, and possibly a list of fields to
+include in the export. The best thing to do would be to write a small action
+that simply redirects to your custom export view::
+
+    from django.contrib import admin
+    from django.contrib.contenttypes.models import ContentType
+    from django.http import HttpResponseRedirect
+    
+    def export_selected_objects(modeladmin, request, queryset):
+        selected = request.POST.getlist(admin.ACTION_CHECKBOX_NAME)
+        ct = ContentType.objects.get_for_model(queryset.model)
+        return HttpResponseRedirect("/export/?ct=%s&ids=%s" % (ct.pk, ",".join(selected)))
+
+As you can see, the action is the simple part; all the complex logic would
+belong in your export view. This would need to deal with objects of any type,
+hence the business with the ``ContentType``.
+
+Writing this view is left as an exercise to the reader.
+
+.. _adminsite-actions:
+
+Making actions available site-wide
+----------------------------------
+
+.. method:: AdminSite.add_action(action[, name])
+
+    Some actions are best if they're made available to *any* object in the admin
+    site -- the export action defined above would be a good candidate. You can
+    make an action globally available using :meth:`AdminSite.add_action()`. For
+    example::
+
+        from django.contrib import admin
+        
+        admin.site.add_action(export_selected_objects)
+
+    This makes the `export_selected_objects` action globally available as an
+    action named `"export_selected_objects"`. You can explicitly give the action
+    a name -- good if you later want to programatically :ref:`remove the action
+    <disabling-admin-actions>` -- by passing a second argument to
+    :meth:`AdminSite.add_action()`::
+    
+        admin.site.add_action(export_selected_objects, 'export_selected')
+
+.. _disabling-admin-actions:
+
+Disabling actions
+-----------------
+
+Sometimes you need to disable certain actions -- especially those
+:ref:`registered site-wide <adminsite-actions>` -- for particular objects.
+There's a few ways you can disable actions:
+
+Disabling a site-wide action
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. method:: AdminSite.disable_action(name)
+
+    If you need to disable a :ref:`site-wide action <adminsite-actions>` you can
+    call :meth:`AdminSite.disable_action()`.
+    
+    For example, you can use this method to remove the built-in "delete selected
+    objects" action::
+    
+        admin.site.disable_action('delete_selected')
+        
+    Once you've done the above, that action will no longer be available
+    site-wide.
+    
+    If, however, you need to re-enable a globally-disabled action for one
+    particular model, simply list it explicitly in your ``ModelAdmin.actions``
+    list::
+    
+        # Globally disable delete selected
+        admin.site.disable_action('delete_selected')
+        
+        # This ModelAdmin will not have delete_selected available
+        class SomeModelAdmin(admin.ModelAdmin):
+            actions = ['some_other_action']
+            ...
+            
+        # This one will
+        class AnotherModelAdmin(admin.ModelAdmin):
+            actions = ['delete_selected', 'a_third_action']
+            ...
+            
+
+Disabling all actions for a particular :class:`ModelAdmin`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want *no* bulk actions available for a given :class:`ModelAdmin`, simply
+set :attr:`ModelAdmin.actions` to ``None``::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        actions = None
+        
+This tells the :class:`ModelAdmin` to not display or allow any actions,
+including any :ref:`site-wide actions <adminsite-actions>`.
+
+Conditionally enabling or disabling actions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. method:: ModelAdmin.get_actions(request)
+
+    Finally, you can conditionally enable or disable actions on a per-request 
+    (and hence per-user basis) by overriding :meth:`ModelAdmin.get_actions`.
+
+    This returns a dictionary of actions allowed. The keys are action names, and
+    the values are ``(function, name, short_description)`` tuples.
+
+    Most of the time you'll use this method to conditionally remove actions from
+    the list gathered by the superclass. For example, if I only wanted users
+    whose names begin with 'J' to be able to delete objects in bulk, I could do
+    the following::
+    
+        class MyModelAdmin(admin.ModelAdmin):
+            ...
+            
+            def get_actions(self, request):
+                actions = super(MyModelAdmin, self).get_actions(request)
+                if request.user.username[0].upper() != 'J':
+                    del actions['delete_selected']
+                return actions
+    
+

File ref/contrib/admin/admindocs.txt

+========================================
+The Django admin documentation generator
+========================================
+
+.. module:: django.contrib.admindocs
+    :synopsis: Django's admin documentation generator.
+
+.. currentmodule:: django.contrib.admindocs
+
+Django's :mod:`~django.contrib.admindocs` app pulls documentation from the
+docstrings of models, views, template tags, and template filters for any app in
+:setting:`INSTALLED_APPS` and makes that documentation available from the
+:mod:`Django admin <django.contrib.admin>`.
+
+In addition to providing offline documentation for all template tags and
+template filters that ship with Django, you may utilize admindocs to quickly
+document your own code.
+
+Overview
+========
+
+To activate the :mod:`~django.contrib.admindocs`, you will need to do
+the following:
+
+    * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.
+    * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to
+      your :data:`urlpatterns`. Make sure it's included *before* the
+      ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get
+      handled by the latter entry.
+    * Install the docutils Python module (http://docutils.sf.net/).
+    * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR`
+      setting to be configured.
+    * **Optional:** Using the admindocs bookmarklets requires the
+      :mod:`XViewMiddleware<django.middleware.doc>` to be installed.
+
+Once those steps are complete, you can start browsing the documentation by
+going to your admin interface and clicking the "Documentation" link in the
+upper right of the page.
+
+Documentation helpers
+=====================
+
+The following special markup can be used in your docstrings to easily create