django-forms

name	django-forms
description	Django form handling patterns including ModelForm, validation, clean methods, and HTMX form submission. Use when building forms, implementing validation, or handling form submission. Use when this capability is needed.
metadata	{"author":"AngelDann"}

Django Forms

Philosophy

• Prefer ModelForm for model-backed forms
• Keep validation logic in forms, not views
• Always handle and display form errors
• Use commit=False when you need to modify the instance before saving

Validation

Field-level (clean_<field>):

• Validate and transform a single field
• Return the cleaned value or raise ValidationError
• Use for: format checks, uniqueness, normalization

Cross-field (clean):

• Call super().clean() first
• Access multiple fields via cleaned_data
• Use self.add_error(field, message) for field-specific errors
• Use for: password confirmation, conditional requirements

View Integration

• Check request.method explicitly
• Instantiate form with request.POST for POST, empty for GET
• Use form.save(commit=False) to set additional fields (e.g., author)
• Return redirect on success, re-render with form on error

HTMX handling:

• Check request.headers.get("HX-Request") for HTMX requests
• Return partial template on success/error for HTMX
• Use HX-Trigger header to notify other components

Templates

• Display form.non_field_errors for cross-field errors
• Display field.errors for each field
• Use partial templates (_form.html) for HTMX responses
• Include loading indicator with hx-indicator

Widgets

• Override in Meta.widgets dict
• Set HTML attributes via attrs parameter
• Common: Textarea(attrs={"rows": 5}), DateTimeInput(attrs={"type": "datetime-local"})

Formsets

• Use inlineformset_factory for related model collections
• Validate both form and formset: form.is_valid() and formset.is_valid()
• Pass instance for editing existing parent objects

Pitfalls

• Validating in views instead of forms
• Silently redirecting without checking is_valid()
• Forgetting commit=False when setting related fields
• Not displaying form errors to users

Source

Adapted from claude-code-django (.claude/skills/django-forms).

---

Source: AngelDann/app-comisions-dist — distributed by TomeVault.