Skip to main content

Module schema

Module schema 

Source
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 inputs

IDs 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. width is in 12ths.
Condition
One predicate of a ConditionalRule.
ConditionalRule
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 data JSON.
FormSettings
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.
TransLeaf
One translatable text leaf in a form, for the per-locale editor.
ValidationRule
A validation rule (this is the storage shape).

Enums§

FieldType
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 by translatable_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 field is visible given the current answers (key → value). Rules apply in order: a show rule makes visibility equal to its match; a hide rule 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 data JSON 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._draft when 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 data that publishes draft: top level := draft, and _draft := the same (so editing continues from the published state).
save_draft_value
Produce new data that stores draft under _draft while 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. Returns field when 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 None when valid. Empty values pass here — “required” is enforced separately by the submit handler.