Embedding the builder
<datum-form-builder> is the whole builder as one element: the palette, the canvas, the inspector and the workspaces beside them. An application places it in its own shell, hands it a form and stores what comes back.
The whole page
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Form builder</title>
<link rel="stylesheet" href="/datum/datum-builder.css">
<script type="module" src="/datum/datum-builder.js"></script>
</head>
<body>
<datum-form-builder
id="builder"
layout="contained"
style="height: 640px"
src="/forms/customer-intake.json"
save="/api/forms/customer-intake"
>
</datum-form-builder>
<script type="module">
const builder = document.getElementById("builder");
// The data sources the rendering page will supply: the canvas previews their options and
// the inspector's Data source picker lists their ids.
builder.dataSources = {
countries: [
{ value: "CA", label: "Canada" },
{ value: "US", label: "United States" },
{ value: "MX", label: "Mexico" }
]
};
// Every edit reports the whole form as authored so far.
builder.addEventListener("datum-builder-change", ({ detail }) => {
console.log(detail.reason, detail.definition.id);
});
// New, Open, Download and Save are reported once they are done.
builder.addEventListener("datum-builder-file-action", ({ detail }) => {
console.log(detail.action, detail.name);
});
</script>
</body>
</html>/forms//api/ are answered by the example.Nothing yet.
The builder needs room. Measured on the builder's own width, under 900 pixels the side panels become drawers, and under 768 it takes a phone layout with a bar along its bottom holding the palette, the outline and the rest. So on a wide window the result runs past the text column. Press Expand for the builder at the full width of the window.
Sizing it
layout="contained" keeps the builder's bar and rails inside the box the page gives it, so the page sets a height. layout="page" takes the viewport instead, for a page that is only the builder. Under a header of the application's own, set --db-shell-top to the header's height so the builder starts below it.
Handing it a form
src fetches a definition, and the definition property takes the object. With neither, the builder opens on an empty form.
data takes the same sources the rendering page will supply. The builder never stores them: the canvas previews their options and the inspector offers their ids.
New, Open and Download
The bar leads with the builder's own file actions, over the whole definition as a JSON file. Each asks before it replaces unsaved work and is reported as datum-builder-file-action once it is done. file-actions picks which show: a list such as "open download", or "off" for none. The file property takes the page's own function for any of them.
The page's controls on the bar
A control with slot="toolbar" rides the builder's bar, drawn in the builder's look. Mark the main one with data-builder-primary for the accent. The other places on the bar are listed in Customising the builder.
Hearing every edit
datum-builder-change fires on every edit with the whole form in detail., ready to store or to hand straight to a <datum-form> on the same page for a live preview. The builder emits what the form takes, so one line sits between them.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Form builder with a live preview</title>
<link rel="stylesheet" href="/datum/datum-builder.css">
<script type="module" src="/datum/datum-builder.js"></script>
</head>
<body>
<datum-form-builder
id="builder"
layout="contained"
style="height: 640px"
src="/forms/customer-intake.json"
>
</datum-form-builder>
<datum-form id="preview"></datum-form>
<script type="module">
const builder = document.getElementById("builder");
const preview = document.getElementById("preview");
// The same data sources on both: the canvas previews them, and the form renders them.
const dataSources = {
countries: [
{ value: "CA", label: "Canada" },
{ value: "US", label: "United States" },
{ value: "MX", label: "Mexico" }
]
};
builder.dataSources = dataSources;
preview.dataSources = dataSources;
// What the builder emits is what the form takes: no conversion in between.
builder.addEventListener("datum-builder-change", ({ detail }) => {
preview.definition = detail.definition;
});
</script>
</body>
</html>/forms//api/ are answered by the example.Nothing yet.
Edit a component in the builder and the form under it follows. In the column the builder takes its small-screen layout, so press Expand to work in it at the full width of the window, then close it to see the form.
Saving
The first example saves with one attribute, save="/api/. Make an edit and the builder shows "Changes not saved" on its bar. Choose Save from the ⋮ menu, or press Ctrl/Cmd+S in the builder, and the log shows the PUT the builder sent. A 2xx answer clears the cue; use Server reply to Save to see a refusal or an unreachable server, which show beside the menu as the reason the form was not saved.
That is the simplest of several ways. Saving forms chooses between them, and covers what the builder does when the person leaves with unsaved work.
A server that checks the revision
A page that keeps its forms on a server usually needs a request the attributes cannot make, such as one that carries the revision the form was loaded at. For that, hand the builder a function: builder. puts Save in the ⋮ menu and on Ctrl/Cmd+S, and the builder asks about an open edit, shows "Saving…" while the promise is pending and shows the message of a rejection beside the menu.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Form builder</title>
<link rel="stylesheet" href="/datum/datum-builder.css">
<script type="module" src="/datum/datum-builder.js"></script>
</head>
<body>
<datum-form-builder id="builder" layout="contained" style="height: 640px"></datum-form-builder>
<script type="module">
const builder = document.getElementById("builder");
const FORM_URL = "/api/forms/customer-intake";
builder.dataSources = {
countries: [
{ value: "CA", label: "Canada" },
{ value: "US", label: "United States" },
{ value: "MX", label: "Mexico" }
]
};
// The revision the form was loaded at. Every save sends it back as If-Match, so a save from
// a page that fell behind another author's is refused with 409, not laid over theirs.
const loaded = await fetch(FORM_URL).then((response) => response.json());
let revision = loaded.revision;
// The definition the builder is handed is its saved one: builder.dirty stays false, and the
// builder shows no "Changes not saved" cue, until the author changes something.
builder.definition = loaded.definition;
async function save() {
// What this save sends: an edit made while it runs stays unsaved.
const definition = builder.definition;
let response;
try {
response = await fetch(FORM_URL, {
method: "PUT",
headers: { "content-type": "application/json", "if-match": String(revision) },
body: JSON.stringify(definition)
});
} catch {
throw new Error("the server could not be reached");
}
// A thrown error is the reason the builder shows beside its menu.
if (response.status === 409) throw new Error("someone else saved this form first");
if (!response.ok) throw new Error("the server answered " + response.status);
revision = (await response.json()).revision;
// The form as sent is the saved one now, so the cue clears. An edit made meanwhile stays unsaved.
builder.savedDefinition = definition;
}
// Save in the builder's ⋮ menu, and Ctrl/Cmd+S inside the builder. The builder asks about
// an edit still open in the inspector first, and shows "Saving…" while the promise is pending.
builder.fileActions = { save, saveLabel: "Save" };
</script>
</body>
</html>/forms//api/ are answered by the example.Nothing yet.
Make an edit and the builder shows "Changes not saved" on its bar. Choose Save from the ⋮ menu, or press Ctrl/Cmd+S in the builder, and the log shows the PUT with its If-Match revision and the cue clears. The function sets saved to the form it sent, not to whatever the builder holds when the answer arrives, so an edit made during the save stays unsaved. Turn on Someone else saves first and save again: the server has moved on, the PUT is refused with 409 and the page throws, which is what shows beside the menu.
Next
- Which workspaces, panels and component types show, and the builder's look: Customising the builder.
- A builder with only the parts you list: Leaving parts out.
- Every attribute, property, event and method: The builder element.