mixins-editing.txt

==============
Editing mixins
==============

The following mixins are used to construct Django's editing views:

* :class:`django.views.generic.edit.FormMixin`
* :class:`django.views.generic.edit.ModelFormMixin`
* :class:`django.views.generic.edit.ProcessFormView`
* :class:`django.views.generic.edit.DeletionMixin`

.. note::

    Examples of how these are combined into editing views can be found at
    the documentation on :doc:`/ref/class-based-views/generic-editing`.

``FormMixin``
=============

.. class:: django.views.generic.edit.FormMixin

    A mixin class that provides facilities for creating and displaying forms.

    **Mixins**

    * :class:`django.views.generic.base.ContextMixin`

    **Methods and Attributes**

    .. 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.

    .. attribute:: prefix

        The :attr:`~django.forms.Form.prefix` for the generated form.

    .. method:: get_initial()

        Retrieve initial data for the form. By default, returns a copy of
        :attr:`~django.views.generic.edit.FormMixin.initial`.

    .. method:: get_form_class()

        Retrieve the form class to instantiate. By default
        :attr:`~django.views.generic.edit.FormMixin.form_class`.

    .. method:: get_form(form_class=None)

        Instantiate an instance of ``form_class`` using
        :meth:`~django.views.generic.edit.FormMixin.get_form_kwargs`.
        If ``form_class`` isn't provided :meth:`get_form_class` will be used.

    .. method:: get_form_kwargs()

        Build the keyword arguments required to instantiate the form.

        The ``initial`` argument is set to :meth:`.get_initial`. If the
        request is a ``POST`` or ``PUT``, the request data (``request.POST``
        and ``request.FILES``) will also be provided.

    .. method:: get_prefix()

        Determine the :attr:`~django.forms.Form.prefix` for the generated form.
        Returns :attr:`~django.views.generic.edit.FormMixin.prefix` by default.

    .. method:: get_success_url()

        Determine the URL to redirect to when the form is successfully
        validated. Returns
        :attr:`~django.views.generic.edit.FormMixin.success_url` by default.

    .. method:: form_valid(form)

        Redirects to
        :meth:`~django.views.generic.edit.FormMixin.get_success_url`.

    .. method:: form_invalid(form)

        Renders a response, providing the invalid form as context.

    .. method:: get_context_data(**kwargs)

        Calls :meth:`get_form` and adds the result to the context data with the
        name 'form'.

``ModelFormMixin``
==================

.. class:: django.views.generic.edit.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:`~django.views.generic.detail.SingleObjectMixin.model` and
    :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` attributes,
    describing the type of object that the ``ModelForm`` is manipulating.

    If you specify both the
    :attr:`~django.views.generic.edit.ModelFormMixin.fields` and
    :attr:`~django.views.generic.edit.FormMixin.form_class` attributes, an
    :exc:`~django.core.exceptions.ImproperlyConfigured` exception will be
    raised.

    **Mixins**

    * :class:`django.views.generic.edit.FormMixin`
    * :class:`django.views.generic.detail.SingleObjectMixin`

    **Methods and Attributes**

    .. attribute:: model

        A model class. Can be explicitly provided, otherwise will be determined
        by examining ``self.object`` or
        :attr:`~django.views.generic.detail.SingleObjectMixin.queryset`.

    .. attribute:: fields

        A list of names of fields. This is interpreted the same way as the
        ``Meta.fields`` attribute of :class:`~django.forms.ModelForm`.

        This is a required attribute if you are generating the form class
        automatically (e.g. using ``model``). Omitting this attribute will
        result in an :exc:`~django.core.exceptions.ImproperlyConfigured`
        exception.

    .. 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}/"`` 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:`~django.views.generic.edit.FormMixin.form_class` is provided,
        that class will be used. Otherwise, a ``ModelForm`` will be
        instantiated using the model associated with the
        :attr:`~django.views.generic.detail.SingleObjectMixin.queryset`, or
        with the :attr:`~django.views.generic.detail.SingleObjectMixin.model`,
        depending on which attribute is provided.

    .. method:: get_form_kwargs()

        Add the current instance (``self.object``) to the standard
        :meth:`~django.views.generic.edit.FormMixin.get_form_kwargs`.

    .. method:: get_success_url()

        Determine the URL to redirect to when the form is successfully
        validated. Returns
        :attr:`django.views.generic.edit.ModelFormMixin.success_url` if it is
        provided; otherwise, attempts to use the ``get_absolute_url()`` of the
        object.

    .. method:: form_valid(form)

        Saves the form instance, sets the current object for the view, and
        redirects to
        :meth:`~django.views.generic.edit.FormMixin.get_success_url`.

    .. method:: form_invalid(form)

        Renders a response, providing the invalid form as context.


``ProcessFormView``
===================

.. class:: django.views.generic.edit.ProcessFormView

    A mixin that provides basic HTTP GET and POST workflow.

    .. note::

        This is named 'ProcessFormView' and inherits directly from
        :class:`django.views.generic.base.View`, but breaks if used
        independently, so it is more of a mixin.

    **Extends**

    * :class:`django.views.generic.base.View`

    **Methods and Attributes**

    .. method:: get(request, *args, **kwargs)

        Renders a response using a context created with
        :meth:`~django.views.generic.edit.FormMixin.get_context_data`.

    .. method:: post(request, *args, **kwargs)

        Constructs a form, checks the form for validity, and handles it
        accordingly.

    .. method:: put(*args, **kwargs)

        The ``PUT`` action is also handled and passes all parameters through to
        :meth:`post`.


``DeletionMixin``
=================

.. class:: django.views.generic.edit.DeletionMixin

    Enables handling of the ``DELETE`` http action.

    **Methods and Attributes**

    .. attribute:: success_url

        The url to redirect to when the nominated object has been
        successfully deleted.

        ``success_url`` may contain dictionary string formatting, which will be
        interpolated against the object's field attributes. For example, you
        could use ``success_url="/parent/{parent_id}/"`` to redirect to a URL
        composed out of the ``parent_id`` field on a model.

    .. method:: delete(request, *args, **kwargs)

        Retrieves the target object and calls its ``delete()`` method, then
        redirects to the success URL.

    .. method:: get_success_url()

        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.