Generic form

webapp/js/gen-form.js builds every create form, edit form, action form, and read-only record card of the web app from EntityMeta.form. webapp/js/form-drafts.js keeps unsaved input during a session, and webapp/js/customselect.js restyles every native select. This page lists the field controls, the metadata features the form honours, how values are collected, and how drafts work. The metadata classes are on metadata model.

Scope and source¶

• Defined in: webapp/js/gen-form.js (createGenForm, makeGenFormView, mountRecordForm, buildRecordCard), webapp/js/form-drafts.js, webapp/js/customselect.js (initCustomSelects)
• Count: 15 field types with a dedicated control, plus a plain text fallback (counted from the branches of controlHtml in webapp/js/gen-form.js:67-200); FieldMeta.field_type allows 19 values (src/cluster_erp/core/metadata.py:82-102)

Entry points¶

Field controls¶

Decimal input stays a string from field to request. This follows the money rule on money and Decimal. The quick-create + carries the tooltip Quick create (fk.create_tooltip).

Metadata features honoured¶

Validation and collection¶

validate() checks required fields in visible groups, including required sub-fields of container fields, and returns messages built from validation.field_required_named (webapp/js/gen-form.js:1696-1762). collect() skips hidden conditional groups and read-only fields, writes nested groups into their bucket, and never clears a loaded value whose option was not found (webapp/js/gen-form.js:1764-1794). commitFiles() uploads chosen files to POST /attachments/ and writes the returned ids before collect() runs (webapp/js/gen-form.js:1795-1812). The server validates again; see errors and exceptions.

Record card¶

mountRecordForm first shows a read-only card built by buildRecordCard (webapp/js/gen-form.js:2210-2308, webapp/js/gen-form.js:2440-2484). The card shows:

• contact quick actions for record_actions (call, message, mail) (webapp/js/gen-form.js:2058-2077, webapp/js/gen-form.js:2449-2450);
• the photo header when the entity declares photo (webapp/js/gen-form.js:2452-2460);
• the Documents row (docs.section) unless record_documents is false (webapp/js/gen-form.js:2477-2483);
• navigation bar entries: Share, Edit, and Actions when single_record actions apply (webapp/js/gen-form.js:2319-2361);
• metadata links (RecordLinkMeta) that apply to the record; a link raises cluster:open-section with parameters taken from the record (webapp/js/gen-form.js:2364-2385).

In edit mode the navigation bar shows Cancel and Save (webapp/js/gen-form.js:2318-2322).

Drafts of unsaved input¶

form-drafts.js keeps only the fields the user changed from the loaded baseline (webapp/js/gen-form.js:1255-1271, webapp/js/form-drafts.js:1-16).

When a draft is restored, fields that depend on another field are filled after their controlling field, so dependent pickers find their options (webapp/js/gen-form.js:1273-1290).

Custom selects¶

initCustomSelects() runs at boot and upgrades every current and future native select through a MutationObserver. The native element stays as the source of truth for value and change events. A search box appears from 8 options (webapp/js/customselect.js:1-17, webapp/js/customselect.js:229, webapp/js/main.js:229).

Constraints and validation¶

• The form never invents a status field. A status that changes only through actions is not on the form; a condition on it reads the loaded record (webapp/js/gen-form.js:703-707). See actions and action sheet.
• Browser tests: web-client/_e2e_form_draft.mjs, web-client/_e2e_form_draft_matrix.mjs, web-client/_e2e_ui_forms.mjs, web-client/_e2e_party_form_fixes.mjs.

Terms introduced¶

Related pages¶

• Web app platform
• Metadata rendering
• Generic detail
• Tenant fields
• Party unification

Verified against commit 92f8051 on 2026-11-13.