Forms¶
FormworkForm and FormworkModelForm bundle the DaisyUI renderer with
behaviours plain Django forms do not have: search registration, a choice of
error placement, mandatory fields, dirty-only validation, and async validation
and saving. section_forms() builds the forms of a page that saves one row in
several sections.
With FORM_RENDERER = "django_formwork.FormworkRenderer" set, every form in
the project renders styled, including plain forms.Form. Reach for the base
classes when you want the behaviours below, or formwork styling on individual
forms without the global renderer.
Everything documented here is importable from the package root:
Base classes¶
| Class | Use with |
|---|---|
FormworkForm |
any data |
FormworkModelForm |
a model; subscript it for typed instance and save(): FormworkModelForm[Book] |
Both render with FormworkRenderer and use FormworkBoundField. It adds
aria-required to a mandatory field, and
aria-labelledby to a dropdown trigger that <label for> cannot target.
For icons, descriptions or a trigger class on model choices, return a
ChoiceLabel from label_from_instance:
from django import forms
from django_formwork import ChoiceLabel
class MemberChoiceField(forms.ModelChoiceField):
def label_from_instance(self, obj):
return ChoiceLabel(obj.name, description=obj.email)
Search registration¶
A field whose widget (Select, SelectMultiple, ComboBox or
ComboBoxMultiple) has a search_queryset registers its search when Python
creates the form class.
Formwork imports the forms module of every installed app at startup, so the
search exists in every worker before the first request. A single
include("django_formwork.urls") serves all of them. Registration raises
ImproperlyConfigured for a widget without search_decorator: pass an auth
decorator such as login_required, or None for a public endpoint. A bad Meta
option fails the same way, when Python creates the class: an error_display
other than "auto", "inline" or "tooltip", a mandatory that is a string or
names a field the form lacks, and validate_dirty_only on a model without
get_dirty_fields(). See
Views for the endpoint and the
quickstart for a worked
example.
Required and mandatory fields¶
A required field shows a red * after its label, and the widget carries
aria-required="true". A disabled field shows no asterisk. Formwork marks no
optional field.
Meta.mandatory names fields that a save accepts empty but a later step needs,
for example a draft that the user publishes later. They get the asterisk and
aria-required too, and they still validate as optional:
class ListingForm(FormworkModelForm):
class Meta:
model = Listing
fields = ["title", "price", "description"]
mandatory = ["price", "description"]
Meta.mandatory seeds the set self.mandatory. Add a name that depends on the
data after super().__init__():
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
if self.instance.category == "vehicle":
self.mandatory.add("mileage")
Help text¶
Formwork escapes help text. Django's own templates render it as HTML, so a
plain string with tags that showed as markup there shows the tags as text here.
Build markup with format_html() or mark_safe():
from django.utils.html import format_html
email = forms.EmailField(
help_text=format_html('See the <a href="{}">privacy policy</a>.', "/privacy/"),
)
error_display¶
error_display picks where field errors render:
| Value | Placement |
|---|---|
"auto" (default) |
inline when the field has help text, in a tooltip when it has none |
"inline" |
inline under every field |
"tooltip" |
in a DaisyUI tooltip on every field |
Set it on the Meta class or per instantiation:
class ContactForm(FormworkForm):
class Meta:
error_display = "tooltip"
# or
form = ContactForm(request.POST, error_display="tooltip")
An inline error uses the pattern of the help text: a small icon below the
widget, in error color, with the message truncated to one line and a [more]
toggle when it overflows. [more] reveals the full error and the help text
together; [less] collapses both. While collapsed, the help text is
present for screen readers but visually hidden. A tooltip error is more
compact, but a user can miss it in a dense layout such as a table row.
Use "inline" for inline table-row editing, dense multi-column layouts, or
forms where the help text must stay reachable while an error shows, and
"tooltip" for fields with room around them. A plain forms.Form rendered by
FormworkRenderer uses "auto".
validate_dirty_only¶
On an edit form, validators added after a record was saved can reject stored
values the user never touched. validate_dirty_only skips validation for
fields the submission did not change. Enable it on the Meta class or per
instantiation:
class TicketEditForm(FormworkModelForm):
class Meta:
model = Ticket
fields = ["title", "priority", "description"]
validate_dirty_only = True
# or
form = TicketEditForm(request.POST, instance=ticket, validate_dirty_only=True)
For a field the user did not change:
- field validators and the
clean_<field>method do not run - model field validation, unique checks, and constraint checks exclude it
- the stored value is carried into
cleaned_dataand left untouched on the instance, so an unchanged relation is never re-assigned
A field that the post leaves out counts as unchanged, so a form that posts
only its changed fields (a section form with data-send-changed) validates
only those. Changed fields validate as usual, and the form-wide clean()
method always runs. Form.changed_data decides whether a field counts as
changed: it compares the posted value against the initial data of the form,
and with instance= bound, the initial data is what the database holds. The
model-level exclusions apply only to existing instances. On create, the
full_clean() of the instance covers every field.
On a FormworkModelForm the flag requires the model to provide
get_dirty_fields(). Inherit FormworkModel, or mix
filthyfields.DirtyFieldsMixin into the model directly; the form raises
ImproperlyConfigured otherwise. Plain FormworkForm supports the flag too,
where it covers the field-level skips.
The cookbook walks through a legacy-data example.
Async validation and saving¶
ais_valid(), afull_clean(), and asave() are async counterparts to
Django's sync methods. clean_<field>() and clean() can be sync or async in
the same form. Formwork detects the async ones and awaits them, so validation
can use the async ORM without sync_to_async wrappers.
from django import forms
from django.contrib.auth.models import User
from django.core.exceptions import ValidationError
from django_formwork import FormworkForm
class SignupForm(FormworkForm):
email = forms.EmailField()
async def clean_email(self):
email = self.cleaned_data["email"]
if await User.objects.filter(email__iexact=email).aexists():
raise ValidationError("Already registered.")
return email
async def signup(request):
if request.method == "POST":
form = SignupForm(request.POST)
if await form.ais_valid():
...
asave(commit=True) mirrors ModelForm.save(): it awaits the instance's
asave() and then saves many-to-many relations. With commit=False it
returns the unsaved instance and exposes asave_m2m as an async callable;
call await form.asave_m2m() after saving the instance. Calling the sync
save_m2m hook on a form saved with asave(commit=False) raises
RuntimeError that points to asave_m2m().
Set FORMWORK_FORCE_ASYNC = True in settings to make the sync entry points
(is_valid(), full_clean(), save()) raise RuntimeError. Use it to keep
accidental sync calls out of an async codebase.
Without the setting, a form with an async clean_<field>() or clean() that
validates through the sync is_valid() stores the un-awaited coroutine in
cleaned_data and skips the check. Enable FORMWORK_FORCE_ASYNC in a project
that defines async validators and touches forms from sync code, including a
template that reads form.errors. The sync call then raises RuntimeError.
Formwork's model formsets validate their forms through the sync path, so their
forms are exempt from the setting; see Formsets.
FormworkRowSaveMixin calls the sync is_valid(), so a row save fails while the
setting is on.
Section forms¶
A section form saves its own fields of one row, without a submit button: it posts on every change and morphs itself back from the response. Several section forms on one page share a request queue, so their saves run in order.
section_forms(request, sections, **kwargs) builds every section's form and
binds only the one that the POST names. The keyword arguments go to each form,
for example instance=. A POST that names no known section raises
BadRequest.
from django_formwork import section_forms
def edit_product(request, pk):
product = get_object_or_404(Product, pk=pk)
sections = section_forms(
request,
{"general": ProductGeneralForm, "extras": ProductExtrasForm},
instance=product,
)
for form in sections.values():
if form.is_bound and form.is_valid():
form.save()
return render(request, "product_edit.html", {"sections": sections})
{% load formwork %}
<div data-section-forms>
<form id="general_form" data-section-form novalidate
hx-post="{{ request.path }}" hx-trigger="change delay:300ms"
hx-select="#general_form" hx-swap="outerMorph"
hx-sync="closest [data-section-forms]:queue all">
{% csrf_token %}{% formwork_section "general" %}
{{ sections.general }}
</form>
<form id="extras_form" data-section-form data-send-changed novalidate
hx-post="{{ request.path }}" hx-trigger="change delay:300ms"
hx-select="#extras_form" hx-swap="outerMorph"
hx-sync="closest [data-section-forms]:queue all">
{% csrf_token %}{% formwork_section "extras" %}
{{ sections.extras }}
</form>
</div>
Load {% formwork_sections_js %} after htmx. The formwork bundle leaves it
out, and it does not need Alpine.
{% formwork_section "name" %}writes the hidden_formwork_sectioninput that names the section.- Every section form needs
hx-sync="closest [data-section-forms]:queue all". A dropped or replaced save leaves its change unsent, and a request that waits for that save then never runs. - A response to a save that is older than the latest change leaves the form alone; the queued request after it carries that change.
- A request that replaces section forms (a tab switch, for example) waits until their saves are answered. Leaving the page during a save asks for confirmation.
data-send-changedon a form posts only the fields that differ from the last valid render, pluscsrfmiddlewaretokenand_formwork_section. With a value,data-send-changed="<prefix>"also posts every field whose name starts with<prefix>, changed or not. Pair it withvalidate_dirty_only, so the fields the post leaves out keep their stored values.data-section-indicator="<selector>"on a field wrapper shows that indicator while a save the field started runs.
FormworkModel¶
FormworkModel is an abstract model base that mixes in
filthyfields.DirtyFieldsMixin, providing the get_dirty_fields() that
validate_dirty_only needs, and adds one helper for clean() rules:
class Ticket(FormworkModel):
status = models.CharField(max_length=10)
closed_at = models.DateTimeField(null=True, blank=True)
def clean(self):
if self.fields_dirty("status") and self.status == "closed" and not self.closed_at:
raise ValidationError("Closing a ticket requires closed_at.")
fields_dirty(*names) is True if any of the named fields changed since the
instance was loaded from the database. New instances always return True, so
cross-field rules fire fully on create.