Form

A container that collects its child inputs and submits them to a database through a write named query. Validation, submission and the success/error outcome are handled for you — the result arrives as submitSuccess or submitError rather than as a script you have to write.

Reach for it when you need:

• Downtime and defect entry
• Batch records and quality checks
• Any structured data entry that lands in SQL

Component name: Form · Category: Input

In the palette: Collect inputs and submit them to a database via a write Named Query

Properties

Any property can be bound to a tag, another component's property, or a query.

Property	Type	Default	Description
size	enum	inherit	Height, padding and text of every field in this form (and its Submit button). Project default = the project's Control size (Project settings → Theme). Use md or larger on touch panels. Options: inherit · xs · sm · md · lg · xl. 1.0.8
header	object	{"title":"","subtitle":"","align":"left","divider":false,"ba… (truncated)	Optional header block above the fields: title + subtitle text, alignment, a divider line, and its own background / spacing / text styling. Leave title and subtitle blank = no header.
↳ header.title	string	""	Heading text. Blank = no title line.
↳ header.subtitle	string	""	Descriptive line under the title. Blank = none.
↳ header.align	enum	left	Align the title + subtitle: left, center, or right. Options: left · center · right.
↳ header.divider	boolean	false	Draw a divider line between the header and the form fields.
↳ header.background	color	""	Header background color. Blank = transparent.
↳ header.padding	number	12	Inner padding (px) around the header content.
↳ header.margin	number	0	Outer margin (px) around the header block.
↳ header.titleSize	number	16	Title font size (px).
↳ header.titleWeight	enum	semibold	Title font weight. Options: normal · medium · semibold · bold.
↳ header.titleColor	color	""	Title text color. Blank = theme default.
↳ header.subtitleSize	number	12	Subtitle font size (px).
↳ header.subtitleColor	color	""	Subtitle text color. Blank = muted theme default.
autoHeight	boolean	true	Auto-grow the form's HEIGHT (header + fields) so nothing clips when fields stack on mobile/narrow widths — works in Coordinate, Flex and Grid. Width is unaffected. Turn off for a fixed-height box you size by hand (the field area then scrolls).
insertQuery	enum	""	The INSERT (write-type) Named Query this form submits — its :params become the fields. Also used in edit mode when no updateQuery is set (e.g. an upsert).
updateQuery	enum	""	Edit mode: the write-type Named Query run when recordId is set (UPDATE … WHERE :recordKey). Blank = use insertQuery for both insert and edit (e.g. an upsert).
selectQuery	enum	""	Edit mode: the SELECT (read-type) Named Query that fetches the row to edit by its key (SELECT … WHERE :recordKey). Its columns seed the fields (column name = field param).
recordFromTable	enum	""	Convenience (SAME view): pick a Table on this view → recordId is auto-bound to its selected row's key, making this Form the editor for that table's selection. It just sets recordId for you (you can still edit recordId by hand).
recordFromParam	string	""	Convenience (DIALOG / other view): the name of the view Param that carries the record id (passed by the Panel action that opens this Form, e.g. params: { id: row.id }). Auto-binds recordId to {{params.<this>}}. Use recordFromTable instead when the Table is on the same view.
recordId	string	""	The key value of the row to edit (bind to a selected table row / tag / param). Empty = insert mode (new row).
recordKey	string	id	The key column / param name used by selectQuery and updateQuery (e.g. 'id').
resetAfter	boolean	false	Clear the fields after a successful insert (ignored in edit mode)
style	style	{}	Custom CSS properties

Events

Attach event actions to these in the Event Manager.

Event	Label	Group	Payload
click	Click	Mouse	The DOM event.
dblclick	Double click	Mouse	The DOM event.
contextmenu	Right click	Mouse	The DOM event.
mouseenter	Mouse enter	Mouse	The DOM event.
mouseleave	Mouse leave	Mouse	The DOM event.
change	Change	Input	The DOM event.
submit	Submit	Input	The DOM event.
focus	Focus	Input	The DOM event.
blur	Blur	Input	The DOM event.
submitSuccess	Submit success	Form	context.submit — the submitted values.
submitError	Submit error	Form	error (bare) plus context.submit.

Right-click behaves differently in the Designer

contextmenu fires your configured actions at runtime only — in LiveView and in preview. On the Designer canvas the right-click is captured to open the Event Manager, so testing it there will not run your actions. Test right-click in preview.

Notes

Submitting through a named query rather than inline SQL keeps the statement in one place, binds parameters instead of concatenating them, and lets the screen work without database credentials of its own.

Two field fixes in 1.0.7: Changed in 1.0.7 a field's clearable now works on number and password fields, where it saved but drew nothing; and a wysiwyg field is resizable from a 180-pixel minimum and no longer offers the person filling the form a switch to Markdown source — see WYSIWYG.

What the outcome events hand a script

submitSuccess carries the submitted values as context.submit. submitError carries the error as a bare error, and the values as context.submit too, so a handler can tell the operator which record failed. The Event Manager shows this under each event. New in 1.0.8

Every field on one size New in 1.0.8

The form's fields used to draw at a fixed 44 px with small text, whatever else was on the screen. They now follow the same scale as the field widgets — xs 28 · sm 36 · md 44 · lg 52 · xl 64 px — and the form's size sets it for every field and the Submit button at once. Project default follows the project's Control size. A select field is exactly as tall as a text field beside it at every size.

A select field whose options come from a named query fetches them again each time the form opens, rather than reusing a 30-second-old copy. Changed in 1.0.8

Fields, buttons and menus draw smaller after upgrading to 1.0.8

Before 1.0.8 these widgets had one size, what is now md (a 44 px field). The project's Control size defaults to sm (36 px), sized for desktop dashboards, and every widget whose size is Project default follows it — which is every widget in an upgraded project. On a touch panel, set Project settings → Theme → Control size to md or larger: 44 px is the touch-target minimum.

See also

• Named queries
• Event actions