Expand description
Form Builder schema.
The visual builder stores a whole form as one JSON document in the
backing snippet’s data column (type_name = "form"). This module is
the pure, IO-free contract for that document: serde types + validation
- small traversal helpers. Everything downstream — the builder editor, the public renderer, the submit handler, the submissions admin — reads and writes through these types.
Shape (mirrors the user’s hierarchy):
Form
├─ settings (submit label, success message/redirect, notify emails)
└─ pages[] ← wizard steps (next/prev)
└─ sections[] ← logical groupings within a page
└─ rows[] ← a 12-column grid row
└─ columns[] (width 1..=12)
└─ fields[] ← the typed inputsIDs are client-minted UUID strings, stable across reorder (the builder JS reuses them); validation never depends on array position.
Structs§
- Choice
- A choice option for selection field types.
- Column
- A grid cell holding fields.
widthis in 12ths. - Condition
- One predicate of a
ConditionalRule. - Conditional
Rule - A conditional rule (this is the storage shape).
- Field
- One input (or presentational element) in a column.
- Form
- One built form. Serialized as the snippet
dataJSON. - Form
Settings - Form-level defaults. An embed block may override the success redirect / message per placement.
- Page
- A wizard step.
- Row
- A 12-column grid row.
- Section
- A labelled grouping of rows within a page.
- Trans
Leaf - One translatable text leaf in a form, for the per-locale editor.
- Validation
Rule - A validation rule (this is the storage shape).
Enums§
- Field
Type - Every field/input type the builder offers.
Functions§
- apply_
translations - Apply per-locale
overrides(field_path → text) to a form’s text leaves, in place. Missing/empty overrides leave the canonical text. Mirror of the keys produced bytranslatable_leaves. - has_
unpublished_ changes - True when the draft differs from the published top level.
- is_
valid_ key - A field key must be a simple identifier:
[A-Za-z][A-Za-z0-9_]*. - is_
visible - Whether
fieldis visible given the currentanswers(key → value). Rules apply in order: ashowrule makes visibility equal to its match; ahiderule hides when matched. No rules → always visible. The runtime (form_runtime) mirrors this logic in JS; the server uses it so hidden fields are excused from “required”. - parse
- Parse a form from a snippet
dataJSON value. Missing keys default, so a partial/empty{}yields an empty form rather than an error. - parse_
draft - Parse the DRAFT a builder should edit:
data._draftwhen present, else the published top level (forms predating draft/publish edit live). - parse_
str - Parse from a JSON string (e.g. a hidden builder input).
- publish_
value - Produce new
datathat publishesdraft: top level := draft, and_draft:= the same (so editing continues from the published state). - save_
draft_ value - Produce new
datathat storesdraftunder_draftwhile leaving the published top level untouched. Save-draft path. - slugify_
key - Derive a valid field key from a human label (builder auto-slug helper).
Lowercases, replaces runs of non-alphanumerics with
_, and ensures it starts with a letter. Returnsfieldwhen nothing usable remains. - to_
value - Serialize a form back to a JSON value for storage in
snippet.data. - translatable_
leaves - List every translatable text leaf in document order: settings messages, then page labels / section titles / field label+help+placeholder / choice option labels / presentational content. Keys are id-based so they survive reorder. A single-page form’s page label is left out: it is never shown.
- validate
- Validate a form for save. Returns a list of human-readable problems (empty = valid). Non-fatal in the builder UI; the save handler may surface these as field errors.
- validate_
value - Server-side validation of one submitted value against a field’s rules.
Returns an error message, or
Nonewhen valid. Empty values pass here — “required” is enforced separately by the submit handler.