Architecture¶
Design constraints¶
Django forms render at three levels:
- The form (
{{ form }}) renders all fields with labels, errors and help text. - The field (
{{ field.as_field_group }}) renders one field with its label, errors and help text. - The widget (
{{ field }}) renders the bare<input>,<select>or<textarea>.
Django admin renders only at the widget level, so formwork follows five constraints:
- Overriding form or field level rendering is admin-safe.
- Formwork never overrides a built-in widget template: it would reach admin and third-party forms. Built-ins are styled by CSS only; formwork's own widgets are opt-in.
- CSS is independent: admin and frontend load separate stylesheets.
- CSS styles all form elements globally: standalone inputs get
DaisyUI styling without needing
{{ form }}. - Most formwork rules sit in
@layer components, so a Tailwind utility class or unlayered project CSS overrides them.
Rendering¶
FormworkRenderer is a TemplatesSetting renderer. It renders {{ form }}
with formwork/forms/div.html and each field group with
formwork/forms/field.html, and it loads every template through the project's
TEMPLATES. A full render and an htmx swap of the search results therefore
resolve the same template, and a project overrides any formwork template from
its own template directories. Formwork uses its own template paths: shadowing
django/forms/div.html from inside an app would change every form in every
project that installs formwork.
Widget design rules¶
These rules keep each widget in one place and each fix in one file. Follow them for a new widget and for a change to an existing one.
| # | Rule | Reason |
|---|---|---|
| R1 | A widget has one class, one template, and at most one Alpine component. Add no fourth place. | Python builds the context, the template holds the markup, and the JS module holds the behaviour. |
| R2 | Check field.widget_type in no template except field.html. Add a branch there only when the widget cannot do the work. |
Django takes the field wrapper from Field.template_name or the renderer, never from the widget. So only the wrapper can branch (single checkbox, toggle). |
| R3 | A widget template has no <script>, not even a small one. Register the behaviour with Alpine.data(name, …) in an alpine:init listener, import the module in formwork.js, and list it in the widget's Media. The template only names it: x-data="formworkSelect". |
A template that needs document.currentScript, a window.load listener, or a global from another library has its behaviour in the wrong file. |
| R4 | Follow Django's hierarchy. Subclass for the data contract, share the template, and override only the block that differs. SelectMultiple is a thin subclass over the shared SearchableSelectMixin. A domain variant, such as a project's own country select, subclasses Select and changes only the choices. When only the look of an option differs, return a ChoiceLabel and add no widget. |
Django's own SelectMultiple is three lines over Select. |
| R5 | Declare a widget by class, never with a multiple=True kwarg. |
Meta.widgets and ModelMultipleChoiceField.widget name a class, so the class is the contract. |
| R6 | Factor out shared behaviour and markup. Do not copy it. A variant extends the base template and overrides one block. The shared dropdown mechanics live once in dropdownBase() in widgets/_helpers.js. |
Each fix then goes in one place. |
| R7 | An inline Alpine attribute is one call: onToggle(), onNav($event, 1), matches($el). Move the value into the module if it contains ;, const, new …, or a JS literal built from {{ }}. Put a repeated attribute block in one x-bind object on the shared base. Pass values through data-* attributes. |
'{{ v\|escapejs }}' inside an expression parses only if escapejs escaped every quote. Bad: x-show="!search \|\| '{{ option.label\|escapejs }}'.toLowerCase()…". Good: x-show="matches($el)" data-label="{{ option.label }}". |
| R8 | Use native HTML first, Alpine second, and a library last: <details>/<summary> for a dropdown, <input type=search> for a filter, <button> for an action. |
The browser gives keyboard support and accessibility. |
| R9 | Put the id on the focusable control. A hidden input that has the field id is a bug. |
<label for> must point to an element that the user can click. |
| R10 | Keep server concerns in Python. A template builds no URL and no query parameter. Option markup goes through the #option_list partial. |
htmx swaps and full renders then use one code path. |
| R11 | The look of a widget is in its template, not in the Python class. A caller's attrs={"class": …} is only for a one-off variant. Add a CSS component class only after the same variant appears on a third page, and restate every hover and focus state in it. |
DaisyUI state rules win over a plain component class. |
| R12 | Name a widget after the primitive. Use Django's name for a drop-in replacement. Add a prefix only when two widgets coexist for one primitive. Do not name the library, the look, or a behaviour that is automatic. | See Widget names. |
Widget names¶
| Name | Reason |
|---|---|
Select, SelectMultiple |
Django's names. Search appears past search_threshold, so it is not part of the name. |
TextInput, PasswordInput, DateInput |
Drop-in replacements, so no prefix. |
StepperNumberInput, SuffixNumberInput |
Two number inputs coexist, so both have a prefix. |
CardRadioSelect, CardCheckboxSelectMultiple |
The form is a card. "Big" would be subjective. |
ToggleInput |
The semantic. "Pill" would name the skin. |
SearchInput, ComboBox |
input type=search and the ARIA term. |
CountrySelect |
A domain choice set, not a rendering variant. Formwork ships no domain widgets; a project builds one from Select. |
~~CalendarDateInput~~ |
Rejected: names the calendar library. |
~~ComponentCheckboxSelectMultiple~~ |
Rejected: "Component" says nothing. |
The names shadow django.forms on purpose. Widget modules write
forms.Select, and callers write from django_formwork import widgets and
widgets.Select.
Adding a widget¶
- Subclass the closest Django widget and set
template_name. - Compute the context in
get_context. Keep the classes and the copy in the template. - If the widget needs behaviour, add one
Alpine.datamodule. - For a variant, extend the base template and override one block.
- For server search, build on
SearchableSelectMixin, so the form registers the search andFormworkSearchViewserves it. Write no URL and no view.