Guide / Controls / Reference

Form

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
FieldTypeDefaultWhat it does
modemodechoiceone of 2create

Add new or edit existing

Chooses whether the form starts blank or is filled from the selected record and refilled when the selection moves.

  • create defaultstart blank to add a new record
  • editfill from the selected record to change it
collectioncollectiontext—

Which saved list it works on

Names the local collection the form reads from when editing and saves into by default.

fieldsfieldsobject—

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.

submitsubmitobject—

What Save does

Runs this one action with the whole draft when the form is submitted, writing everything at once.

afterSubmitafterSubmitchoiceone of 2clear

What happens to the entries after saving

Decides whether the form empties back to its starting values or keeps what was just submitted.

  • clear defaultempty 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.

New plant form

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.

JSON 18 lines
{ "type": "group", "id": "plantForm", "label": "New plant",
  "position": [0, 0], "span": [5, 4], "grid": { "columns": 2, "rows": 3, "rowHeight": 76 },
  "form": {
    "collection": "plants",
    "fields": {
      "name":      { "required": true, "maxLength": 40 },
      "everyDays": { "required": true, "min": 1, "max": 60, "kind": "integer" },
      "room":      { "oneOf": ["Kitchen", "Office", "Porch"] }
    },
    "submit": { "method": "local", "op": "insert", "set": "{{form}}" }
  },
  "children": [
    { "type": "textInput", "id": "name", "position": [0, 0], "span": [1, 2], "placeholder": "Name" },
    { "type": "stepper", "id": "everyDays", "position": [1, 0], "min": 1, "max": 60, "label": "Every (days)" },
    { "type": "picker", "id": "room", "position": [1, 1], "options": ["Kitchen", "Office", "Porch"] },
    { "type": "button", "id": "save", "position": [2, 0], "span": [1, 2], "label": "Save", "role": "submit",
      "enabled": { "ref": { "field": "plantForm.valid" }, "operator": "eq", "value": true } }
  ] }

Open in CAR-TER

Form that posts to a web address

Sends the draft to a server instead of the local store. Intended effect: tapping Send posts the typed note, then the form keeps its text.

JSON 11 lines
{ "type": "group", "id": "noteForm", "label": "Note",
  "position": [0, 0], "span": [5, 2], "grid": { "columns": 1, "rows": 2, "rowHeight": 76 },
  "form": {
    "fields": { "note": { "required": true, "maxLength": 200 } },
    "submit": { "method": "http", "path": "/notes", "payload": "{{form}}" },
    "afterSubmit": "keep"
  },
  "children": [
    { "type": "textInput", "id": "note", "position": [0, 0], "placeholder": "Note" },
    { "type": "button", "id": "send", "position": [1, 0], "label": "Send", "role": "submit" }
  ] }

Open in CAR-TER

Edit form for the selected row

Fills from the row picked in a list and updates it. Intended effect: choosing a plant loads its name, and Save changes that row in place.

JSON 12 lines
{ "type": "group", "id": "editPlant", "label": "Edit plant",
  "position": [0, 0], "span": [5, 2], "grid": { "columns": 1, "rows": 2, "rowHeight": 76 },
  "form": {
    "mode": "edit",
    "collection": "plants",
    "fields": { "name": { "required": true, "maxLength": 40 } },
    "submit": { "method": "local", "op": "update", "id": "{{selected}}", "set": "{{form}}" }
  },
  "children": [
    { "type": "textInput", "id": "editName", "field": "name", "position": [0, 0], "placeholder": "Name" },
    { "type": "button", "id": "saveEdit", "position": [1, 0], "label": "Save", "role": "submit" }
  ] }

Open in CAR-TER

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.

Generated from ControlDocs/form.md. Something unclear or missing? Tell me.