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:
.. code-block:: python
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``:
.. code-block:: html
This view will render the template ``address_formset.html`` with a context variable
:code:`formset` representing the :code:`AddressFormSet`. Once POSTed and successfully
validated, :code:`formset_valid` will be called (which is where your handling logic
goes), then the view will redirect to :code:`success_url`.
Formset constructor and factory kwargs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FormSetView exposes all the parameters you'd normally be able to pass to the
:code:`django.forms.BaseFormSet` constructor and
:code:`django.forms.formset_factory()`. This can be done by setting the
respective attribute on the class, or :code:`factory_kwargs`, :code:`formset_kwargs` and
:code:`form_kwargs` at the class level.
Below is an exhaustive list of all formset-related attributes which can be set
at the class level for :code:`FormSetView`:
.. code-block:: python
...
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'}
form_kwargs = {'label_suffix': ':'}
In the above example, BaseAddressFormSet would be a subclass of
:code:`django.forms.BaseFormSet`.
ModelFormSetView
----------------
ModelFormSetView makes use of :code:`django.forms.modelformset_factory()`, using the
declarative syntax used in :code:`FormSetView` as well as Django's own class-based
views. So as you'd expect, the simplest usage is as follows:
.. code-block:: python
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 :code:`fields`, :code:`exclude` can be defined
at the class level as a list of fields to be excluded.
It is not necessary to define :code:`fields` or :code:`exclude` if a
:code:`form_class` is defined at the class level:
.. code-block:: python
...
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 :code:`FormSetView`, the :code:`formset` variable is made available in the template
context. By default this will populate the formset with all the instances of
:code:`Item` in the database. You can control this by overriding :code:`get_queryset` on
the class, which could filter on a URL kwarg (:code:`self.kwargs`), for example:
.. code-block:: python
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.
.. code-block:: python
from extra_views import InlineFormSetView
class EditContactAddresses(InlineFormSetView):
model = Contact
inline_model = Address
...
Aside from the use of :code:`model` and :code:`inline_model`,
:code:`InlineFormSetView` works more-or-less in the same way as
:code:`ModelFormSetView`, instead calling :code:`django.forms.inlineformset_factory()`.
CreateWithInlinesView and UpdateWithInlinesView
-----------------------------------------------
These are the most powerful views in the library, they are effectively
replacements for Django's own :code:`CreateView` and :code:`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:
.. code-block:: python
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:
.. code-block:: html
InlineFormSetFactory
^^^^^^^^^^^^^^^^^^^^
This class represents all the configuration necessary to generate an inline formset
from :code:`django.inlineformset_factory()`. Each class within in
:code:`CreateWithInlines.inlines` and :code:`UpdateWithInlines.inlines`
should be a subclass of :code:`InlineFormSetFactory`. All the
same methods and attributes as :code:`InlineFormSetView` are available, with the
exception of any view-related attributes and methods, such as :code:`success_url`
or :code:`formset_valid()`:
.. code-block:: python
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 :code:`InlineFormSetFactory`, :code:`model` should be the
*inline* model and **not** the parent model.
GenericInlineFormSetView
------------------------
In the specific case when you would usually use Django's
:code:`django.contrib.contenttypes.forms.generic_inlineformset_factory()`, you
should use :code:`GenericInlineFormSetView`. The kwargs :code:`ct_field` and
:code:`fk_field` should be set in :code:`factory_kwargs` if they need to be
changed from their default values:
.. code-block:: python
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 :code:`GenericInlineFormSetFactory` which is analogous to
:code:`InlineFormSetFactory` for use with generic inline formsets.
:code:`GenericInlineFormSetFactory` can be used in
:code:`CreateWithInlines.inlines` and :code:`UpdateWithInlines.inlines` in the
obvious way.