The builder element
<datum-form-builder> is the design surface. It edits one definition and returns it as JSON through the definition property, saves it to your server, or hands it to the person through its own file actions.
<link rel="stylesheet" href="datum-builder.css">
<script type="module" src="datum-builder.js"></script>
<datum-form-builder
src="/forms/intake.json"
save="/api/forms/intake"
layout="contained"
></datum-form-builder>src loads the form and save stores it at that address: Save appears in the ⋮ menu at the end of the bar, and on Ctrl/Cmd+S. No script is needed.
Attributes
| Attribute and property | What it does |
|---|---|
definition | The form being edited; reading returns it as authored. Refused (datum-error, nothing replaced) while a src fetch is still loading: clear src first. Takes JSON of a form definition. Default empty form. |
src | Fetched on connect; a later src replaces a form an earlier one brought. Refused (datum-error, nothing fetched) while a definition the page assigned, or one New or Open brought, is in place: clear definition first. While it loads, an assigned definition, New and Open are refused; a response that arrives after the author edited is not loaded over the edits (datum-warning src.superseded). 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 or the Open file action, in UTF-8 bytes, the cap every other import has; a longer one is refused before it is parsed. Anything but a whole number above 0 is reported and the cap stays. Takes whole number of bytes. Default 2097152 (2 MiB). |
theme | The builder's own look: an id the host registers, default (the built-in light look), or the built-in dark one, datum-dark, which counts as the dark scheme unless the author remembered a choice or the page sets scheme. Takes builder theme id. Default default. |
load-fontsload | Loads the builder's own fonts (Geist and Geist Mono) from beside the bundle. A binding's files come through the assets property. Takes boolean attribute. Default off. |
debugattribute only | Logs journey diagnostics to the console. Takes boolean attribute. Default off. |
pdf-themepdf | The theme the PDF preview is drawn with. Takes PDF theme id. Default default. |
layout | contained fills its parent's box with % heights. Takes page | contained. Default page. |
locale | The locale the canvas and inspector resolve labels in. Takes BCP 47 tag. Default the form's default locale. |
data-sourcesdata | Sources the Data workspace and canvas can use. Takes JSON of a data source set. Default none. |
data-source-idsdata | Ids the Data workspace offers when the sources themselves are not given. Takes space or comma list of ids. Default none. |
validation-codesvalidation | Server-side codes the Logic workspace can name. Takes JSON list of host validation codes. Default none. |
component-typescomponent | Restricts the palette. Exclusions win over inclusions. The componentTypes property is a different thing (custom types). Takes space or comma list of types; a leading - drops a type, a trailing * matches a prefix. Default every type. |
pdf | Default ON: the executor is fetched as a chunk of this bundle on the first preview. off removes the PDF mode and the PDF seed. A page-built executor is the pdfSupport property. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent (auto), unless allow-origins lists that origin; the property may name any. Takes auto | off | URL of the PDF module. Default auto (on). |
pdf-pagespdf | Where the page imagery for template areas loads from; off draws on blank sheets. 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 (auto), unless allow-origins lists that origin; the property may name any. Takes auto | off | URL. Default auto. |
journeys | Default ON. off removes the Journeys mode; the definition's journeys pass through untouched. Takes auto | off. Default auto (on). |
values | Seeds Try it. Takes JSON of sample answers. Default none. |
translations | The host's catalog: the previews use it, and the Languages workspace shows the texts it overrides read-only. The form's own translations are the definition's translations map, edited in the Languages workspace. 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. |
mode | The builder mode shown first; setMode() changes it. Takes form | pdf | journeys. Default form. |
persist-panelspersist | Remembers which panels are open under this key. Takes storage key. Default off. |
file-actionsfile | Which of the builder's own file actions show. Save is not one of them: save or the fileActions property turns it on, whatever this names. Takes auto | none | off | space or comma list of new, open, download. Default all three (none on the PDF designer unless named). |
save | Puts Save in the ⋮ menu and on Ctrl/Cmd+S. Choosing it asks about an edit still in the inspector, then fires datum-builder-save with the definition. Bare, it sends nothing: the page stores the form in a listener and hands the work to detail.waitUntil(promise), so the item reads Saving… until it settles and a rejection's message shows beside the menu. With an address (save="/api/forms/x"), the builder also sends the form there itself: the definition as JSON (content-type application/json) by save-method, any 2xx answer counting as saved, anything else, an unreachable server or 30 seconds without an answer shown beside the menu as the reason it was not saved; detail.waitUntil(promise) has the request wait on the page's own work, and preventDefault() leaves the request out. Relative URLs read against the page. The address is 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. Once it succeeds the form as sent is the saved one (dirty clears). A request that needs headers of its own, credentials on another origin or a revision check is a bare save with a listener, or the fileActions.save function; a fileActions.save function wins over this attribute. The property is false, true (bare) or the address. Takes boolean attribute | URL. Default off. |
save-methodsave | The request an address in save is sent by. Any other word is reported as datum-error and the method stays. Takes PUT | POST. Default PUT. |
save-labelsave | Save's name in the ⋮ menu (Save draft, Publish), whichever Save it is; a fileActions.saveLabel wins. Takes text. Default Save. |
workspace | The workspace shown first; setWorkspace() switches through the unsaved-edits guard. Takes form | logic | data | languages | journeys | pdf | print. Default form. |
hidden-workspaceshidden | Leaves workspaces off the bar. It does not remove their code. Takes space or comma list of workspaces. Default none hidden. |
hidden-panelshidden | Leaves strip panels off, as hidden-workspaces does workspaces; works with or without features, which it can only restrict. A hidden panel is never loaded and never the open one, remembered or not: the workspace's own opens instead. Takes space or comma list of panel ids: form, chrome, components, outline, variables, tests, view, settings. Default none hidden. |
managed-settingsmanaged | Settings the host owns: the inspector shows Managed by the site. in place of each box and never touches the stored value. Takes space or comma list of inspector property paths, or answersFree for data.answersFree. Default none managed. |
features | Present means only the listed parts exist, besides the Form workspace with its canvas, inspector and component palette; minimal is that alone, so minimal logic is the form plus Logic. The list is the master: pdf, journeys, hidden-workspaces, hidden-panels, component-types and file-actions can only take more away, and a pdf or journeys that asks for a side the list omits is ignored with one console warning, as is a workspace for one (the form opens). translations is the pointer line under a component's texts, which says how much of it each language has and opens the Languages workspace on it, tests the Tests panel, print the Print workspace (the form's print settings beside a preview of the printed form, a lazy chunk), json the JSON view and editor, binding-picker the binding picker (the binding property still sets the binding), advanced-fields the inspector's component id and data key. agent is opt-in: not part of all; write all agent to add it (the agent tools over the builder, a lazy chunk: twenty-four tools besides the session pair). A part that is left out fetches none of its chunks. A word with a minus in front takes that part out: all -pdf is every part but the PDF side, and so is -pdf 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. Changing it after connect rebuilds the sides, workspaces, strip, bar and inspector, except an agent-only change, which only registers or withdraws the agent tools. On datum-pdf-designer the pdf side is always in. Takes space or comma list of logic, data, languages, translations, journeys, pdf, print, variables, header-footer, data-model, palette, try-it, tests, json, binding-picker, advanced-fields, agent; presets all, minimal; -name leaves one out. Default absent: every feature but agent. |
full-windowfull | Present: the builder covers the whole browser window; the bar's button toggles it. Takes boolean attribute. Default off. |
no-full-windowattribute only | Removes the bar's full-window control. Takes boolean attribute. Default off. |
scheme | The builder's own colour scheme: dark applies the studio look's dark palette to the shell, every panel and every workspace surface (Logic, Data, Languages, the overviews, the command palette), as theme="datum-dark" does. The ⋮ menu's Dark mode switch changes it and remembers the choice under localStorage; an attribute set by the page wins over the memory. While dark, the form on the canvas is drawn in Datum's dark look, or under the dark variant of the design-system binding it is drawn with where that binding names one; a binding that names none stays a light form on a white sheet. Takes light | dark. Default light, or the scheme the author last chose from the ⋮ menu on this origin. |
no-scheme-toggleattribute only | Removes Dark mode from the ⋮ menu; scheme still sets the look. Takes boolean attribute. Default off. |
wasm | The sandbox Try it validates with; nothing is fetched until the author turns the validator on in Try it. A serverChecks property wins over it. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent (auto), unless allow-origins lists that origin; the property may name any. Takes auto | off | URL of the sandbox module. Default auto. |
allow-originsattribute only | The other origins the wasm, pdf, pdf-pages and save 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. |
leave-guardattribute only | Leaving the page with unsaved work (a reload, a link, a closed tab) has the browser ask first, in its own words: the form differs from the saved one, or an edit is still held in a panel. off leaves that to a page that keeps the work some other way. Read when the page is about to go, so it can change at any time. Takes on | off. Default on. |
Properties without an attribute
| Property | What it is |
|---|---|
file | The Save callback and its label, for a save the save attribute cannot express; it wins over it. |
plugins | Plugins for this builder alone, beside those the page registered with plugins.register: their components join the catalogue and, through the palette entry each declares, the palette; their data sources reach the canvas and the picker; their validators, hooks, handlers, renditions and sandbox modules reach the previews. A property only. Assigning reseeds the builder. |
component | Palette entries for component types of your own, appended to the standard palette: a list of { type, label, icon?, group? }. A later entry with the same type replaces an earlier one's label and group. A type needs a definition too (componentDefinitions or a plugin) to draw; without an entry here or a plugin's own palette entry it draws but is not on the palette. The component-types attribute (componentTypeFilter) then narrows the whole palette. |
component | Component types beyond the standard catalogue (a type with a standard one's name replaces it). A type is offered on the palette only when an entry exists for it, from componentTypes or a plugin's palette entry. |
icons | The icon set the builder's chrome draws with. Unset, the set the page registered with setDefaultIconSet, else Datum's own drawings. Setting it repaints in place. |
themesplugin | The registries the builder resolves through: themes for the theme and pdf-theme ids, pluginRegistry for the page's plugins. Each is the page's shared one unless a host hands the element its own. A theme or plugin registered after the element connected is taken up without reseeding the form. |
bindingassets | The design-system binding the canvas draws the form with, and its files; the canvas's picker offers each binding registered with bindings.register. |
formulaformula | Extra FEEL functions and the link their help opens. |
texttext | The builder's own UI language and its catalog. |
pdfjourney | Object forms of pdf and journeys. |
server | The object behind wasm. |
Saving
save with an address sends the form there, a bare save fires datum-builder-save, and file takes a function. Saving forms chooses between them and covers dirty, the leave guard and language changes.
Workspace or mode
The builder has two ways of saying where the author is, and one of them is enough.
workspaceis the tab on the bar:form,logic,data,languages,journeys,pdforprint. It is the one to use. Set the attribute or property to start somewhere other than Form, callsetto move, and listen toWorkspace(id) datum-builder-workspace-change(detail.andworkspace detail.). A switch goes through the unsaved-edits guard, soprevious setreturnsWorkspace() falsefor a workspace that is off or hidden, andtruewhen the switch has started, which includes waiting for the question the guard asks.modeis lower level: which document designer is on the canvas,form,pdforjourneys. Journeys and PDF are both a workspace and a mode, but opening the workspace shows its list of journeys or layouts with the form still the mode, and the mode changes only when one of them is opened.datum-builder-mode-change(detail.andmode detail.) and theprevious modefield ofdatum-builder-changeuse it.modeslists the ones on offer, andshowandMode Switch hiddenare for pages that lay out their own switch, as the PDF designer does.Mode Ids
A page that wires both gets both events for one move. Set attributes before the element connects: a call to set straight after create has nothing to act on yet.
Remembering the layout
persist-panels="key" has the builder remember, in the browser's local under that key, which strip panel is open, the widths of the side column and the inspector, whether the inspector is folded, and the workspace, and put them back the next time a builder with the same key opens. An attribute with no value uses the key default. Things to know:
- Only Form, Logic, Data, Languages and Print come back as the workspace. Journeys and PDF never do, so a
workspace="pdf"still opens on the remembered workspace when one is stored. - The store belongs to the origin, so two builders on one origin with one key share a layout. Give each its own key.
- Where
localis blocked, the layout is kept for the life of the page only.Storage
Settings the page owns
managed-settings lists inspector settings the page keeps for itself. For each one the inspector shows "Managed by the site." in place of the box and never changes the stored value, and the JSON editor refuses text that would change it. A setting is named by its property path in the component's configuration, as it appears in the JSON of the component: required, label, data., chrome.. One word is shorthand: answers means data.. To find a path, select a component, open Edit JSON on the inspector's ⋯ menu and read the key.
<datum-form-builder managed-settings="required data.answersFree"></datum-form-builder>Offering your own PDFs
An uploaded PDF template is kept inside the definition as base64. A host that keeps its PDFs in a store gives the builder a resolver instead, and the layout then carries only a storage kind and a reference, never the bytes. Set pdf (on <datum-pdf-designer> too) to an object made by create, exported by datum-builder.:
import { createPdfTemplateResolver } from "./datum-builder.js";
builder.pdfTemplates = createPdfTemplateResolver(
{
// How each storage kind turns a reference into bytes.
assets: async (source) => new Uint8Array(await (await fetch(`/pdf/${source.ref}`)).arrayBuffer())
},
{
// The PDFs the designer offers beside Upload.
templates: [
{ id: "permit", label: "Permit application", source: { storage: "assets", name: "permit.pdf", type: "application/pdf", size: 98304, ref: "permit-v3" } }
],
// ICC profiles offered as PDF/A output conditions.
profiles: []
}
);The first argument maps a storage kind to a function from a template source to its bytes; the kind base64 is always understood. templates and profiles are lists, or functions that return a promise of one, and both are optional. A source is { storage, name, type, size } with data (base64) for an embedded file or ref for one the host finds. The same resolver turns a layout's source into bytes whenever the PDF is drawn.
Formula functions
Functions that plugins contribute to the formula language are listed in the Logic editor, the inspector, the form settings and the Variables panel, and a call to one is evaluated on the canvas and in Try it, with no further wiring: the builder reads them from the plugins on the page and on the element. Set formula only to hand it a different source: the plugin platform's formula function registry, or any object with table() (rows to list), signatures() (names and argument counts, so formulas parse) and optionally functions() (the evaluators, by name). A source without functions() lists and parses the names, and a call to one works out to nothing while authoring.
More properties
| Property | What it is |
|---|---|
save | false, true or an address: the property behind the save attribute. |
dirty | Whether the form differs from the saved one, drafts held in a panel included. It is also reflected as a dirty attribute on the element, so a Save button can be styled from CSS. |
saved | The baseline dirty compares with. Setting it makes the form saved at that definition. |
definition | The form being edited, as authored so far. |
controller | The engine's builder controller behind the form's panels, for a page that needs the whole engine surface. |
builder | The inner <datum-builder>. |
component | The property for component-types, which limits the palette. The different property component adds entries to it. |
modes, mode, show, hidden | See Workspace or mode. |
pdf, journey, pdf, journey | The designer sides and the objects behind pdf and journeys. |
server | The object behind wasm. |
These attributes have no property of their own: debug, no-full-window, no-scheme-toggle, allow-origins and leave-guard.
Hosting the builder
The builder is a page component like the form. Give it layout="contained" inside your own shell, or page to take the viewport. A host that keeps definitions gives the builder a Save (see Saving forms); the Spring Boot and FastAPI hosts have write endpoints for it, off by default. The builder's own strings can be translated for a workspace in another language.
Which workspaces and panels show, the builder's own look, its command palette and its languages are covered in Customising the builder.
Events
Every event bubbles and crosses shadow boundaries.
| Event | When, and what detail carries |
|---|---|
datum-builder-change | The definition changed. |
datum-builder-file-action | A New, Open, Download or Save action was taken. detail.trigger is "agent" when a browser assistant's save tool asked for the Save, so a host's save can tell who asked. |
datum-builder-save | The Save the save attribute turned on was chosen (cancelable). detail.definition is the form to store, detail.localeChanges the languages changed since the last save, detail.trigger "agent" when a browser assistant asked; detail.waitUntil(promise) has the save wait on the page's work and fail with its rejection, and preventDefault() leaves out the request to the address in save. Not fired for a fileActions.save function. |
datum-builder-workspace-change | The workspace changed. |
datum-builder-dirty-change | Unsaved changes began or ended. |
datum-builder-mode-change | The builder mode changed. |
datum-builder-binding-change | The canvas's binding changed: detail.bindingId. |
datum-builder-full-window-change | Full window opened or closed. |
datum-builder-scheme-change | The builder's colour scheme changed once the builder was up, from the Dark mode switch in the ⋮ menu or a change to the scheme attribute: detail.scheme is light or dark. The scheme attribute follows a change made from the menu. Choosing a theme (theme="datum-dark") does not raise it. |
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-pdf-layout-change | A PDF layout was edited. |
datum-pdf-layout-select | A PDF layout was selected. |
datum-pdf-designer-ready | The PDF designer is ready. |
datum-journey-change | A journey was edited. A page or journey given another id reports reason page-rename or journey-rename with renamed ({ journeyId, from, to }); the form's tests follow it by themselves, so a host forwards nothing. |
datum-journey-select | A journey was selected. |
datum-error | A problem the page should know of: { code, message, cause? }, the code naming the cause (definition.invalid, definition.too-large, attribute.origin-refused). A definition refused (unreadable, too large, or arriving while another source is loading), an attribute refused (another origin). |
datum-warning | Something taken, but not whole: detail.code translations.dropped says a loaded form's unusable translation entries were left out, with detail.count and detail.addresses (the first few); Save writes the rest. detail.code src.superseded says a src response arrived after the author edited and was not loaded over the edits. |
datum-builder-change
Fires after every change to the form, and when the selection moves. A keystroke typed into the inspector is not a change until Apply. detail:
| Field | Meaning |
|---|---|
definition | The whole form as authored. |
reason | Why it changed. On the form: init (the form was loaded or replaced, by definition, src, New or Open), add, move, remove, edit, select (only the selection moved). On the PDF side: layouts and template, with the form's own reasons. On the Journeys side: journeys, form-rename, page-rename and journey-rename. A change that only restyled the canvas is not announced. |
mode | Which side changed: form, pdf or journeys. |
selected | The selected component on the form side, else undefined. |
renamed | Only on the change that gave a component a new id: { from, to }, with data (where its answers moved to, [] standing for a repeating section's entries), rules (ids of the components whose rules were rewritten) and unparsed (formulas that spell the old id but do not parse, left as written). Journeys follow the rename in a form-rename change of their own. |
rename | Only on the change an Undo or Redo of a rename made: { from, to, by }, with by undo or redo. |
data | Only on a change that moved where answers are stored (a data key, a container's key, a container that stops or starts nesting data): a list of { from, to } value paths. Undo announces the moves reversed and Redo the same moves again. |
history | undo or redo on every change an Undo or Redo made, so you can tell a redone data from a new one. |
A page that keeps anything keyed by answer path (drafts, tests, a catalogue) follows data as one map, so two keys swapped stay swapped, and applies each change's map exactly once, as it is told. Undo and Redo send theirs with history precisely so that each is applied once and in the direction the author went.
The other events
| Event | detail |
|---|---|
datum-builder-file-action | { action, name?, definition, trigger?, warnings? }. action is new, open, download or save; definition is the form after it; warnings is on a Download that left something to say (no-submit-button: the form has no Submit button). |
datum-builder-workspace-change | { workspace, previous }. |
datum-builder-mode-change | { mode, previous }. |
datum-builder-dirty-change | { dirty }, when the form starts or stops differing from the saved one. |
datum-builder-binding-change | { binding, when the author picks a design system for the canvas in the View panel. datum is Datum's own. |
datum-builder-full-window-change | { full. |
datum-builder-scheme-change | { scheme }, light or dark, when the author switches Dark mode in the menu. |
datum-pdf-layout-change | { layout, pdf, definition, reason }: the layout edited, the layouts block and the form to save. |
datum-pdf-layout-select | { layout. |
datum-pdf-designer-ready | { layout }: a layout is up. |
datum-journey-change | { journey?, configuration, definition, reason, renamed? }: the journey concerned, the journey block as it stands, and for page-rename and journey-rename renamed as { journey. |
datum-journey-select | { journey. |
datum-error | { code, message, cause? }: a form refused, an attribute refused, a file that did not load. code names the cause; the codes page lists them. |
datum-warning | { message, code, count?, addresses? }: something taken but not whole, such as translations. or src.. |
datum-builder-save, for the Save a page asks for, is described in Saving forms.
Methods
| Method | Does |
|---|---|
mark | Tells the builder the page has saved: the definition and its languages as they stand become the baseline, and dirty clears. |
has | Whether an edit is still open in a panel that a leave would lose. A changed definition is the dirty property. |
request | Runs run at once when nothing is open, otherwise after the person answers the builder's Save or Discard question. Call it before swapping the builder out. |
locale | The languages changed since the last save, for a page that keeps a translation catalog of its own. |
mark | Makes the languages as they stand the baseline, after a save of the page's own. mark does the same. |
set | Opens a workspace. Returns false for one that is off or hidden. See Workspace or mode. |
set | Opens a document designer by its mode id. Returns false for one that is off or hidden. |
feature | Whether a part named in features is on, such as pdf or tests. |
undo(), redo() | Undo and redo on the side the author is looking at. |
open | Opens the command palette, as Ctrl+K or Cmd+K does inside the builder. See Keyboard shortcuts. |
register | Adds the page's own commands to the palette, such as Publish. source is { commands() } and is read each time the palette opens. Returns a function that removes them. |
tried | The answers the author typed in Try it, by value path, without the page's values. |
clear | Empties them, as the Try panel's Clear answers does. |
agent | With the agent feature: the builder's tools for a browser assistant. See Browser assistants. |
execute | Runs one of those tools and resolves with its result, a refusal included. |
Exports
datum-builder. also exports create, parse, normalize, BUILDER_ and BUILDER_, form (the check Open applies to a file, for a page that reads files itself), adopt, BUILDER_ and resolve, BUILDER_, and the element classes. The classic script datum-builder. exposes them on window..