form

Fields a person fills in to add a row to a table or change one, such as a new agent's rules or a ticket's status.

table is the table it writes; mode is insert (the default: a new row) or update (the row the address's ?id= names, its fields filled in). fields lists 1 to 20 fields: name (the column written), label, kind (text, textarea, number, date, email, password, select, switch, checkbox, lookup), required, min/max for numbers, pattern, hint; a select needs options and a lookup needs lookup: { table, label, value }. submit is { label, approval, then }: approval: true shows a confirm card before writing; then is the screen opened after. Every field is checked again on the server.

When to use

Use it when

A person adds something, such as a new agent described in plain language.
A person corrects one record, such as a ticket's subject or agent.
A request that someone approves before it is written, such as an order.

Use another block when

The same column changed on many rows at once.
Use grid
A yes or no on a row someone else asked for.
Use approval
A link to the screen where the form lives.
Use button

Build an agent

form:
  table: agent_drafts
  fields:
    - { name: name, label: Name, required: true, hint: How people will see it in the queue }
    - { name: starts_when, label: Starts when, kind: textarea, required: true }
    - { name: budget_usd, label: Monthly model budget ($), kind: number, min: 0, max: 100000 }
    - { name: test_on, label: Test first on, kind: select, options: [Last 100 tickets of this kind, No test run] }
  submit: { label: Test and save, then: agents }

<a id="form-1"></a>

Form: inserts a row into agent_drafts

- name "Name": text, required — How people will see it in the queue
- starts_when "Starts when": textarea, required
- budget_usd "Monthly model budget ($)": number, min 0, max 100000
- test_on "Test first on": select, one of Last 100 tickets of this kind, No test run

Submit "Test and save" · approval: no · then /a/catalog/agents

- #form-1.insert "Test and save": POST /a/catalog/{screen}/act/form-1/insert · fields name, starts_when, budget_usd, test_on; inserts a row into agent_drafts · approval: no · cost: write

Correct a ticket

form:
  table: tickets
  mode: update
  fields:
    - { name: subject, label: Subject, required: true }
    - { name: agent, label: Agent, kind: lookup, lookup: { table: agents, label: name, value: name } }
    - { name: status, label: Status, kind: select, options: [Needs a person, Closed by agent] }
  submit: { label: Save ticket, then: ticket }

<a id="form-1"></a>

Form: updates the row of tickets that ?id= names

- subject "Subject": text, required
- agent "Agent": lookup, from agents (name = name): Identity = Identity, Apps = Apps
- status "Status": select, one of Needs a person, Closed by agent

Submit "Save ticket" · approval: no · then /a/catalog/ticket

- #form-1.update "Save ticket": POST /a/catalog/{screen}/act/form-1/update · id=row id, fields subject, agent, status; updates that row of tickets · approval: no · cost: write

An order that needs approval

form:
  table: orders
  fields:
    - { name: item, label: What to order, required: true }
    - { name: amount_usd, label: Amount ($), kind: number, min: 1, required: true }
    - { name: urgent, label: Needed this week, kind: switch }
  submit: { label: Request the order, approval: true }

<a id="form-1"></a>

Form: inserts a row into orders

- item "What to order": text, required
- amount_usd "Amount ($)": number, required, min 1
- urgent "Needed this week": switch

Submit "Request the order" · approval: yes

- #form-1.insert "Request the order": POST /a/catalog/{screen}/act/form-1/insert · fields item, amount_usd, urgent; inserts a row into orders · approval: yes · cost: write

States

ready
the fields, empty (insert) or filled from the row (update)
invalid
the fields again, each refused one with its sentence
error
the row could not be read or written: the sentence; the page still answers 200

Action	Needs	Does	Reversible	Confirm page	Cost
insert	every field valid	inserts the form's fields as one row into the table	yes	when declared	write
update	every field valid, and the row `?id=` names	writes the form's fields to that row	yes	when declared	write

JSON Schema