Skip to content

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.

html
<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 propertyWhat it does
definitionThe 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.
srcFetched 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-bytes
maxDefinitionBytes
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).
themeThe 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-fonts
loadFonts
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.
debug
attribute only
Logs journey diagnostics to the console.
Takes boolean attribute. Default off.
pdf-theme
pdfTheme
The theme the PDF preview is drawn with.
Takes PDF theme id. Default default.
layoutcontained fills its parent's box with % heights.
Takes page | contained. Default page.
localeThe locale the canvas and inspector resolve labels in.
Takes BCP 47 tag. Default the form's default locale.
data-sources
dataSources
Sources the Data workspace and canvas can use.
Takes JSON of a data source set. Default none.
data-source-ids
dataSourceIds
Ids the Data workspace offers when the sources themselves are not given.
Takes space or comma list of ids. Default none.
validation-codes
validationCodes
Server-side codes the Logic workspace can name.
Takes JSON list of host validation codes. Default none.
component-types
componentTypeFilter
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.
pdfDefault 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-pages
pdfPages
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.
journeysDefault ON. off removes the Journeys mode; the definition's journeys pass through untouched.
Takes auto | off. Default auto (on).
valuesSeeds Try it.
Takes JSON of sample answers. Default none.
translationsThe 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.
modeThe builder mode shown first; setMode() changes it.
Takes form | pdf | journeys. Default form.
persist-panels
persistPanels
Remembers which panels are open under this key.
Takes storage key. Default off.
file-actions
fileActions
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).
savePuts 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-method
saveMethod
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-label
saveLabel
Save's name in the ⋮ menu (Save draft, Publish), whichever Save it is; a fileActions.saveLabel wins.
Takes text. Default Save.
workspaceThe workspace shown first; setWorkspace() switches through the unsaved-edits guard.
Takes form | logic | data | languages | journeys | pdf | print. Default form.
hidden-workspaces
hiddenWorkspaces
Leaves workspaces off the bar. It does not remove their code.
Takes space or comma list of workspaces. Default none hidden.
hidden-panels
hiddenPanels
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-settings
managedSettings
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.
featuresPresent 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-window
fullWindow
Present: the builder covers the whole browser window; the bar's button toggles it.
Takes boolean attribute. Default off.
no-full-window
attribute only
Removes the bar's full-window control.
Takes boolean attribute. Default off.
schemeThe 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-toggle
attribute only
Removes Dark mode from the ⋮ menu; scheme still sets the look.
Takes boolean attribute. Default off.
wasmThe 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-origins
attribute 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-guard
attribute 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 ​

PropertyWhat it is
fileActions.saveThe Save callback and its label, for a save the save attribute cannot express; it wins over it.
pluginsPlugins 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.
componentTypesPalette 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.
componentDefinitionsComponent 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.
iconsThe 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.
themes
pluginRegistry
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.
binding
assets
The design-system binding the canvas draws the form with, and its files; the canvas's picker offers each binding registered with bindings.register.
formulaFunctions
formulaReferenceHref
Extra FEEL functions and the link their help opens.
textLocale
textCatalog
The builder's own UI language and its catalog.
pdfConfiguration
journeyConfiguration
Object forms of pdf and journeys.
serverChecksThe object behind wasm.

Saving ​

save with an address sends the form there, a bare save fires datum-builder-save, and fileActions.save 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.

  • workspace is the tab on the bar: form, logic, data, languages, journeys, pdf or print. It is the one to use. Set the attribute or property to start somewhere other than Form, call setWorkspace(id) to move, and listen to datum-builder-workspace-change (detail.workspace and detail.previous). A switch goes through the unsaved-edits guard, so setWorkspace() returns false for a workspace that is off or hidden, and true when the switch has started, which includes waiting for the question the guard asks.
  • mode is lower level: which document designer is on the canvas, form, pdf or journeys. 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.mode and detail.previous) and the mode field of datum-builder-change use it. modes lists the ones on offer, and showModeSwitch and hiddenModeIds are for pages that lay out their own switch, as the PDF designer does.

A page that wires both gets both events for one move. Set attributes before the element connects: a call to setWorkspace() straight after createElement has nothing to act on yet.

Remembering the layout ​

persist-panels="key" has the builder remember, in the browser's localStorage 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 localStorage is blocked, the layout is kept for the life of the page only.

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.answersFree, chrome.frame. One word is shorthand: answersFree means data.answersFree. To find a path, select a component, open Edit JSON on the inspector's ⋯ menu and read the key.

