Tutorial
Building with it
Forms and validation
Bind controls to state, validate what the reader types, upload files, and show what the server said.
This chapter is about forms in WebFluent: controls that read and write state, rules that say what each value must be, and a submit that sends the form to a server and shows what came back.
You will be able to:
- bind any control to a state, in both directions;
- validate a field with a
validateblock, without writing the error messages' markup; - know whether the whole form is valid, and submit it;
- upload a file and show its progress;
- show the errors a server sends back, and a busy state while a request runs.
WebFluent writes the accessible parts for you: a real <label> for every label, aria-describedby for hints and errors, aria-invalid, errors announced as they appear, and focus moved to the first problem.
Before you start
You should know how to declare state and an action (State and reactivity) and how to handle an event (Events). Sending a form to a server uses an api, which Data and APIs covers in full.
Bind a control to state
To keep a control and a state in step, give the control bind: and the state's name. Typing in the control writes the state, and changing the state updates the control.
This sign-up page binds one of each kind of control:
page Signup(path: "/signup", title: "Sign up", description: "Every control, bound to state.") {
state name = ""
state email = ""
state plan = "free"
state agree = false
state seats = 1
state when: Date? = null
Heading("Sign up").h1
Input(bind: name, label: "Name", placeholder: "Ada Lovelace").required
Input(bind: email, label: "Email").email.required
Select(bind: plan, label: "Plan") {
Select.Option("Free", value: "free")
Select.Option("Team", value: "team")
}
Radio(bind: plan, value: "free", label: "Free")
Radio(bind: plan, value: "team", label: "Team")
Checkbox(bind: agree, label: "I agree to the terms")
Switch(bind: agree, label: "Same thing, as a switch")
Slider(bind: seats, min: 1, max: 50, label: "Seats")
DatePicker(bind: when, label: "Start date")
Text("{name} <{email}> wants {seats} {plan} seats")
if let start = when { Text("Starting {start}") }
}
Note
Coming from React? A controlled input needs value={q} and an onChange that calls the setter. bind: q is both directions at once, and the control holds the state's type, so a Slider writes a Number, not the string e.target.value would give you. See Coming from React.
The last lines repeat what you type and pick. The Select and the two Radios share plan, so choosing in one moves the others.
For several lines of text, use a Textarea. With maxLength: it shows how many characters are left, and tells a screen reader politely (without interrupting):
Textarea(bind: note, label: "Notes", rows: 4, maxLength: 200)
What each control holds
The checker knows the type each control writes, and refuses a bind: to a state of another type (F02):
| Control | Holds |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
the option's |
|
|
|
A value comes back as the type it went in as. Select.Option("Two", value: 2) binds the number 2, not the string "2".
Every control needs an accessible name: a label:, a placeholder: (on an Input), or an aria-label:. The accessibility lints (A03, A04) warn when one has none.
Bind to a store or a list item
bind: takes anything that can be written:
- a state;
- a store's member, such as
bind: Cart.note; - a field of a loop's item.
This list lets the reader rename and tick off each todo in place:
type Todo { id: String, title: String, done: Bool = false }
page Todos(path: "/todos", title: "Todos", description: "Edit each todo in place.") {
state todos: [Todo] = [Todo(id: "1", title: "Water the plants"), Todo(id: "2", title: "Post the letter")]
Heading("Todos").h1
for todo in todos by todo.id {
Input(bind: todo.title, label: "Title")
Checkbox(bind: todo.done, label: "Done")
}
Text("{todos.filter(todo => !todo.done).length} left")
}
The count at the bottom drops as you tick items. The item is written and the list is told it changed, so everything that reads todos follows:
- In a keyed loop (
for … by), the list hears of the change as the reader types. - In a loop with no
by, which redraws every item when its list changes, the list hears of it when the reader leaves the field, so the row is not redrawn under the cursor.
You cannot bind to a constant, a derived value, a prop or a literal: that is F01.
Add a label, a hint or your own error
Every control takes label:, hint: and error:. With any of them, the control is wrapped in a field:
- the label is a real
<label for>; - the hint and the error are linked to the control with
aria-describedby; - the error is a string, empty when there is none. When it appears, it is announced, and it sets
aria-invalidon the control.
This page shows an error while the handle is too short:
page Handle(path: "/handle", title: "Handle", description: "Pick a handle.") {
state handle = ""
derived problem = if handle.length > 0 && handle.length < 3 { "At least three characters" } else { "" }
Heading("Pick a handle").h1
Input(bind: handle, label: "Handle", hint: "Letters, numbers and dashes", error: problem)
}
For a rule about the value itself, a validate block is usually better: it works out the error for you (Validate a field). Use error: for a message that comes from somewhere else.
Group controls in a form
To submit several controls together, put them in a Form. Its on submit handler runs when the form is submitted, and the page never navigates away. Form(bind: form) gives you a handle, named form here, that knows the state of the whole form.
This contact form sends its fields, disables Send until every field is valid, and thanks the reader:
page Contact(path: "/contact", title: "Contact", description: "Send us a message.") {
state name = ""
state email = ""
state message = ""
state sent = false
action send() {
match await http.post("/api/contact", body: { name: name, email: email, message: message }) {
.ok {
sent = true
form.reset()
}
.err(e) { log(e.message) }
}
}
Heading("Contact us").h1
Form(bind: form) {
on submit { send() }
Input(bind: name, name: "name", label: "Name").required
Input(bind: email, name: "email", label: "Email").email.required
Input(bind: message, name: "message", label: "Message").required
Button("Send", type: .submit, disabled: !form.valid || send.pending).primary
Text("{form.values.keys().length} fields filled in").muted.sm
}
if sent { Alert("Thanks — we will be in touch.").success }
}
Note
Coming from React? A submit handler there starts with event.preventDefault(). A Form's on submit never reloads or leaves the page, so the handler holds only what the submit does. See Coming from React.
The form handle
| Member | What it is |
|---|---|
|
|
|
|
|
The message of every field that has one, by name |
|
|
Which fields the reader has left |
|
|
Whether an |
|
|
The controls' values by their |
|
|
Clears the form, and every message it was showing |
|
|
Submits the form from code |
|
|
Shows what the server said, on the fields it named (Show what the server said) |
|
|
The |
Choose which buttons submit
A Button with type: .submit (or the .submit flag) submits the form, and so does Enter in a field. The browser's own constraint checks run first (.required, .email and the rest), so an invalid form never reaches on submit.
Every other button in a form — Add a row, Show password — is type="button", and does only what its on click says.
Validate a field
To say what a value must be, put a validate block beside the state it guards. Each rule is one line. The control bound to that state shows the rules' messages itself: you write no error: and no derived value.
This page requires an email, a password of at least eight characters with a number in it, and a matching confirmation:
page Join(path: "/join", title: "Join", description: "Make an account.") {
state email = ""
state password = ""
state confirm = ""
validate email {
required
email
}
validate password {
required
minLength(8) "Use at least 8 characters"
pattern(/[0-9]/) "Include a number"
}
validate confirm {
matches(password) "The two passwords differ"
}
Heading("Join").h1
Form(bind: form) {
on submit { log("signing up") }
Input(bind: email, label: "Email").email
Input(bind: password, label: "Password").password
Input(bind: confirm, label: "Confirm").password
Button("Join", type: .submit, disabled: !form.valid).primary
}
}
Leave the password field after typing abc, and it shows Use at least 8 characters. Join stays disabled until every rule holds.
A validate block must guard a state that a control binds. A block for a state no control binds, or for a derived value, can never pass: that is F03.
Validation rules
| Rule | Holds when |
|---|---|
|
|
Something was given: a non-blank string, a non-empty list, a ticked checkbox |
|
|
The value looks like an email address, or a URL |
|
|
The text is at least, or at most, that long |
|
|
The number, date or time is within the limit |
|
|
The text matches the regular expression |
|
|
The value equals another value, and follows it as it changes |
|
|
The value is one of those listed |
|
|
The expression is true |
|
|
The answer is true, once it arrives |
How the rules behave:
- Messages. Each rule takes an optional message after it: a string, or
t("key"), which is read in the reader's language. Without one, the rule uses its own message. A project with translations replaces those by naming the keysform.required,form.email,form.minLengthand so on (Translate a site, Show validation messages). - Arguments that read state. An argument such as
max(Ledger.today)is read again each time the rule is checked. - Types. A rule is checked against the type of what it guards:
minLengthon aNumberisT01. - Empty values. Every rule but
requiredpasses an empty value, so a blank optional field shows one message rather than two. - Async rules. An
asyncrule is asked only once the other rules pass, and once per value. A server is not asked about every keystroke of an address that is not valid yet. While it waits,form.pendingistrue.
This rule asks the server whether an address is free. The rule passes when the check's answer is true, so ask the question whose answer you want to be yes:
api Backend(base: "/api") {
get emailFree(email: String) at "emailFree" -> Bool!
}
page Register(path: "/register", title: "Register", description: "Check an address is free.") {
state email = ""
validate email {
required
email
async "That address is taken" {
match await Backend.emailFree(email: email) { .ok(free) { free } else { false } }
}
}
Heading("Register").h1
Form(bind: form) {
on submit { log("registering") }
Input(bind: email, label: "Email").email
Button("Register", type: .submit, disabled: !form.valid || form.pending).primary
}
}
Choose when a message shows
Form(show:) sets when the messages appear:
|
|
A field's message appears |
|---|---|
|
|
after the reader leaves the field |
|
|
only after a submit |
|
|
as the reader types |
The rules run either way, so form.valid is always true to the values, whatever the reader has seen.
A submit that fails shows every message, moves focus to the first field that has one, announces it, and does not run on submit.
Preview every message at once
To see a form as a failed submit would leave it, without filling it in, set data-wf-validation="shown" on the page's root element:
document.documentElement.setAttribute("data-wf-validation", "shown")
Every field then shows what its rules say about its value now. Remove the attribute and the messages go again. An editor's preview sets this attribute to show a form as Invalid.
Let a refined type do the checking
A refined type is a type with a condition, such as Number(1..=30). The condition is already a rule, so you only write the rules the type does not say:
state nights: Number(1..=30) = 2
validate nights { required }
- A range's open end is excluded:
Number(0..10)does not take10. - A date's
after:andbefore:are checked as the reader types, likeminandmax.
See Types for every condition a type can carry.
Read the rules as data
wf rules --json lists, for a tool to read:
- every rule, what it takes, its own message and the translation key that replaces it;
- the patterns people write, by name:
a number,a letter(in any script),no spaces…; - the
show:choices; - every state the project holds to a rule, in order, including the rules its type implies.
The Rust library has the same data as webfluent::validation (with the internals feature, outside semver), which can also write a state's validate block back one rule at a time.
Show what the server said
When the server rejects a value — an address already taken, a code that expired — pass its messages, by field name, to form.apply:
enum SignUpError {
unprocessableContent(problem: FieldErrors) on 422
http(error: HttpError)
}
api Backend(base: "/api") {
post signUp(body: SignUp) at "signUp" -> ! SignUpError
}
action join() {
match await Backend.signUp(body: SignUp(email: email, password: password)) {
.ok { joined = true }
.err(.unprocessableContent(p)) { form.apply(p.errors) } // { email: "That address is taken" }
.err(.http(e)) { log(e.message) }
}
}
Each message is shown on the field it names: a field a validate block guards shows it as its own message, and any other control of the form shows it beneath itself when its name: matches — announced, marked aria-invalid, and named by aria-describedby. The focus moves to the first one. A message stays until the reader changes that field's value. A field may also be given a list of messages; the first is shown. Send a form to a server shows the whole page.
Upload a file
To let the reader pick a file, place a FileUpload and bind it: bind: holds the File chosen (File?, null until one is), or with .multiple the list of them ([File]). Its change event carries the same files, for a page that wants them as they arrive. Each is a File, with:
.name,.size(in bytes) and.type;.preview(), an object URL that shows an image before it is uploaded. It is revoked when the page leaves.
This page shows the picture the reader picks, then uploads it with a progress bar:
api Backend(base: "/api") {
post avatar(id: String, file: File) at "users/{id}/avatar" -> !
}
page Avatar(path: "/avatar", title: "Your picture", description: "Change your picture.") {
state picked: File? = null
state done = false
action upload() -> ! {
if let f = picked {
try await Backend.avatar(id: "me", file: f)
done = true
}
}
Heading("Your picture").h1
FileUpload(bind: picked, accept: "image/*", label: "Choose a picture")
if let f = picked {
Image(src: f.preview(), alt: "The picture you chose")
Text("{f.name}, {format(f.size / 1024, .integer)} kB").muted.sm
Button("Upload", disabled: upload.pending).primary { on click { upload() } }
if upload.pending { Progress(value: Backend.avatar.progress * 100, max: 100) }
}
if done { Alert("Uploaded.").success }
}
- An endpoint with a
Fileparameter sends a multipart form. Backend.avatar.progressfollows the upload from 0 to 1.FileUpload(bind: files).multiplelets the reader pick several files, held in a[File].
Important
accept: and any size limit you show are for the reader's convenience, not checks. The server decides what it accepts (Security).
Send a form to a server
To send a form, describe the service once with api, call it from the submit handler, and hand what a 422 said back to the form.
type SignUp { email: String, password: String }
type FieldErrors = Problem { errors: [String: String] }
/// Why an account can be refused.
enum SignUpError {
unprocessableContent(problem: FieldErrors) on 422
http(error: HttpError)
}
api Backend(base: "/api") {
post signUp(body: SignUp) at "signUp" -> ! SignUpError
}
page Welcome(path: "/welcome", title: "Join", description: "Make an account.") {
state email = ""
state password = ""
state joined = false
validate email { required email }
validate password { required minLength(8) }
action join() {
match await Backend.signUp(body: SignUp(email: email, password: password)) {
.ok { joined = true }
.err(.unprocessableContent(p)) { form.apply(p.errors) }
.err(.http(e)) { log(e.message) }
}
}
Heading("Join").h1
if joined { Alert("Welcome aboard.").success }
Form(bind: form) {
on submit { join() }
Input(bind: email, name: "email", label: "Email").email
Input(bind: password, name: "password", label: "Password").password
Button("Join", type: .submit, disabled: !form.valid || join.pending).primary
}
}
unprocessableContent(problem: FieldErrors) on 422 is the case a 422 answer arrives in, its body typed FieldErrors, so p.errors is what the server sent. If the server answers { "errors": { "email": "That address is taken" } }, the message appears under Email.
Data and APIs covers the service in full: retries, timeouts and typed errors.
Show that a request is running
An action that awaits has a .pending value, true while a call of it runs. Use it to show a spinner, or to keep a button busy with loading:. On a store's action, read it as Store.action.pending:
store Api {
state saved = 0
action save(payload: Json) -> ! {
try await http.post("/api/save", body: payload)
saved = saved + 1
}
}
page Notes(path: "/notes", title: "Notes", description: "Save a note.") {
use Api
state text = ""
Heading("Notes").h1
Input(bind: text, label: "Note")
Button("Save").primary { on click { Api.save({ text: text }) } }
Button("Save a copy", loading: Api.save.pending) { on click { Api.save({ text: text, copy: true }) } }
Text("Saved {Api.saved} times")
}
- A button or a form waits for its work. A
Button'son clickor aForm'son submitthat calls an action that awaits is busy until that call ends:aria-busy, a press that does nothing, and, past a moment, a spinner in place of its label at the same width. The focus stays on it. Nothing has to be written for it. - A double click submits once. A call of an action with the same arguments as one still running is that call: the work is not done twice, and both get the same answer. A call with other arguments — the next row's save — runs beside it. An action whose every call should run, a poll, says so:
action poll() concurrent { … }. loading:keeps any button busy while a value holds — another button's work, a store's state.
Reading .pending on an action that awaits nothing is T17.
Choosing: toggles, groups, steps and days
Some choices are not a text field. These built-ins draw them, each with the keyboard a reader expects:
page Order(path: "/", title: "Order", description: "Choose how it is sent.") {
state view = "grid"
state plan = "free"
state qty = 1
state step = 0
state day: Date? = null
Heading("Order").h1
ToggleGroup(bind: view, label: "View") {
ToggleGroup.Item("Grid", value: "grid", icon: "grid")
ToggleGroup.Item("List", value: "list", icon: "list")
}
RadioGroup(bind: plan, label: "Plan").cards {
RadioGroup.Option("Free", value: "free", hint: "For trying it out")
RadioGroup.Option("Team", value: "team", hint: "€8 a seat")
}
NumberInput(bind: qty, min: 1, max: 9, label: "Quantity")
Stepper(bind: step) {
Stepper.Step("Address") { Text("Where it goes.") }
Stepper.Step("Delivery") {
Calendar(bind: day, disabled: d => d.weekday() >= 6, label: "Delivery day")
}
}
}
Toggleis one button that stays pressed;ToggleGroupis a row of them, one chosen (or several,.multiple). Tab stops once on the group, and the arrow keys move inside it.RadioGroupis native radio buttons under a legend;.cardsdraws each as a card with its hint.NumberInputsteps with − and +, the arrow keys, and PageUp and PageDown, and stays betweenmin:andmax:.Pagination(bind: page, pages: n)draws the pages of a list, with gaps for the ones it leaves out.Steppershows one step at a time and each step's state.CheckboxGroupticks the values of a list, withall:a box for every one;TagInputmakes words chips;InputOTPtakes a one-time code a digit to a box;Ratingis stars a keyboard can set;Slider(…).rangehas two thumbs;DateRangePickerchooses a first and a last day in two months, or by a preset.Textarea(…).autosizegrows with its text,Input(…).password.revealcan show what was typed, andFileUpload(bind: files).dropzonetakes files dropped on it.Calendaris a month a keyboard can work: the arrows by day and week (the other way round right to left), PageUp and PageDown by month..rangeholds{ start, end },.multiplea list.
Checklist for a good form
- Every control has a
label:. A placeholder is not a label. - Rules live in
validateblocks, not in hand-writtenderivederrors. - The submit button is
type: .submit, so Enter submits. - The submit button is disabled while the request runs:
disabled: save.pending. - The page says what happened afterwards, in an
Alertor aToast. - Server errors go back to their fields with
form.apply. - The server checks everything again. The page's rules are for the reader.
Troubleshooting
| What you see | Why, and what to do |
|---|---|
|
|
The target cannot be written: a constant, a derived value, a prop or a literal. Bind a |
|
|
The control cannot hold the state's type, such as a text |
|
|
No control binds that state, or it is a derived value, so its rules can never pass. |
|
|
The rule does not fit the type, such as |
|
|
The form is invalid, so the submit stopped. Check |
| A button submits the form by accident |
Only |
| A server message never shows |
|
| A message shows before the reader has typed |
The form uses |
Common mistakes
A text field bound to a number. An Input with no type flag holds a String, so it cannot write a Number state:
page P(path: "/", title: "Seats", description: "Pick a number of seats.") {
state seats = 1
Heading("Seats").h1
Input(bind: seats, label: "Seats")
Text("{seats} seats")
}
Add .number, which holds a Number, or use a Slider (F02).
A validate block for a state no control binds. The rules check the state, and nothing the reader types reaches it:
page P(path: "/", title: "Join", description: "Make an account.") {
state email = ""
validate email { required email }
Heading("Join").h1
Input(label: "Email").email
Text("You typed {email}")
}
Bind the control to the state the rules guard: Input(bind: email, label: "Email") (F03).
A bind: to a derived value. A control writes back to what it binds, and a derived value is worked out, never assigned:
page P(path: "/", title: "Handle", description: "Pick a handle.") {
state first = ""
derived handle = first.toLowerCase()
Heading("Handle").h1
Input(bind: first, label: "First name")
Input(bind: handle, label: "Handle")
}
Bind a state instead, and show the derived value with Text(handle) (F01).
What you learned
-
Bind any control to a state, a store member or a list item with
bind: -
Write
validaterules and let the bound control show their messages -
Read the whole form through
Form(bind: form):form.valid,form.errors,form.apply -
Upload a file and follow its progress
-
Send a form to an
apiand show what the server answered