A form is a group with a form block. Its input children write to a draft, and one submit writes the whole draft at once. Typing never writes anything until the user submits.
Symbol
list.bullet.rectangle.portrait
Docs
Docs complete
Fields
5 fields, each with what it does.
Fields
Field
Type
Default
What it does
modemode
choiceone of 2
create
Add new or edit existing
Chooses whether the form starts blank or is filled from the selected record and refilled when the selection moves.
createdefaultstart blank to add a new record
editfill from the selected record to change it
collectioncollection
text
—
Which saved list it works on
Names the local collection the form reads from when editing and saves into by default.
fieldsfields
object
—
The rules for each entry
Checks each field against its rules and shows an error under it, and refuses the submit while any rule fails.
submitsubmit
object
—
What Save does
Runs this one action with the whole draft when the form is submitted, writing everything at once.
afterSubmitafterSubmit
choiceone of 2
clear
What happens to the entries after saving
Decides whether the form empties back to its starting values or keeps what was just submitted.
cleardefaultempty the form back to its starting values
keepleave what was submitted in place
Examples
3 examples, each one a control you can paste into a layout.
Adds a plant to the local plants collection once every rule passes. Intended effect: Save is refused with errors shown until the name and watering interval are valid, then one row is inserted and the form clears.
draft instead of firing their own actions, a closed set of validators checks the
How it works
Fields. Every input inside the group (textInput, stepper, slider, toggle,
picker, segmentedControl, datePicker, colorPicker, including those in nested
groups but not in a nested form) is a draft field. The field name is the input's
field key, else its id. Use field when two forms write the same column (an
add form and an edit form both writing name), because control ids are unique in a layout.
No writes before submit. While an input belongs to a form, its own action never
fires, its value never reaches the control store, the mesh, or glance surfaces. The
draft is the only place the value lives.
Submit. A Border thickness with "role": "submit" inside the form submits it. If any
field fails validation the submit is refused, every error shows, and nothing is
written. Otherwise submit runs once with {{form}} = the draft object (every field;
an empty field is null; kind: integer/number turns a typed "12" into 12).
Starting values. A field starts at the input's defaultValue, else what the input
shows with no value: a stepper or slider's min, a picker's first option, a toggle off,
a date picker's current time, an empty text field.
Edit mode. With "mode": "edit" the draft is filled from the record whose id is the
collection's selection cursor ({{selected}}, moved by a local action with
op: "select"), and refilled when the selection changes. Pair it with
"op": "update", "id": "{{selected}}".
Validators
A closed set. Anything else (including pattern/regex) makes the layout fail to load.
Validator
Value
Fails when
required
bool
the field is empty (no value, blank text)
min / max
number
the value (or a numeric string) is below / above it
minLength / maxLength
integer ≥ 0
the text is shorter / longer
oneOf
array
the value is not one of the listed values
kind
integer | number | date | email | url
the value is not that kind (date = yyyy-MM-dd or ISO-8601; url = http/https with a host; email is a structural check)
An empty optional field is valid; only required checks emptiness. An input with an
error shows a red outline and the message on its own line below the control (never over
the value). It shows once the user commits an edit (a text field loses focus or Return is
pressed; a stepper steps; an option is picked), or when a submit is refused. Typing alone
never flashes an error.
A Symbol color or Track roundness field holds what the control shows: a value outside its
min/max (a default, a prefilled row) is pinned into range in the draft too.
A submit button gated on valid ("enabled": {"ref": {"field": "<formId>.valid"}, …})
is dimmed while the form is invalid, but a tap on it still reaches the form: the submit
is refused and every field's error shows. No alert. Leave room for the error line: give
the form's grid a taller rowHeight (the sample uses 76).
Cells for conditions
A form exposes readable cells, addressed with a field ref in any Visibility
condition (visible / enabled):
Ref
Value
{"field": "<formId>.valid"}
true when every field passes
{"field": "<formId>.dirty"}
true when the draft differs from its starting values
{"field": "<formId>.<field>"}
the field's draft value
{"field": "<formId>.<field>.error"}
the shown error message, null when none
{"derive": "form.<formId>.valid"} is the same cell spelled as a derive.