Formsets and Editable Tables¶
formwork_modelformset_factory and formwork_inlineformset_factory build model
formsets on top of Django's. They validate uniqueness with one query per check
instead of one per row, and they render as an editable table. Every name on this
page is importable from django_formwork.
Factories¶
from django_formwork import formwork_inlineformset_factory, formwork_modelformset_factory
TaskFormSet = formwork_modelformset_factory(Task, fields=["title", "status"], extra=0)
LineFormSet = formwork_inlineformset_factory(Order, OrderLine, fields=["product", "quantity"])
Both take the arguments of Django's modelformset_factory and
inlineformset_factory. Three defaults differ:
| Argument | Default |
|---|---|
form |
FormworkModelForm |
formset |
FormworkBaseModelFormSet / FormworkBaseInlineFormSet |
renderer |
FormworkRenderer() |
To add formset behavior, subclass the base class and pass it as formset:
from django.core.exceptions import ValidationError
from django_formwork import FormworkBaseModelFormSet, formwork_modelformset_factory
class TaskBaseFormSet(FormworkBaseModelFormSet):
def clean(self):
super().clean()
if sum(form.cleaned_data.get("hours", 0) for form in self.forms) > 40:
raise ValidationError("More than 40 hours in one week.")
TaskFormSet = formwork_modelformset_factory(Task, formset=TaskBaseFormSet, fields=["title", "hours"])
Uniqueness validation¶
Django validates uniqueness one form at a time: each row runs one query per unique
check, so 50 rows with 3 checks make 150 queries. A Formwork formset takes these
checks from its forms and runs one query per distinct check for all rows. The
errors, their messages and their placement (on the field or in __all__) are the
same as Django's. Only the query count changes.
One query covers all rows for:
unique,unique_togetherandunique_for_date/unique_for_month/unique_for_year.- A
UniqueConstrainton fields only, with nocondition, the defaultviolation_error_messageandnulls_distinctnot set toFalse. - Every
CheckConstraint.
These still run per row, through Django's own constraint.validate():
- A
UniqueConstraintwith acondition, expressions, a custom message ornulls_distinct=False. - A
UniqueConstraintover aGeneratedFieldor a field with adb_collation.
The database checks run in the formset's full_clean(), before validate_max and
clean(), as Django runs them in each form's full_clean(). A clean() override
without super() skips only the check between the submitted rows, as in Django.
Rows marked for deletion are checked too, and the formset drops their errors, as
Django does.
A plain ModelForm passed as form keeps Django's per-form checks.
Known differences¶
Two cases compare values in Python where Django compares them in SQL:
- A
uniqueorunique_togetherfield with a case-insensitive collation (MySQL*_ci,db_collation="NOCASE", PostgreSQLcitext). The batched check can miss a duplicate that differs only in case. The database then rejects the save with anIntegrityError. unique_for_date(or month, year) against aDateTimeFieldwith aTIME_ZONEother than UTC. The batched check keys rows by the stored UTC date, Django by the local date, so a row near midnight can miss its duplicate.
Editable tables¶
formset.as_rows(save_url) renders the formset as one <table>, with a header row
from the formset's empty_form. form.as_row(save_url) renders one FormworkForm
or FormworkModelForm as a <tbody>, with one cell per visible field and the
hidden inputs in the first cell.
With a save_url, each row posts its own fields to that URL 400 ms after a change
and morphs the response in place. Without one, the rows are static.
A disabled field shows as text: the instance's get_<field>_display(), else the
instance's value (a comma-separated list for a many-to-many field), else the labels
of the chosen values.
as_rows() does not render the management form. Add
{{ formset.management_form }} if the table is also submitted as a whole formset.
Templates¶
| Template | Renders | Set per class on |
|---|---|---|
formwork/tables/table.html |
as_rows(): the <table> |
the formset, template_name_table |
formwork/tables/row.html |
as_row(): one <tbody> |
the form, template_name_row |
To override one for the whole project, put a template at the same path in a
directory of your TEMPLATES setting.
Saving a row¶
FormworkRowSaveMixin is the view behind save_url. It saves the posted row and
answers with the row rendered again.
# views.py
from django.shortcuts import render
from django.urls import reverse
from django.views import View
from django_formwork import FormworkRowSaveMixin
class TaskRowSave(FormworkRowSaveMixin, View):
form_class = TaskRowForm
http_method_names = ["post"]
def get_queryset(self, request):
return Task.objects.filter(owner=request.user)
def task_list(request):
formset = TaskFormSet(queryset=Task.objects.filter(owner=request.user))
return render(request, "tasks/list.html", {"table": formset.as_rows(reverse("task_row_save"))})
# urls.py
from django.contrib.auth.decorators import login_required
urlpatterns = [
path("tasks/row/", login_required(TaskRowSave.as_view()), name="task_row_save"),
]
On each post the view:
- Reads the form prefix and the row's primary key from the post.
- Looks the row up in
get_queryset(request). A missing or malformed key, or a row outside the queryset, gets a 404. - Binds
form_class(request.POST, request.FILES, instance=row, prefix=prefix). - Saves the form if it is valid, and answers with the row, errors included.
queryset or get_queryset() is required. It holds the rows a user can change, so
a user cannot post another user's primary key and edit that row. Without either,
the view raises ImproperlyConfigured. Set queryset = Task.objects.all() only if
every user can change every row. The mixin does no other access check: protect the
view as you protect any other.
| Method | Default |
|---|---|
get_queryset(request) |
queryset.all() |
get_form_kwargs() |
{}, extra arguments for form_class |
get_prefix(request) |
the posted _formwork_prefix |
get_save_url(request) |
request.path |
render_row(request, form) |
form.as_row(self.get_save_url(request)) |
The form validates every field of form_class against the post: a required field
the row does not post fails, and an optional one can be saved empty. Give the row
form only the columns the table shows.
Hand-authored rows¶
To lay a row out yourself, render it from your own template and override
render_row() to render the same template. Put {{ form.row_hidden_inputs }} in
the row: it carries the prefix and the primary key the view reads. The
full example
renders its task list this way.
FORMWORK_FORCE_ASYNC¶
Django's formsets have no async API: they validate and save their forms through the
sync methods. The forms that a Formwork formset builds are therefore exempt from
FORMWORK_FORCE_ASYNC. In an async view, run the formset's methods in a worker
thread:
from asgiref.sync import sync_to_async
if await sync_to_async(formset.is_valid)():
await sync_to_async(formset.save)()
Because these forms validate through the sync path, an async clean_<field>() or
clean() on them is not awaited. Keep those methods sync on a formset's form.
A Django formset (modelformset_factory) with a FormworkModelForm gets no
exemption: with the setting on, its is_valid() raises RuntimeError. Build it
with formwork_modelformset_factory instead.