Getting started
This page is the shortest path from a definition to a form on a page that delivers its answers: one runnable page with a script tag, and the same form wired from a module. Start here, then follow the links for each topic.
Both ways use the same files, which you serve yourself. Files you host says how to get the folder and what is in it. The first way needs no build step at all.
With a script tag
Load the stylesheet and the module, place the element, and hand it the definition the builder saved. The locale, the draft key and the PDF layer are attributes. Nothing is compiled on the page.
<link rel="stylesheet" href="datum-form.css">
<script type="module" src="datum-form.js"></script>
<datum-form id="intake"
src="/forms/intake.json"
language-switcher
confirmation
draft="intake"
pdf="auto">
</datum-form>
<script type="module">
const form = document.getElementById("intake");
form.addEventListener("datum-submit", ({ detail }) => {
if (!detail.accepted) return; // the form shows its own errors
detail.waitUntil(deliver(detail));
});
// Resolves with the server's reply, so `confirmation` can show its reference.
async function deliver(detail) {
const res = await fetch("/api/submissions", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ document: detail.signed ?? detail.submission,
submissionKey: detail.submissionKey })
});
const reply = await res.json();
if (res.status === 422) { // { errors: [{ field, code, message }] }
form.setErrors(reply.errors.map((e) => ({
componentId: e.field, code: e.code, message: e.message })));
} else if (!res.ok) {
throw new Error("The server answered " + res.status);
}
return reply;
}
</script>When the person submits, the element validates, locks the form and raises datum-submit with the canonical envelope. detail. is the signed wrapper when the form signs the submission (see Signing) and is absent otherwise, so the page delivers detail.. The page delivers it wherever it likes. The form shows its own confirmation, with the reference the server's reply carries, or the server's errors on the right fields. Submissions and replies describes the event, the replies and the retry key.
The sandbox and the PDF kernel are separate files the element fetches only when the form asks for them, so the first paint carries only the renderer.
As a module
Importing the module defines the element and exports the API behind it, which types/ lists (see TypeScript). An application built with a bundler, or with plain ES modules, wires the form from code instead of attributes: the definition as the object the builder saved, the binding, the colour scheme, the locale, and data sources as plain lists.
import "./datum-form.js"; // defines <datum-form>
import definition from "./forms/intake.json" with { type: "json" };
const form = document.createElement("datum-form");
form.definition = definition; // the object the builder saved
form.colorScheme = "dark";
form.locale = "fr-CA";
form.dataSources = {
provinces: [{ value: "ON", label: "Ontario" }, { value: "QC", label: "Québec" }]
};
// The organisation's chrome, once, for every form this application serves.
form.chrome = {
header: [
{ type: "image", src: "/brand/logo.svg", alt: "Example Org" },
{ type: "heading", text: "Example Org" },
{ type: "form-title" },
{ type: "language-switcher" }
],
footer: [{ type: "text", text: {
default: "Privacy · Accessibility",
locales: { "fr-CA": "Confidentialité · Accessibilité" } } }],
frame: { id: "paper", fixed: true } // fixed: this frame wins over the author's pick
};
form.addEventListener("datum-change", ({ detail }) => {
autosave(detail.values); // settled values, not every keystroke
});
document.getElementById("send").addEventListener("click", async () => {
const { accepted, submission } = await form.submit();
if (accepted) await deliver(submission); // otherwise the form shows its own errors
});
document.getElementById("intake-slot").append(form);The application's own controls drive the element. It hears settled values through datum-change, asks for validate() or submit() from any button, and reads the verdict from what they return.
Getting a definition
Open the builder (the live example on that page is one you can use now), design the form, and use Download in its file menu. The file is the definition: put it where the page can fetch it and point src at it, or hand the parsed object to the definition property. Publishing a form follows the file from there to a hosted page, and says how a definition on another origin or over 2 MiB is treated.
Download warns when the form has no submitting button. Add one, a button with the action submit, or the form cannot be sent.
Frameworks
Any. A React, Vue, Angular or Svelte page uses the elements as it uses any custom element: attributes for the declarative part, properties for objects and functions, events for what comes back. React, Vue and Angular has a component for each, and its TypeScript section says how to use the typings in types/.