Server-side Views¶
Formwork has two views: FormworkSearchView serves the server-side search of
every dropdown, and FormworkValidateView is the base class for a textarea
validation endpoint. Both are importable from django_formwork (or from
django_formwork.views).
Server-side search¶
Select, SelectMultiple, ComboBox and ComboBoxMultiple search on the
server when the widget gets a search_queryset. You configure the search on
the widget; you write no URL and no view.
Setup¶
# urls.py
from django.urls import include, path
urlpatterns = [
path("__formwork__/", include("django_formwork.urls")),
]
This mounts one URL, __formwork__/search/<key>/ (name formwork:search),
which FormworkSearchView serves for every registered search.
Configure a widget¶
# forms.py
from django import forms
from django.contrib.auth.decorators import login_required
from django_formwork import FormworkForm, widgets
from .models import City
def cities(request):
return City.objects.filter(active=True).select_related("country")
class CityForm(FormworkForm):
city = forms.ModelChoiceField(
queryset=City.objects.filter(active=True),
widget=widgets.Select(
search_queryset=cities,
search_fields=["name", "country__name"],
search_decorator=login_required,
),
)
| Parameter | Description |
|---|---|
search_queryset |
callable(request, **params) that returns the rows to search. The endpoint calls it for each request, so it can scope the rows to the user. |
search_fields |
Field paths that the query matches with __icontains (or ranks, with search_ranked). Without them the endpoint does not filter: search_queryset reads request.GET["q"] itself and returns its rows best first. |
search_decorator |
Required. A view decorator that wraps the endpoint, such as login_required or permission_required("app.view_city"). Pass None for a public endpoint. |
search_ranked |
Orders the rows by match quality on PostgreSQL. See Ranked search. |
search_key, search_params |
Reuse another field's search with its own params. See Search templates. |
allow_clear |
Select and SelectMultiple: the list starts with the empty choice of an optional field (empty_label of a ModelChoiceField), so the user can clear it. |
The form class registers each search when Python creates it, under a stable
key built from the module, the form class, the field name, and the place where
search_queryset and search_decorator are defined, so forms that a factory
builds over one model keep their own search. Formwork imports the
forms module of every installed app at startup, so a search declared there
exists in every worker before the first request. A form defined elsewhere
registers when its module is first imported. Registration raises
ImproperlyConfigured for a widget without search_decorator, for a
search_queryset that is not callable, for search_fields without
search_queryset, and for search_ranked without search_fields or outside
PostgreSQL.
search_queryset filters through the request it gets, never through values it
closes over. The endpoint serves one search per key, so a second form of the same
name whose search_queryset closes over other values raises
ImproperlyConfigured.
The endpoint renders each row with label_from_instance of the field, so a
ChoiceLabel adds an icon, a description or a
trigger class to the results. A ComboBox over a CharField takes its own
label_from_instance= and falls back to str().
Paging¶
The widget renders the first 20 rows itself, plus the selected rows that lie
past them. A search returns the next 20 matches at most. When more exist, the
list ends with a hint and a "Load more" button that fetches the next page. The
endpoint fetches one row past the page to tell whether more exist, so it never
runs a COUNT. The first "Load more" request excludes the selected rows that
the widget already shows past the first page.
With static choices and no search_queryset, the widget filters in the
browser. It shows the search box past search_threshold (10) options, or when
show_search=True.
Access control¶
search_decorator wraps FormworkSearchView.dispatch for that search. Every
search needs an explicit value, and a widget without one raises
ImproperlyConfigured when its form class registers:
from django.contrib.auth.decorators import login_required, permission_required
widgets.Select(search_queryset=cities, search_fields=["name"], search_decorator=login_required)
widgets.Select(
search_queryset=cities,
search_fields=["name"],
search_decorator=permission_required("geo.view_city"),
)
widgets.Select(search_queryset=cities, search_fields=["name"], search_decorator=None) # public
A request for an unknown key from an anonymous user redirects to
settings.LOGIN_URL when django.contrib.auth is installed, so the response
does not tell a missing key from a protected one. Otherwise an unknown key
returns 404. Queries longer than FormworkSearchView.MAX_QUERY_LENGTH (200)
characters are truncated.
FormworkSearchView is final: configure a search through the widget, not by
subclassing the view.
Ranked search¶
search_ranked=True orders the rows by how well they match, and matches typos
too. It needs PostgreSQL with the pg_trgm extension, and at least one
search_fields entry.
widgets.Select(
search_queryset=cities,
search_fields=["name"],
search_ranked=True,
search_decorator=login_required,
)
Rows that contain the query come first, then typo matches. Within each group, whole-word matches rank above partial ones, and the closest value comes first. A query shorter than 3 characters has too few trigrams to rank by, so it ranks exact matches first, then prefix matches, then the other rows that contain the query.
A GIN trigram index on UPPER(field::text) per search field serves every
lookup of the ranked search and of plain __icontains:
from django.contrib.postgres.indexes import GinIndex, OpClass
from django.db import models
from django.db.models import TextField
from django.db.models.functions import Cast, Upper
class City(models.Model):
name = models.CharField(max_length=100)
class Meta:
indexes = [
GinIndex(
OpClass(Upper(Cast("name", output_field=TextField())), name="gin_trgm_ops"),
name="city_name_trgm",
),
]
Create the extension in a migration with
django.contrib.postgres.operations.TrigramExtension(). Without
search_ranked, __icontains runs as LIKE '%query%'; the leading wildcard
rules out a B-tree index, so a large table needs the same trigram index.
ranked_search(queryset, fields, query) in django_formwork.search applies
the same ordering to any queryset.
Search templates¶
A form that builds fields in __init__ (one field per group, for example)
reuses one registered search with its own params. Declare a template field
whose search_queryset takes keyword-only int or str params after the
request, then pass its search_key and the params to the fields you build:
from django import forms
from django.contrib.auth.decorators import login_required
from django.contrib.auth.models import User
from django_formwork import FormworkForm, widgets
def group_members(request, *, group: int):
return User.objects.filter(groups=group)
class TeamForm(FormworkForm):
members_template = forms.ModelMultipleChoiceField(
queryset=User.objects.none(),
widget=widgets.SelectMultiple(
search_queryset=group_members,
search_fields=["email"],
search_decorator=login_required,
),
)
def __init__(self, *args, groups, **kwargs):
super().__init__(*args, **kwargs)
key = self.fields.pop("members_template").widget.search_key
for group in groups:
self.fields[f"group_{group.pk}"] = forms.ModelMultipleChoiceField(
queryset=User.objects.filter(groups=group),
widget=widgets.SelectMultiple(search_key=key, search_params={"group": group.pk}),
)
The params travel in the search URL, and the endpoint converts them to the
declared type before it calls search_queryset. The widget raises
ImproperlyConfigured when the params do not match the declared names, and a
param cannot take a name the endpoint reads itself (q, offset, exclude,
widget, allow_clear). A user can edit the params in the URL, so
search_queryset must return only rows that the requesting user is allowed to see,
whatever the params say.
FormworkValidateView¶
Base view for server-side textarea validation. It answers a POST, calls get_errors(text, request=request), and returns two fragments:
- The text as HTML, with
<mark>tags around the error spans. htmx swaps it into the highlight overlay of theValidatedTextarea. - An out-of-band (
hx-swap-oob) fragment with the error messages. htmx swaps it into the error area of the widget.
Usage¶
# views.py
import re
from django_formwork import FormworkValidateView
TYPOS = {"teh": "the", "recieve": "receive"}
class SpellCheckView(FormworkValidateView):
def get_errors(self, text: str, **kwargs) -> list[dict]:
return [
{
"message": f"Did you mean {TYPOS[word.group().lower()]!r}?",
"start": word.start(),
"end": word.end(),
}
for word in re.finditer(r"\w+", text)
if word.group().lower() in TYPOS
]
# urls.py
from django.urls import path
from .views import SpellCheckView
urlpatterns = [
path("validate/spell/", SpellCheckView.as_view(), name="spell-check"),
]
# forms.py
from django import forms
from django.urls import reverse_lazy
from django_formwork.widgets import ValidatedTextarea
class PostForm(forms.Form):
content = forms.CharField(
widget=ValidatedTextarea(validate_url=reverse_lazy("spell-check")),
)
The widget posts only when the textarea has an id; see ValidatedTextarea.
Error dict keys¶
| Key | Required | Description |
|---|---|---|
message |
Yes | Error description displayed below the textarea |
start |
No | Start character index in the text (for highlight) |
end |
No | End character index in the text (for highlight) |
When an error has both start and end, the overlay wraps the text between those indices in a <mark> tag. The view merges overlapping spans into one <mark> and drops a span that lies outside the text.
Access control¶
Like the search side's search_decorator, the view exposes a validate_decorator hook. Set it on your subclass to wrap dispatch with a standard Django auth decorator:
from django.contrib.auth.decorators import login_required
class SpellCheckView(FormworkValidateView):
validate_decorator = login_required
None (the default) leaves the endpoint public. Set a decorator on a subclass that does expensive work, such as a spell check, an LLM call or a database lookup: without one, anyone can call the endpoint, and formwork applies no rate limit.
MAX_TEXT_LENGTH¶
The view truncates the text to MAX_TEXT_LENGTH characters (default 50_000) before it calls get_errors(), as MAX_QUERY_LENGTH does on the search side. Override the class attribute to change the limit.
Security note¶
FormworkValidateView is CSRF-exempt, because it only reads the posted text and returns the highlighted output. It changes no application state.
Read-only checks only
Subclass FormworkValidateView only for a read-only check. An operation that writes to the database, sends an email or changes other state needs a regular Django view with CSRF protection.