2. Forms¶
A bike comes in through the door. Before anyone touches it the shop writes down whose it is, what kind of bike, what is wrong with it and when the customer can have it back. This page builds that counter screen.
A form¶
view [
title "Book a repair"
form [
field customer "Customer" required
field phone "Phone" "So we can call when it is ready"
choice bike "Bike" ["Road" "Mountain" "City" "Child's"] required
area fault "What is wrong" required
money estimate "Estimate" min $0
date due "Due back" required
submit "Book in" [toast rejoin ["Booked in for " values/customer]]
]
]
form lines its faces up in two columns, labels on the left and controls on the right. When it is narrow,
on a phone or in a narrow column, it puts each label over its control instead. Each face inside it reads the same way:
the style says what kind of value it takes:
fielda line of text,choiceone of a list,areaa few lines,moneyan amount,datea day;the word after the style is the field’s name,
customerordue;the first string is its label and the second, when there is one, the hint shown while it is empty;
the rest are rules:
required,min $0.
Try it before reading on. The button looks disabled until every field is valid, and pressing it anyway points out every field that is not. A field that breaks a rule says so when you leave it, not while you are still typing, and the message goes as soon as it is fixed.
The values¶
submit is a button that belongs to its form: it only runs its action when the form is valid, and Enter
in any field presses it. Inside its action, values is a map of every named field and its value:
view [
title "Book a repair"
form [
field customer "Customer" required
choice bike "Bike" ["Road" "Mountain" "City" "Child's"] required
money estimate "Estimate" min $0
date due "Due back" required
submit "Book in" [booked/text: mold values]
]
booked: text muted "Nothing booked yet."
]
Each value has its own type. The estimate is a money! and the due date a date!, ready to add, compare or
store, the same values the first tutorial worked with. A field left empty is none. Nothing in the form had
to turn text into a number.
Options in groups¶
A long list of options is easier to read in groups. In the options of a choice, a title followed by a block
is a group, with the block’s options under the title; options on their own and groups can go together:
view [
form [
choice job "Job" [
"Repairs" ["Puncture" "Brakes" "Gears"]
"Service" ["Basic service" "Full service"]
"Something else"
] required
submit "Book in" [toast values/job]
]
]
What the program receives is still the option chosen, here "Brakes", not its group. A radio takes groups
the same way, and shows each title over its options.
A number on a line¶
Some numbers are easier to pick than to type, when what matters is roughly where they sit between two ends.
A slider is a handle on a line, with the number it stands at after it:
view [
form [
slider pressure "Tyre pressure" 20 120 step 5
slider wear "Chain wear" 0 1 step 0.25
submit "Save" [toast rejoin [values/pressure " psi"]]
]
]
The two numbers are the least and the most it takes, 0 and 100 when they are left out, and step how far
one move takes it, 1 unless told. It starts at its least, and its value is a number, an integer unless the step
makes it a decimal. Dragging it, or the arrow keys, Home and End, move it; its action and on-change run as
it moves.
Two dates¶
A booking, a holiday or a report covers days from one to another. A date-range picks both on one calendar:
the first day you pick stays marked, and the second closes it.
view [
form [
date-range hire "Bike hire" required min 1-Jan-2026
submit "Book" [toast rejoin ["From " localize values/hire/1 " to " localize values/hire/2]]
]
]
Its value is a block of two dates, the start first: [3-Nov-2026 10-Nov-2026]. The field shows them in the
active language, and they can be typed too, apart by a dash. min holds for the start and max for the end.
A time of day¶
A time takes an hour and its minutes. Its button lists the times of the day, half an hour apart, or step
minutes apart; min and max keep them within opening hours:
view [
form [
date day "Day" required
time drop-off "Drop-off" required min 8:30 max 18:00 step 15
submit "Book" [toast rejoin ["Drop-off at " localize values/drop-off]]
]
]
Its value is a time!, shown in the active language. It can be typed as 9:30, 9.30 or 9:30 pm.
Rules of your own¶
The built-in rules cover the usual cases: required, email, url, integer, iban, min and max
for numbers, amounts and dates, length 3 20 for text, and match for a field that must repeat another. A rule
of the shop’s own is a check block. It sees the field’s value as value and says true when the value is
good, or the message to show when it is not:
view [
title "Book a repair"
form [
field customer "Customer" required length 2 60
date due "Due back" required check [
case [
value < now/date ["That day has already gone"]
value/weekday = 7 ["The shop is closed on Sundays"]
true [true]
]
]
submit "Book in" [toast "Booked in"]
]
]
Pick a Sunday and leave the field. A check runs whenever its value changes, so keep it quick; a rule
that has to ask a server is a check-async, which a later page uses.
A rule the shop needs in many fields gets a name with rule, and then goes after a field as email does.
The shop’s frame numbers are two letters and six digits:
alpha: charset [#"A" - #"Z" #"a" - #"z"]
digit: charset "0123456789"
rule 'frame-number #(en: "Enter a frame number, like WT123456" es: "Introduce un número de cuadro, como WT123456") [
parse value [2 alpha 6 digit]
]
view [
title "Book a repair"
form [
field frame "Frame number" required frame-number
field old-frame "Frame it replaces" frame-number
submit "Book in" [toast "Booked in"]
]
]
Its block sees value, face and values as a check does, and runs only when the field has a value. It
gives true when the value is good; none or false shows the rule’s message, which is a text, or a text per
language, as the languages page tells; a string shows that string instead. The message is
kept in i18n/ui under the rule’s name, so an app can say it its own way:
poke i18n/ui 'frame-number #(en: "That is not one of our frames").
A package of rules, the ones of a country for instance, is a module of rules: a program that imports it,
import 'trebol-es, can write those words after its fields (see packages).
Faces that follow others¶
Some faces only show what others hold: the price of the repair, worked out from the hours and the parts, or
a line that sums up the booking. calc gives a field a formula, is gives any face one, and react runs a
block of your own:
view [
title "Quote"
form [
number hours "Hours" min 0
money parts "Parts" EUR min 0
money total "Total" EUR calc [values/hours * 30 + values/parts]
text muted is [
either values/total [rejoin ["The customer pays " localize values/total]] ["Fill in hours and parts"]
]
check rush "Rush job"
text warning hidden react [face/hidden: not values/rush face/text: "Ready tomorrow, 20% more"]
submit "Send quote" [toast "Quote sent"]
]
]
Type the hours and the parts. Each of these blocks runs when its face is shown and again whenever something it
reads changes, and Trebol tells what it reads by looking at it: values/hours, face/hidden, or a face’s
label and facet, as in search/text. A block that reads what another one sets runs after it, so the line
below the total follows the total. calc makes the field read only: its value is the formula’s, and a
formula that cannot be worked out yet, because a field is empty, leaves it empty. is sets what the face
shows, its value for a field and its text for a text; react sets whatever it likes, and react later
waits for the first change instead of running when shown.
A block can read more than faces: any word that holds an object, down a path as deep as it goes, such as
settings/look/dark or the state and data of a machine (page 15 of the language tutorial). Whatever changes
it, a click, a timer of the machine or another tab, the faces that read it follow:
repair: machine [
data [bike: none]
initial received
state received []
state repairing []
from received to repairing on start set [bike: event/bike]
from repairing to received on fixed
]
view [
title "Workshop"
text is [either in? repair 'repairing [rejoin ["Repairing " repair/data/bike]] ["Nothing on the stand"]]
row [
button "Start" react [face/disabled: in? repair 'repairing] [send repair [start bike: "Brompton"]]
button "Done" react [face/disabled: not in? repair 'repairing] [send repair 'fixed]
]
]
in? repair 'repairing counts as reading repair/state.
A face that is hidden folds away, and one shown again unfolds, as the warning here does when the box is ticked; the first time a screen shows, its faces are simply there.
A form in steps¶
A long form reads better a part at a time. The shop’s web page takes repairs too, and a customer filling it
in at home answers who they are, then what is wrong, then checks it all before sending. steps splits a
form like that, each step a title and its block:
view [
title "Book a repair"
form [
steps [
"You" [
radio account "Who brings it" ["Me" "My company"] required
field customer "Name" required
field phone "Phone" required
]
"Company" when [values/account = "My company"] [
field company "Company" required
field tax-id "Tax id" required
]
"The bike" [
choice bike "Bike" ["Road" "Mountain" "City" "Child's"] required
area fault "What is wrong" required
]
"Check" [
text is [rejoin [any [values/customer ""] ", a " any [values/bike "bike"] " bike: " any [values/fault ""]]]
]
]
submit "Book in" [toast rejoin ["Booked in for " values/customer]]
]
]
Only one step shows, under a bar with every title. Next moves on when the fields of the step are valid,
and otherwise points out the ones that are not, as submit does for the whole form; Enter in a field presses
it. Back keeps what was typed. The submit of the form waits for the last step, and values there holds
the fields of every step.
A step with when is there only while its block is true. Choose My company and a step for the company
comes in; choose Me again and it goes, its fields with it: they are not checked, and they are not in
values.
A step done can be chosen again by its title, and the browser’s Back goes to the step before, as people
expect from a form on the web. The step on show is the value of steps, so a button can go back to one:
with go: steps [...], a Change button on the last step is button "Change" [go/value: 1].
When which step comes next is more than one when, a machine (page 15 of the language tutorial) can lead the
steps. Its word goes after steps, and each step starts with the name of its state:
booking: machine [
data [account: none]
initial you
state you []
state company []
state bike []
state check []
from you choose on next [
when [event/values/account = "My company"] to company set [account: "company"]
else to bike set [account: "own"]
]
from company to bike on next
from bike to check on next
]
view [
title "Book a repair"
form [
steps booking [
you "You" [
radio account "Who brings it" ["Me" "My company"] required
field customer "Name" required
]
company "Company" [
field company "Company" required
]
bike "The bike" [
area fault "What is wrong" required
]
check "Check" [
text is [rejoin [any [values/customer ""] ": " any [values/fault ""]]]
]
]
submit "Book in" [toast rejoin ["Booked in for " values/customer]]
]
]
The step on show is the one of the state the machine is in. Next checks the fields of the step, as before,
and sends the machine next, with the values of the form in event/values; where it goes is the machine’s
choice, and it may keep what it needs in its data. Next is there while the machine has a way out on
next (can? booking 'next), so on the last step the submit takes its place. Back puts the machine back
where it was before that Next, its data too, and nothing in on-enter runs again: the machine only says the
way forward. The steps it did not go through do not apply, as with when.
A photo¶
photo shows an image and lets the person choose another: with its button, by clicking the image, or by
dropping one on it. On a phone, the button offers the camera too. round makes it a circle, as for a
person:
view [
title "Customer"
global card: form [
photo picture "Photo" round
field name "Name" required
submit "Save" [saved/text: mold values]
]
saved: text muted "Nothing saved yet."
]
set-values card #(name: "Ada Lovelace" picture: "ada.svg")
A record that has a photo gives its address, as it comes from the server, and the field shows it. When the
person chooses another, the value becomes that image, an object with its name, size, type and file,
the same as one file of an upload; the server page sends it. Removing it leaves none. It takes
images only, unless accept says otherwise.
What’s next¶
A form on its own fills the page from side to side. The next page arranges the counter screen: the form beside the day’s bookings, grouped in panels, and what happens to all of it on a phone.