Formset Views

For all of these views we’ve tried to mimic the API of Django’s existing class-based views as closely as possible, so they should feel natural to anyone who’s already familiar with Django’s views.

FormSetView

This is the formset equivalent of Django’s FormView. Use it when you want to display a single (non-model) formset on a page.

A simple formset:

from extra_views import FormSetView
from my_app.forms import AddressForm


class AddressFormSetView(FormSetView):
    template_name = 'address_formset.html'
    form_class = AddressForm
    success_url = 'success/'

    def get_initial(self):
        # return whatever you'd normally use as the initial data for your formset.
      return data

    def formset_valid(self, formset):
        # do whatever you'd like to do with the valid formset
        return super(AddressFormSetView, self).formset_valid(formset)

and in address_formset.html:

<form method="post">
  ...
  {{ formset }}
  ...
  <input type="submit" value="Submit" />
</form>

This view will render the template address_formset.html with a context variable formset representing the AddressFormSet. Once POSTed and successfully validated, formset_valid will be called (which is where your handling logic goes), then the view will redirect to success_url.

Formset constructor and factory kwargs

FormSetView exposes all the parameters you’d normally be able to pass to the django.forms.BaseFormSet constructor and django.forms.formset_factory(). This can be done by setting the respective attribute on the class, or formset_kwargs and factory_kwargs at the class level.

Below is an exhaustive list of all formset-related attributes which can be set at the class level for FormSetView:

...
from my_app.forms import AddressForm, BaseAddressFormSet


class AddressFormSetView(FormSetView):
    template_name = 'address_formset.html'
    form_class = AddressForm
    formset_class = BaseAddressFormSet
    initial = [{'type': 'home'}, {'type': 'work'}]
    prefix = 'address-form'
    success_url = 'success/'
    factory_kwargs = {'extra': 2, 'max_num': None,
                      'can_order': False, 'can_delete': False}
    formset_kwargs = {'auto_id': 'my_id_%s'}

In the above example, BaseAddressFormSet would be a subclass of django.forms.BaseFormSet.

ModelFormSetView

ModelFormSetView makes use of django.forms.modelformset_factory(), using the declarative syntax used in FormSetView as well as Django’s own class-based views. So as you’d expect, the simplest usage is as follows:

from extra_views import ModelFormSetView
from my_app.models import Item


class ItemFormSetView(ModelFormSetView):
    model = Item
    fields = ['name', 'sku', 'price']
    template_name = 'item_formset.html'

Rather than setting fields, exclude can be defined at the class level as a list of fields to be excluded.

It is not necessary to define fields or exclude if a form_class is defined at the class level:

...
from django.forms import ModelForm


class ItemForm(ModelForm):
    # Custom form definition goes here
    fields = ['name', 'sku', 'price']


class ItemFormSetView(ModelFormSetView):
    model = Item
    form_class = ItemForm
    template_name = 'item_formset.html'

Like FormSetView, the formset variable is made available in the template context. By default this will populate the formset with all the instances of Item in the database. You can control this by overriding get_queryset on the class, which could filter on a URL kwarg (self.kwargs), for example:

class ItemFormSetView(ModelFormSetView):
    model = Item
    template_name = 'item_formset.html'

    def get_queryset(self):
        sku = self.kwargs['sku']
        return super(ItemFormSetView, self).get_queryset().filter(sku=sku)

InlineFormSetView

When you want to edit instances of a particular model related to a parent model (using a ForeignKey), you’ll want to use InlineFormSetView. An example use case would be editing addresses associated with a particular contact.

from extra_views import InlineFormSetView


class EditContactAddresses(InlineFormSetView):
    model = Contact
    inline_model = Address

    ...

Aside from the use of model and inline_model, InlineFormSetView works more-or-less in the same way as ModelFormSetView, instead calling django.forms.inlineformset_factory().

CreateWithInlinesView and UpdateWithInlinesView

These are the most powerful views in the library, they are effectively replacements for Django’s own CreateView and UpdateView. The key difference is that they let you include any number of inline formsets (as well as the parent model’s form). This provides functionality much like the Django Admin change forms. The API should be fairly familiar as well. The list of the inlines will be passed to the template as context variable inlines.

Here is a simple example that demonstrates the use of each view with normal inline relationships:

from extra_views import CreateWithInlinesView, UpdateWithInlinesView, InlineFormSetFactory


class ItemInline(InlineFormSetFactory):
    model = Item
    fields = ['sku', 'price', 'name']


class ContactInline(InlineFormSetFactory):
    model = Contact
    fields = ['name', 'email']


class CreateOrderView(CreateWithInlinesView):
    model = Order
    inlines = [ItemInline, ContactInline]
    fields = ['customer', 'name']
    template_name = 'order_and_items.html'

    def get_success_url(self):
        return self.object.get_absolute_url()


class UpdateOrderView(UpdateWithInlinesView):
    model = Order
    inlines = [ItemInline, ContactInline]
    fields = ['customer', 'name']
    template_name = 'order_and_items.html'

    def get_success_url(self):
        return self.object.get_absolute_url()

and in the html template:

<form method="post">
  ...
  {{ form }}

  {% for formset in inlines %}
    {{ formset }}
  {% endfor %}
  ...
  <input type="submit" value="Submit" />
</form>

InlineFormSetFactory

This class represents all the configuration necessary to generate an inline formset from django.inlineformset_factory(). Each class within in CreateWithInlines.inlines and UpdateWithInlines.inlines should be a subclass of InlineFormSetFactory. All the same methods and attributes as InlineFormSetView are available, with the exception of any view-related attributes and methods, such as success_url or formset_valid():

from my_app.forms import ItemForm, BaseItemFormSet
from extra_views import InlineFormSetFactory


class ItemInline(InlineFormSetFactory):
    model = Item
    form_class = ItemForm
    formset_class = BaseItemFormSet
    initial = [{'name': 'example1'}, {'name', 'example2'}]
    prefix = 'item-form'
    factory_kwargs = {'extra': 2, 'max_num': None,
                      'can_order': False, 'can_delete': False}
    formset_kwargs = {'auto_id': 'my_id_%s'}

IMPORTANT: Note that when using InlineFormSetFactory, model should be the inline model and not the parent model.

GenericInlineFormSetView

In the specific case when you would usually use Django’s django.contrib.contenttypes.forms.generic_inlineformset_factory(), you should use GenericInlineFormSetView. The kwargs ct_field and fk_field should be set in factory_kwargs if they need to be changed from their default values:

from extra_views.generic import GenericInlineFormSetView


class EditOrderTags(GenericInlineFormSetView):
    model = Order
    inline_model = Tag
    factory_kwargs = {'ct_field': 'content_type', 'fk_field': 'object_id',
                      'max_num': 1}
    formset_kwargs = {'save_as_new': True}

    ...

There is a GenericInlineFormSetFactory which is analogous to InlineFormSetFactory for use with generic inline formsets.

GenericInlineFormSetFactory can be used in CreateWithInlines.inlines and UpdateWithInlines.inlines in the obvious way.