==============

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.