Skip to content

Ways to configure ​

This page is a map. Use it when you know what you want to change and not which setting does it: it says what the seven ways of configuring the form and the builder are, and lists each task with the page that covers it.

A page that hosts a form or the builder decides a good deal about it: what it loads, how it looks, what it says, where the answers go and which parts exist at all. None of that needs a build of Datum. It is all set from the page, through seven mechanisms.

The seven mechanisms ​

MechanismWhat it carriesExample
AttributesThe declarative part: text, numbers, on/off, and objects written as JSONlocale="fr-CA", draft="intake", features="minimal"
PropertiesObjects and functions, set from scriptform.dataSources = {…}, builder.fileActions = {…}
EventsWhat happened, for the page to act ondatum-submit, datum-builder-change
MethodsThe page's own controls driving the elementform.setErrors(…), builder.setWorkspace("logic")
SlotsThe page's own controls inside the builder's bar<button slot="toolbar">Save</button>
RegistriesAdditions every element on the page takes upplugins.register(…), bindings.register(…)
The definitionChoices the form's author made in the builder, saved with the formMessages, chrome, frame, translations

Almost every attribute has a property of the same meaning, so most of what is written in HTML can be set from script instead. The exceptions are attribute only: on the builder save, debug, leave-guard, allow-origins, no-full-window and no-scheme-toggle, and on the form debug and allow-origins. A script-driven host sets those with setAttribute. The reverse does not hold: a function has no attribute. The full lists are in the reference: the form element and the builder element.

html
<datum-form id="intake" src="/forms/intake.json" locale="auto" draft="intake"></datum-form>

<script type="module">
  const form = document.getElementById("intake");
  form.dataSources = { countries: () => fetch("/api/countries").then((r) => r.json()) };
  form.addEventListener("datum-submit", ({ detail }) => { /* deliver detail.submission */ });
</script>

The page or the author ​

Several settings can be made twice: once by the author in the builder, saved in the definition, and once by the page that hosts the form. Each has a rule for which one wins.

SettingWho winsTo change that
Validation messagesThe page's. An entry in messages beats the form's own message for that code; the codes it leaves out keep the author's words.Leave a code out of messages to keep the author's. See Languages.
FrameThe author's pick. The page's frame is the default.frame-fixed makes the page's win.
Header and footerBoth. The page's chrome parts are merged over the form's own.See Look and chrome.
TranslationsThe page's. An entry in translations overrides the form's own for the same text.See Languages.
FeaturesThe page's list is the limit. The form can only use what the list allows.See Leaving parts out.

In the builder, managed-settings takes a setting out of the author's hands altogether: the inspector shows "Managed by the site." in its place. See Customising the builder.

Find the page for a task ​

The form ​

ToUseCovered in
Put a form on a page and take its submissionsrc, datum-submit, setErrors, setNoticeThe form on your page
Deliver to a slow server, time out and retrywaitUntil, texts, submissionKeySubmissions and replies
Set the language, or let the person switchlocale, language-switcherLanguages
Fill a select from your own datadataSourcesData model and data sources
Word the validation messages and the form's own textmessages, texts, translationsLanguages
Add a logo, a title and a footerchrome, frameLook and chrome
Draw the form with your design systembinding, assetsDesign-system bindings
Draw it with Bootstrap and your own CSSbinding, assets.stylesheetsBootstrap with your own CSS
Use it in a React, Vue or Angular applicationProperties, eventsReact, Vue and Angular
Show it on another siteAn <iframe> and postMessageIn an iframe
Keep a half-filled formdraft, draft-storeDrafts
Run a form as several pagesjourney, pageJourneys
Check an answer in a way the form's settings cannotvalidWhen, wasm, wasmPluginsValidation and the sandbox
Offer the answers as a PDFpdf, pdf-themePDFs
Sign the submission or the PDFsign-with, pdfSignerSigning
Ship lessfeaturesLeaving parts out

The builder ​

ToUseCovered in
Put the builder in your applicationlayout, src, the toolbar slotEmbedding the builder
Save the form to your serversave, fileActionsSaving forms
Take parts, workspaces, panels or component types awayfeatures, hidden-panels, component-typesLeaving parts out
Choose where it opens, add a panel, a command or a slotworkspace, strip, registerCommands()Customising the builder
Give it your colours, or a dark schemetheme, schemeCustomising the builder
Add a component type of your ownplugins.register, componentDefinitionsComponents of your own
Change its iconsicons, setDefaultIconSetCustomising the builder
Translate its interfacetextLocale, textCatalogLanguages

The server ​

What the server accepts, how it validates and what it renders are set on the server host, not on the page: see Server hosts. For a server of your own, Your own server has the protocol and four worked examples with the endpoint in Python, Java, C# and Node.js.

Live examples ​

The pages in this section carry live examples: the whole page a reader would write, with choices that rewrite it, and that page running under the code. Live examples lists them all.

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