The form element
<datum-form> renders a definition, validates the answers and raises the submission. Attributes carry the declarative part, JS properties take objects and functions, events report what happened, and methods let the page's own controls drive the form.
<link rel="stylesheet" href="datum-form.css">
<script type="module" src="datum-form.js"></script>
<datum-form src="/forms/intake.json" locale="auto" draft="intake"></datum-form>The tables on this page are written from the element's own code, so they list every attribute and event the element has. The same list ships as attributes. in the repository's docs/ folder, for tools.
Attributes
Almost every attribute has a property of the same meaning, named under it where the spelling differs. The two exceptions are debug and allow-origins, which are attribute only: set them with set. An attribute takes text, so objects are written as JSON; the property takes the object itself.
| Attribute and property | What it does |
|---|---|
definition | One of definition or src is required. The property takes the object. Refused (datum-error, nothing replaced) while a src fetch is still loading: clear src first. Takes JSON of a form definition. Default none. |
src | Fetched on connect; a later change refetches, and a form an earlier src brought is replaced. Refused (datum-error, nothing fetched) while a definition the page assigned is in place: clear definition first. A response longer than max-definition-bytes is refused before it is parsed. Takes URL of a definition. Default none. |
max-definition-bytesmax | The longest definition read from src, in UTF-8 bytes, the cap every other import has; a longer one is reported as datum-error and not parsed. Anything but a whole number above 0 is reported and the cap stays. Takes whole number of bytes. Default 2097152 (2 MiB). |
mode | readonly keeps the answers as sent. Takes interactive | readonly. Default interactive. |
locale | The starting locale, negotiated against the form's supported locales; auto takes the visitor's browser languages. Switching later never resets an answer. Takes BCP 47 tag | auto. Default the form's default locale. |
language-switcherlanguage | Shows the locale switcher in the form's header. Takes boolean attribute. Default off. |
chrome | Header, footer and other parts a host merges over the definition's own. The language-switcher, frame and frame-fixed attributes still apply beside it, merged in; where both give the same setting (a frame, a language-switcher part), the chrome's wins. Takes JSON of the chrome parts. Default none. |
frame | A default the author's own pick beats, unless frame-fixed. Short for chrome.frame; with a chrome that names a frame, the chrome's frame is used instead. Takes seamless | outlined | paper | a frame the binding defines. Default the binding's own. |
frame-fixedframe | Makes frame beat the author's pick. Applies to the frame attribute, not to a frame the chrome names. Takes boolean attribute. Default off. |
heading-levelheading | The level of the form's top heading; headings the form draws itself sit one level under it. Takes 1 to 6. Default 1. |
debugattribute only | Logs journey diagnostics to the console. Takes boolean attribute. Default off. |
messages | Validation message templates by code. An entry wins over the message the definition authors for that code; codes it leaves out keep the definition's words. Takes JSON of message overrides. Default none. |
texts | The renderer's own strings (buttons, status lines). Takes JSON of UI text overrides. Default none. |
submitting-placementsubmitting | Where the Submitting status line shows. Listing both draws a visual echo at the bottom so the line is announced once. Any other word is reported as an error. Takes top, bottom, or both separated by spaces or commas. Default top. |
confirmation | Present: an accepted submit shows the form's own confirmation, a notice with the reference the delivery's reply carries, if it has one. It never replaces a receipt the page set itself with setNotice. Worded through texts keys confirmationTitle, confirmationMessage and confirmationReference (English built in). Read when a submit is accepted; changing it rebuilds nothing. Takes boolean attribute. Default off. |
error-summaryerror | Where the error summary shows after an invalid submit; none leaves only the inline messages. Any other word is reported as an error. Takes top, bottom, or both separated by spaces or commas; none. Default top. |
data-sourcesdata | The form paints first while its sources load. The property takes sources with functions. Takes JSON of a data source set. Default none. |
data-source-waitdata | all holds the form until every source has answered. Takes none | all. Default none. |
data-source-timeoutdata | 0 for no limit. Takes milliseconds. Default 15000. |
translations | The host's translations of the form's texts; an entry overrides the definition's own translation of the same address. Takes JSON of a translation catalog: locale, then kind (form, components, chrome, journeys, pdf), then the owner's id, then the property tree, with string leaves. Default none. |
values | Seeds the answers; setting later replaces them. Takes JSON of initial answers. Default none. |
host-contexthost | Facts about the visit the rules read, such as host.role. Plain JSON data only: a function, NaN or a Date is left out and reported as datum-error host-context.invalid. Changing it updates the form in place and keeps the answers typed so far. For display only: it is not sent with a submission, and a server judges host. rules with values of its own. Takes JSON object of the values host. names read. Default none. |
draft | A key: answers auto-save under it (the browser's storage unless draft-store or the draftStore property says otherwise) and restore on return. Takes storage key. Default none. |
draft-storedraft | Where the draft key's draft is kept. server:<url> (on the page's origin, or one allow-origins lists; relative URLs read against the page) speaks four requests, <id> being the draft key: PUT <url>/<id> saves the draft as JSON, GET <url>/<id> answers it (404 when there is none), DELETE <url>/<id> removes it (404 counts as removed), GET <url> lists the drafts. local is the browser's storage. Anything else is reported as datum-error. A server on another origin is reported as datum-error and drafts stay in the browser. A draftStore object assigned from script wins; it is the route for headers, credentials, another origin or another protocol. Does nothing without draft, and nothing when features leaves drafts out. Takes server:<url> | local. Default local (browser storage). |
features | Present means only the listed features exist; minimal is a single-page form that renders, validates and submits. The attributes and properties of a feature can only narrow a listed feature, never enable one the list omits. What the page or the definition asks of a left-out feature is ignored with one console warning, its methods reject, and its files (the PDF module, the sandbox, the WebAuthn code, the server validator) are never requested. A word with a minus in front takes that feature out: all -drafts is every feature but drafts, and so is -drafts alone, since a list of only exclusions starts from all; an exclusion wins wherever it stands. A word that names nothing (a mistyped exclusion included) is reported as datum-error and left out, and a list holding one never starts from all, so a typo can only narrow. agent is opt-in: not part of all; write all agent to add it (the agent tools a browser assistant can call through WebMCP, and agentTools() / executeAgentTool() for page script, from a lazy chunk). Changing it rebuilds the runtime, and the answers typed so far carry over; an agent-only change only registers or withdraws the agent tools. Takes space or comma list of journeys, print, translations, data-sources, drafts, server-validation, signing, pdf, wasm, agent; presets all, minimal; -name leaves one out. Default absent: every feature but agent. |
agent-accessagent | With the agent features token: the host enforces, the definition decides, or the host forbids. always: the host enforces, so the tools are registered whatever the definition says (the author's agentTools: off included). definition, the default: the definition decides, so root.configuration.agentTools allowed is live and off or absent is registered sealed (every call answers agent-off, except describe_form, which says the form is the person's to fill). never: the host forbids, so nothing is registered or loaded for this element. Without the token it does nothing. Changing it never rebuilds the form. Takes always | definition | never. Default absent: definition. |
pdf | auto fetches datum-pdf.js beside the bundle on the first PDF. A loaded module is the pdfSupport property; a template resolver is the pdfTemplates property. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent, unless allow-origins lists that origin; the property may name any. Takes auto | URL of the PDF module. Default unset (no PDFs). |
pdf-themepdf | The theme the PDF is drawn with when the render call and the layout name none; it outranks the binding's suggestion. Takes PDF theme id (default, or a registered id). Default unset: the PDF theme the form's binding suggests, else default. |
pdf-unknown-componentspdf | What a PDF does with a component it has no rendition for: ignore draws it generically and says nothing, warn does the same and reports component.unknown, fail rejects the PDF. Takes ignore | warn | fail. Default warn. |
formula-errorsformula | What a rule formula that cannot be read does: fail refuses the form, warn drops the rule and says so. Takes fail | warn. Default fail. |
risky-patternsrisky | Whether a regular expression that could run away is refused. Takes refuse | allow. Default refuse. |
wasm | auto fetches datum-wasm.js beside the bundle and runs the validation sandbox in the page, for development and testing. In production the server validates. A page that imported the module assigns wasmValidationHost; plugins and external data are properties. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent, unless allow-origins lists that origin; the property may name any. Takes auto | URL of the sandbox module. Default unset. |
wasm-log-levelwasm | How much the sandbox's run log keeps; the log arrives on datum-wasm-validated. Takes off | error | warn | info | debug. Default warn. |
wasm-timeoutwasm | How long the page waits for the sandbox module to load; 0 waits without limit. A module that never loads blocks the submit with an error. Takes milliseconds. Default 15000. |
signing-scopesigning | What a signed submission covers. Providers are the signingProvider(s) and pdfSigner properties (functions); the attribute sets the scope inside the signing property. Takes envelope | submission | values. Default envelope. |
signing-placementsigning | Where the signature sits in the delivered submission; the attribute sets the placement inside the signing property. Takes embedded | wrapper. Default embedded. |
sign-withsign | The id of the provider every submit signs with; no provider of that id refuses the submit (signing.providerMissing). Takes provider id. Default none. |
change-onchange | When a typed value counts as settled for datum-change: input reports after change-debounce ms of quiet or on leaving the field, commit only on leaving the field. Any other word is reported as an error. Takes input | commit. Default input. |
change-debouncechange | The quiet time for change-on input; 0 reports every write. Takes whole milliseconds. Default 300. |
journey | Which journey runs: an id, form for the whole form on one page, or journey for the definition's default journey. Changing it restarts the journey over the answers typed. On a definition that has journeys, form still loads the journeys runtime (the journey can be switched later without a rebuild), so a missing runtime file shows the error card even then. Takes journey id | form | journey. Default the definition decides. |
page | Opens the journey on that page when the person may reach it (a deep link, a resume point); nextPage and previousPage move it, and reading the property gives the page shown. Takes page id. Default the journey's first page. |
validate-urlvalidate | Where a journey's server check posts, as the { document, scope, pageId } delivery a Datum host's POST /api/submissions/validate takes; a serverValidator property wins over it and is the custom validator. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent, unless allow-origins lists that origin; the property may name any. Takes URL. Default none. |
validate-timeoutvalidate | How long a journey's server check may take before the service counts as unavailable. Read when the form is built: changing it rebuilds the runtime, and the answers typed so far carry over. Takes whole milliseconds; 0 for no limit. Default 10000. |
allow-originsattribute only | The other origins the wasm, pdf, draft-store and validate-url attributes may name. A word that names no origin (*, a bare host) is reported as datum-error and left out. Changing it applies an attribute it now allows and drops one it no longer does. Takes space-separated origins, each written as a URL (https://cdn.example). Default none: the page's own origin only. |
Properties without an attribute
Functions, registries and custom objects are set from script.
| Property | What it is |
|---|---|
plugins | Plugins for this form alone, beside those the page registered with plugins.register: FormPlugin objects whose components join the catalogue, whose validators run after the field constraints, and whose hooks, submission handlers, PDF renditions, sandbox modules and data sources the form takes up. A property only. Assigning rebuilds the form and keeps the answers typed so far. |
component | Component types beyond the standard catalogue, each drawn by its definition's adapter; a type with a standard one's name replaces it. Assigning rebuilds the form and keeps the answers typed so far. |
themesplugin | The registries the element resolves through: themes for the pdf-theme id, pluginRegistry for the page's plugins. Each is the page's shared one (the themes and plugins exports) unless a host hands the element its own. A plugin registered after the element connected is taken up: the form is rebuilt, and the answers typed so far stay. |
bindingassetscolor | The design-system binding the form is drawn by (a LiveBinding, or the id of one registered with bindings.register; Datum's when left out), the files that binding needs (stylesheets, fonts, scripts), and light or dark. |
datamessagestextsvalues | Object forms of the attributes of the same name; the property takes functions where the attribute cannot. |
signingpdfpdfsigning | Functions: a passkey provider, a hardware-token signer. |
serverdraftwasmwasmwasm | Custom objects behind validate-url, draft and wasm. |
pdfpdf | A loaded PDF module and a template resolver behind pdf. |
ready | Read-only promise: resolves after datum-ready for the current definition (at once when the form is ready already), rejects with the build error (the journeys runtime that did not arrive, a definition the runtime refused), is not rejected by a build a newer request replaced, and is a fresh promise after the next build or Retry. With no definition it settles once one is set and built. |
print takes the theme a printed form is drawn with; Datum's plain one applies when it is left out. See Print.
Events
Every event bubbles and is composed, so one listener on the page hears every form, even from inside another element's shadow tree. Listen on the form or on document. The event's data is in event..
| Event | When, and what detail carries |
|---|---|
datum-submit | An accepted submission; detail carries the answers, and detail.submissionKey the attempt's key, which the page sends beside the document ({ document, submissionKey }) and again unchanged when it retries the delivery. detail.trigger is "agent" when a browser assistant's submit tool started it, and detail.agent (an AgentProvenance) says which answers the assistant's tools wrote last; both are absent where the element's tools were never live: a form that has only ever been sealed adds none. |
datum-change | A settled value change. |
datum-validated | Validation finished. |
datum-error | A problem the page should know of: { code, message, cause? }. The code names the cause (definition.load, definition.too-large, sandbox.unavailable); the message is words to show. An unreadable definition, a sandbox that never loaded. |
datum-binding-error | The binding or its files failed: detail.hook says where (assets: a stylesheet or script of the design system could not be had, with detail.url, and an alert takes the form's place; binding: an id nobody registered; render, ready, focus and self-check: a hook of the binding), detail.message why. Bubbles and is composed. |
datum-form-action | A button was pressed whose action the element does not act on itself; the page hears it and decides. detail is { componentId, action, signature?, journey? }: the button's id, its configured action as written, its signature option. The element handles submit and download buttons, a journey's own Submit, and a pdf button while it can make a PDF (as datum-submit, datum-download and datum-pdf), and stops those; any other action, and a pdf button when no PDF module is set, reaches the page here. |
datum-download | Cancelable; an accepted submission saved as a file. |
datum-pdf | Cancelable; a PDF was made (the PDF button, downloadPdf() or a browser assistant's download_pdf tool); cancelling takes the file over, so the page sends it where it wants. detail.trigger is "agent" for the assistant's tool, and detail.agent is the AgentProvenance account, absent where the element's tools were never live: a form that has only ever been sealed adds none. |
datum-print | Cancelable; print() routed elsewhere if cancelled. |
datum-ready | The form is built and drawn; one microtask after the definition lands for a plain form, one chunk load later for the first journey form on a page. The ready promise settles with it. |
datum-page-change | The journey moved to another page. |
datum-locale-applied | A locale took effect; detail.locale is its code. |
datum-locale-rejected | The person picked a language in the form's own switcher that the form does not declare. detail is { locale, message }: the code picked and the runtime's reason. The switcher has been put back to the form's current language, and nothing else changes. |
datum-wasm-ready | The validation sandbox loaded. |
datum-wasm-validated | The sandbox finished a check. |
datum-agent-action | With the agent feature: a browser assistant's tool call finished. detail names the tool, its outcome and what it changed; see Assistants. |
datum-agent-session | With the agent feature: an assistant's session began, ended, was stopped or went idle; detail.phase says which. |
datum-agent-tools | With the agent feature: the tools were registered, sealed or withdrawn; detail.registered, detail.access and, when not registered, detail.reason say which. |
datum-warning | Something taken, but not whole: detail.code draft.dropped says restoreDraft() left out answers the form cannot hold (an object or a list in a single-valued field), with detail.count and detail.addresses (the first few); the rest is restored. |
Event details
Every event is bubbles and composed. Only datum-download, datum-pdf and datum-print are cancelable.
datum-submit
See Submissions and replies: accepted, submission, errors, result, signed, submission, trigger, agent and wait.
datum-change
| Key | Value |
|---|---|
path | The value path that was written, such as email or billing.. undefined when the event names none. |
value | What the path now holds. |
values | The form's answers as a whole, one entry per value path. Fields a journey page owns for itself are not in it. |
The event is not raised on every keystroke. See When a change is reported.
datum-validated
| Key | Value |
|---|---|
errors | The errors after validate() ran: a list of the entries below, empty when the form is valid. |
Each entry of errors is shaped like this. submit and set return the same entries.
| Key | Value |
|---|---|
id | An identifier of the entry, unique within the list. |
code | The error code, such as required. |
message | Text, when the stage that raised it supplied one. |
component | The component the error is on, when it is on one. |
path | Where the answer is stored, as { segments: [{ key, index? }] }, when the error is on a row or a nested answer. |
stage | The stage that raised it, such as host for an error the page set with set. |
severity | error (the default, blocks), warning or info. |
source | client, wasm, server or custom. |
parameters | Values the message names, such as { min: 3, count: 2 }. |
datum-ready
| Key | Value |
|---|---|
runtime | The engine's runtime object for the form just built. It is the engine's own surface and is not documented on this site: prefer the element's methods. |
datum-error
| Key | Value |
|---|---|
code | A stable name for the cause, such as definition. or sandbox.. Match on this. The codes page lists them. |
message | What went wrong, in words, for showing. It may be reworded between releases. |
cause | The thrown value, when there was one. |
source | Only for a data source that failed: its id. |
component | Only for a data source that failed: the component that names it. |
datum-warning
| Key | Value |
|---|---|
message | What was taken only in part. |
code | draft.: a restored draft held answers the form cannot hold, and the rest was restored. |
count | How many answers were dropped. |
addresses | The first few of them, as dotted paths. |
datum-page-change
| Key | Value |
|---|---|
journey, page | The journey and the page the person is now on. |
from | The page they left, or null when the journey has just started. |
direction | Why: forward (Continue), back, jump (a page already reached), change (a Change link on a Check answers step), error (the page holding an error after a blocked submit), start, resume (a draft restored) or redirect (the page asked for with page cannot be reached with these answers; page is where the person is instead). |
index, total | The page's place on the path as the answers draw it now, counting from 0, with every page on it. |
title | The page's heading in the form's language. |
kind | questions or exit. |
error | The blocking errors the page shows. |
datum-locale-applied and datum-locale-rejected
| Event | Key | Value |
|---|---|---|
datum-locale-applied | locale | The language that took effect, whether the locale attribute negotiated it or the switcher picked it. |
datum-locale-rejected | locale | The language the switcher offered that the form does not declare. The switcher has been put back to the form's current language. |
datum-locale-rejected | message | The reason, for a page that wants to show it. |
datum-download
Cancelable. Fires before the browser is handed the file of an accepted submission. Cancelling takes the file over, for example to upload it, and nothing is downloaded.
| Key | Value |
|---|---|
submission | The envelope, or the signed wrapper around it under the wrapper signing placement. |
file | The name the file would be saved as. |
json | The exact text the file would hold. |
datum-pdf
Cancelable. Fires before the browser is handed a PDF made by the PDF button, download or an assistant's tool. Cancelling takes the bytes over.
| Key | Value |
|---|---|
bytes | The PDF, as a Uint8. |
file | The name it would be saved as. |
layout | The layout that drew it. |
layout | condition when no layout was named and the first layout whose condition held was used. |
page | The number of pages. |
warnings | What the PDF kernel had to say, a list. |
signature | Present when the file was signed: what was signed. |
trigger, agent | As on datum-submit. |
datum-print
Cancelable. Fires before the print dialog opens. Cancelling takes the document over, for example to send it to a PDF service, and nothing is printed.
| Key | Value |
|---|---|
html | The complete document that would print. |
theme | The id of the print theme it is drawn with. |
fell | Present when the print theme asked for was set aside for the basic one: the reasons, a list of strings. |
datum-wasm-ready and datum-wasm-validated
| Event | Key | Value |
|---|---|---|
datum-wasm-ready | host | The loaded sandbox host. |
datum-wasm-validated | blocked | Whether the sandbox's verdict blocked the submit. |
duration | How long the run took. | |
unknown | The setting the run used for keys the form does not define: strip, keep or reject. | |
log | The level the run log kept, when one was set. | |
values, external | What the run was given. | |
outcome | The sandbox's answer, when it gave one. See Your own server. | |
execution | Why it gave none. | |
logs | The run log entries, for the page to forward to a console or a logger. |
datum-binding-error
| Key | Value |
|---|---|
hook | Where it failed: assets (a stylesheet or script of a design system did not load), binding (an id nobody registered), or one of the binding's own hooks such as render, ready, focus and self-check. |
message | Why. |
id | The field's instance key or component id, when one field's problem. |
url | The file, for assets. |
problems | A list of reasons, when the failure had several. |
datum-form-action
| Key | Value |
|---|---|
component | The button's component id. |
action | The button's configured action, as written. |
signature | The button's signature option, when it has one. |
A button with the action submit or download, and a journey's own Submit, is handled by the element, which raises datum-submit and datum-download, so the page does not hear it here. A pdf button reaches the page as datum-form-action only when the element has neither a pdf attribute nor a pdf property to serve it. The event is not a way to attach a button action of your own: the actions a button can have are submit, download and pdf.
When the form is ready
A form is built a moment after it gets its definition: a microtask after definition is assigned or src has loaded, and one chunk load later for the first journey form on a page, because journeys run from a file of their own. datum-ready is raised when the form is built and drawn, and form. is a promise for the same moment.
const form = document.querySelector("datum-form");
form.definition = definition;
await form.ready; // resolves once datum-ready has been raised
form.setLocale("fr");ready resolves once datum-ready has been dispatched for the build, and at once when the form is ready already. It rejects with the reason when a build fails: the journeys file did not arrive, or the runtime refused the definition. A build that a newer assignment replaces rejects nothing, and ready follows the form becoming ready rather than one build. After a failure the next build, by Retry or a new definition, gives a fresh promise. With no definition it settles once one is set and built. An unawaited rejection is not reported as an unhandled one. Every change that rebuilds the form raises datum-ready again; read ready again for the next one.
The methods that return a promise (validate, submit, submit, render, download, print, the draft methods, next, previous and go) wait for a build under way and then run. Two methods answer at once and cannot wait, so they throw while the form is building:
| Method | Before the form is built |
|---|---|
set | Throws "the form is still building; call this after datum-ready". |
set | The same. The locale is kept, and the form is built in it. |
Both also throw <datum-form> has no form yet when there is no definition at all. form. in one tick therefore throws: await ready between them. The locale attribute has no such limit; it applies when the form is built.
What keeps the answers and what starts afresh
Some settings are read when the form is built, so changing one builds the form again: data, translations, draft, draft, plugins (and a plugin registered on the page later), component, features, formula, risky, the signing properties, validate, data, and wasm or wasm when the sandbox appears or goes. A rebuild for the same form keeps what the person typed and the language they chose, and the next submit sends those answers. values assigned in the same change win over the typed answers. Errors already shown are cleared until the next check, and a journey goes back to the first page the person may open, with the answers kept. Each rebuild raises datum-ready again.
The other settings, such as messages, texts, locale, frame, chrome, mode and binding, take effect in place, without a rebuild. So does host: the rules that read host. are worked out again over the answers typed so far, and no datum-ready is raised.
Assigning definition, or a src that loads, starts the form afresh, even when it is the same object assigned again: the typed answers go, and values seeds the new form. Assigning is still a way to clear a form, but reset() is the plain one.
reset() takes the form back to how it first opened for its current definition. It clears what the person typed, the errors and notice on show, which fields were touched, and a journey's place. It applies the values the page assigned again. The language the person chose, the definition and every other setting stay. The form is built again, so datum-ready is raised again, and then one datum-change tells the page the answers are cleared: it has no path, and values holds the form's answers now. reset() resolves after that event. It does nothing on a form with no definition.
reset() does not touch a stored draft. It writes none and deletes none. The first change after it arms the autosave, which then saves the form as it stands, so the draft is replaced by the cleared form. To drop the draft too, call clear as well. See Drafts.
Setting errors and notices
set takes a list. Each entry:
| Key | Meaning |
|---|---|
code | Required. The error code, such as required or a code of your own. |
message | Text for the error. Its {name} slots are filled from parameters. |
component | The component the error is on. Without it, and without a path, the error belongs to the form as a whole and is listed in the summary only. |
path | A value path, such as items[1]. for a field in the second row of a data grid, or billing.. A path without an index names the answer's field, so the error is placed on the component stored there. A path with an index places it on that row. |
severity | error (the default, blocks), warning or info. A warning or note is shown and does not block. |
source | client, wasm, server or custom. Defaults to server. |
parameters | Values for the message's {name} slots, such as { max: 3 }. |
The errors replace those the form held, are shown on their fields and in the summary, move focus to the first, and are returned as the entries described under datum-validated (with stage: "host"). The next validate() or submit() replaces them, and set clears them. In a journey, an error the server reported stands through the page's own checks until its answer changes, and the person is moved to the first page that holds one.
set takes this object, or undefined to clear:
| Key | Meaning |
|---|---|
kind | success (the default), info, warning or error. An error is announced at once; the others are announced politely. |
placement | A list of "top" and "bottom": the ends of the form it is drawn at. Absent or empty means ["top"]. At both ends, the top copy is the one announced. |
title, message | Plain text, or { "default": "...", "locales": { "fr": "..." } } to follow the language. |
details | A list of { label, value }, such as { label: "Reference", value: "GC-48213" }. label can be worded per language; value is a plain string. |
data | The receipt as plain JSON, such as { "reference": "GC-48213" }. It is never drawn by itself: a printed header or footer reads it as {{receipt.reference}} (see Print). A notice with only data draws nothing. |
The notice is drawn where the error summary goes, takes focus, and is printed with the form. The next submit clears it. The notice property reads what was last set.
When a change is reported
datum-change reports a value once it has settled, not on every keystroke. Two attributes decide when:
| Attribute | Default | Meaning |
|---|---|---|
change-on | input | input: a typed value is reported after change-debounce milliseconds without another keystroke, or when the field is left, whichever comes first. commit: a typed value is reported only when the field is left. |
change-debounce | 300 | The quiet time for change-on="input", in whole milliseconds. 0 reports every write. |
A pick (a select, a checkbox, a radio) and a value the page writes are reported at once. A value still waiting is reported before datum-submit, so the answers a listener holds match what is submitted. Any other word for change-on is reported as datum-error.
The confirmation
The confirmation attribute is a boolean. With it present, an accepted submit shows a notice with the form's own words: "Your form was submitted", a message, and a line with the reference when the delivery's reply carries one. The rule for the reference, and when the notice does not appear, is under After acceptance. A notice the page set with set is never replaced by it, and a download never shows it. The three sentences are texts keys, listed on The form's own words.
Origins and size
Four attributes name a URL the page would load code from or send answers to: wasm, pdf, draft-store and validate-url. In markup they reach places a script does not, so each is held to the page's own origin. An attribute that names another origin is reported as datum-error and ignored, unless allow-origins lists that origin.
allow-origins is a space-separated list of origins, each written as a URL: allow-origins="https://cdn.. A path after the origin is ignored. A word that names no origin, such as *, a bare host or a data: URL, is reported as datum-error and left out. It is read as an attribute only: set it with set. Changing it applies an attribute it now allows and drops one it no longer does, so it can be set after the others.
The rule has these edges:
- The properties are not held to it. A script that sets
pdf,Support wasmorValidation Host draftalready runs on the page, and may name any origin.Store srcis not covered. It is fetched with a plainfetch, so the browser's CORS rules, the page'sconnect-srcand the server's headers decide whether another origin may serve a definition. The fetch carries no headers and no credentials. A definition behind a login is fetched by the page and assigned todefinition.srcanddefinitionare used one at a time. While asrcfetch is loading, an assigneddefinitionis refused, and while a definition is assigned,srcis refused. Both are reported asdatum-error, and nothing changes. Clear one before setting the other.
max-definition-bytes caps the size of a definition read from src, in UTF-8 bytes. The default is 2097152 (2 MiB). A response that declares a longer length is refused unread, a body is read only as far as the cap, and a longer one is reported as datum-error and not parsed. The value must be a whole number above 0, or it is reported and the cap stays. A definition the page assigns is not held to it.
Read-only properties
| Property | Holds |
|---|---|
ready | The promise described under When the form is ready. |
errors | The errors the form holds now, as under datum-validated. Empty before the form is built. |
notice | The notice last set with set. |
submitting | Whether a submit is in flight, from the submit until every wait promise has settled. Also reflected as the submitting attribute, for a stylesheet to use. |
active | The language the form is showing now: what locale negotiated to, or what the switcher picked. undefined before the form is built. |
renderer | The inner <datum-form-renderer> element. |
runtime | The engine's runtime object, the same one datum-ready hands out. It is the engine's own surface and is not documented on this site. |
Methods
| Method | Does |
|---|---|
validate({ focus }) | Runs every check, reports the errors as datum-validated and resolves with them. Focus moves to the first error unless focus is false. |
submit({ sign | Validates, locks the form and raises datum-submit. Resolves with the same detail the event carries. A second call while one is in flight joins it; a call that asks for something different, or one made from inside a datum-submit listener, rejects. |
submit | Submits and saves the submission as a JSON file in one step: the signed document when there is one, otherwise the submission. A rejected submit shows its errors and saves nothing. For a PDF, use download. |
set | Shows the server's errors (code, message, component, path, severity, parameters) on their fields and in the summary, and returns them as shown. set clears them. Throws until the form is built: see When the form is ready, and Setting errors and notices. |
set | Shows a notice with a kind, a title, a message and details, such as a confirmation number. set clears it, and so does the next submit. |
reset() | Clears the answers, errors, notice and journey position, and applies the values seed again. The language stays. Raises datum-ready and one datum-change, and resolves after them. A stored draft is left alone. See What keeps the answers and what starts afresh. |
set | Switches the form's language. Throws for a locale the form does not support, and until the form is built. See Languages. |
next, previous | Continue and Back on a journey, from the page's own controls. Each resolves with where the form went or, with ok: false, the reason it stayed. |
go | Opens a journey page the person has already reached, such as from a task list. Refused for a later page. |
journeys() | The journeys the definition declares, for a page that offers a choice. See Journeys. |
presentation | The answers to fields a journey page owns for itself, which are kept in drafts and never sent in a submission. |
has | Whether a draft is stored under the draft key. |
save | Saves the answers under the draft key now, without waiting for the autosave. Resolves with the saved draft's summary. |
restore | Restores the stored draft after checking it against the form. Rejects with a coded error when there is none or it does not fit. |
clear | Deletes the stored draft. See Drafts. |
pdf | The PDF layouts the definition declares, for a page that offers a choice. |
render | Draws the PDF from the current answers and resolves with its bytes. Loads the PDF kernel first when pdf names one. |
download | Draws the PDF and hands it to the person. See PDFs. |
print(options) | Opens the browser's print dialog with the form's print rendition. See Print. |
agent, execute | With the agent feature: the tools a browser assistant is offered, and one of them run from page script. See Browser assistants. |
The ready property is a promise that resolves once the current definition is built and drawn, and rejects with the reason when it could not be. See When the form is ready.