html
<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 pdfTemplates (on <datum-pdf-designer> too) to an object made by createPdfTemplateResolver, exported by datum-builder.js:

js
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 formulaFunctions 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 ​

PropertyWhat it is
savefalse, true or an address: the property behind the save attribute.
dirtyWhether 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.
savedDefinitionThe baseline dirty compares with. Setting it makes the form saved at that definition.
definitionThe form being edited, as authored so far.
controllerThe engine's builder controller behind the form's panels, for a page that needs the whole engine surface.
builderThe inner <datum-builder>.
componentTypeFilterThe property for component-types, which limits the palette. The different property componentTypes adds entries to it.
modes, mode, showModeSwitch, hiddenModeIdsSee Workspace or mode.
pdfMode, journeyMode, pdfConfiguration, journeyConfigurationThe designer sides and the objects behind pdf and journeys.
serverChecksThe 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.

EventWhen, and what detail carries
datum-builder-changeThe definition changed.
datum-builder-file-actionA 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-saveThe 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-changeThe workspace changed.
datum-builder-dirty-changeUnsaved changes began or ended.
datum-builder-mode-changeThe builder mode changed.
datum-builder-binding-changeThe canvas's binding changed: detail.bindingId.
datum-builder-full-window-changeFull window opened or closed.
datum-builder-scheme-changeThe 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-actionWith the agent feature: a browser assistant's tool call finished. detail names the tool, its outcome and what it changed; see Assistants.
datum-agent-sessionWith the agent feature: an assistant's session began, ended, was stopped or went idle; detail.phase says which.
datum-agent-toolsWith 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-changeA PDF layout was edited.
datum-pdf-layout-selectA PDF layout was selected.
datum-pdf-designer-readyThe PDF designer is ready.
datum-journey-changeA 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-selectA journey was selected.
datum-errorA 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-warningSomething 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:

FieldMeaning
definitionThe whole form as authored.
reasonWhy 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.
modeWhich side changed: form, pdf or journeys.
selectedComponentIdThe selected component on the form side, else undefined.
renamedOnly on the change that gave a component a new id: { from, to }, with dataPath (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.
renameSteppedOnly on the change an Undo or Redo of a rename made: { from, to, by }, with by undo or redo.
dataMovedOnly 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.
historyStepundo or redo on every change an Undo or Redo made, so you can tell a redone dataMoved from a new one.

A page that keeps anything keyed by answer path (drafts, tests, a catalogue) follows dataMoved 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 historyStep precisely so that each is applied once and in the direction the author went.

The other events ​

Eventdetail
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{ bindingId }, when the author picks a design system for the canvas in the View panel. datum is Datum's own.
datum-builder-full-window-change{ fullWindow }.
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{ layoutId, 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 { journeyId, from, to }.
datum-journey-select{ journeyId, 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.dropped or src.superseded.

datum-builder-save, for the Save a page asks for, is described in Saving forms.

Methods ​

MethodDoes
markSaved()Tells the builder the page has saved: the definition and its languages as they stand become the baseline, and dirty clears.
hasUnsavedChanges()Whether an edit is still open in a panel that a leave would lose. A changed definition is the dirty property.
requestLeave(run)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.
localeChangesSinceSave()The languages changed since the last save, for a page that keeps a translation catalog of its own.
markLocalesSaved()Makes the languages as they stand the baseline, after a save of the page's own. markSaved() does the same.
setWorkspace(id)Opens a workspace. Returns false for one that is off or hidden. See Workspace or mode.
setMode(id)Opens a document designer by its mode id. Returns false for one that is off or hidden.
featureEnabled(name)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.
openPalette()Opens the command palette, as Ctrl+K or Cmd+K does inside the builder. See Keyboard shortcuts.
registerCommands(source)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.
triedAnswers()The answers the author typed in Try it, by value path, without the page's values.
clearTriedAnswers()Empties them, as the Try panel's Clear answers does.
agentTools()With the agent feature: the builder's tools for a browser assistant. See Browser assistants.
executeAgentTool(name, input)Runs one of those tools and resolves with its result, a refusal included.

Exports ​

datum-builder.js also exports createPdfTemplateResolver, parseBuilderFeatures, normalizeBuilderFeatures, BUILDER_FEATURES and BUILDER_FEATURE_PRESETS, formDefinitionProblem (the check Open applies to a file, for a page that reads files itself), adoptBuilderHostControlStyles, BUILDER_THEMES and resolveBuilderTheme, BUILDER_WORKSPACES, and the element classes. The classic script datum-builder.iife.js exposes them on window.DatumBuilder.

MIT licence. Your forms, your data, your keys.