Customising the builder
A host that embeds <datum-form-builder> in its own application decides what the author sees: where the builder opens, which settings the host owns, how the builder looks, and what the page adds to it. Everything here is set on the element or from the page's script. Taking parts away is on Leaving parts out. Loading, sizing, methods, events and saving are on The builder element.
Where the builder opens
Which parts exist, which workspaces and panels show, and which component types the palette offers are set with features and its narrower switches. Leaving parts out maps each goal to the one setting that does it. This section is only about where the builder opens.
The builder has six workspaces: form, logic, data, languages, journeys and pdf. Use workspace to say which one opens first, and set to move to another from the page. A workspace the author remembered under persist-panels wins over the attribute, and a workspace that features leaves out is refused: the form opens instead.
mode is the same choice at a lower level: the three designers (form, pdf and journeys), where workspace="pdf" and mode="pdf" open the same place. It is kept for hosts that already use it. A move to PDF or Journeys can raise datum-builder-mode-change as well as datum-builder-workspace-change, so a host that listens should listen to the workspace event alone.
<datum-form-builder
features="minimal logic languages"
workspace="logic"
hidden-panels="chrome tests"
component-types="text,select,-acme-*"
></datum-form-builder>Settings the host owns
managed-settings takes a list of inspector property paths, separated by spaces or commas. For each one the inspector shows "Managed by the site." in place of the control and never changes the stored value, and the component's JSON editor refuses text that would change it. Use it for a setting your application fixes itself.
<datum-form-builder managed-settings="required data.answersFree agentTools"></datum-form-builder>A path is the setting's key in the component's configuration for a component, such as required, label or description, or its key in the root configuration for a form-wide setting, such as chrome. or messages. answers is short for data.. agent locks the form's choice about assistant tools. To find another path, open the component's JSON and read the key.
Full window
full-window makes the builder cover the whole browser window, and the bar's button toggles it. no-full-window removes that button. The builder fires datum-builder-full-window-change when it opens or closes.
Look and dark scheme
| Attribute | Takes | Notes |
|---|---|---|
theme | default, datum-dark, or a registered id | The builder's own look. An unknown id keeps the built-in look and raises datum-error. |
scheme | light, dark | The colour scheme. Left out, the one the author last chose on this origin applies. |
no-scheme-toggle | boolean | Removes Dark mode from the ⋮ menu. scheme still sets the look. |
load-fonts | boolean | Loads the builder's own faces, Geist and Geist Mono, from beside the bundle. Without it the builder uses the system face. |
persist-panels | storage key | Remembers the open panel, the column widths, whether the inspector is folded and the workspace (Form, Logic, Data, Languages or Print; Journeys and PDF are never put back), under that key in the browser's local storage, or for this page load alone when storage is blocked. An empty attribute uses the key default. Builders on one origin that share a key share their layout. |
layout | page, contained | contained fills the element's box; set --db-shell-top to the height of a header that stays above a page builder. |
A host registers its own builder theme before the element connects, then names it:
import { builderThemes } from "./datum-builder.js";
builderThemes.register({
id: "acme",
version: "1.0.0",
target: "builder",
tokens: {
"db-accent": "#0b5fff",
"db-accent-hover": "#0a4fd6",
"db-accent-ink": "#ffffff",
"db-accent-text": "#0a4fd6",
"db-accent-soft": "#e3ecff"
}
});<datum-form-builder theme="acme"></datum-form-builder>A page that loads datum-builder. as a classic script has no import: everything the module exports is on window., so the call is Datum, and an icon set is set with Datum.
tokens maps builder token names (db-surface, with or without the leading --) to values. Tokens a theme leaves out keep the built-in look. extends names a theme already registered, such as datum-dark, to build on instead.
Seven tokens are the contract, and stay across versions: the accent set db-accent, db-accent-hover, db-accent-ink (text and icons on the accent), db-accent-text (the accent as text), db-accent-soft (selected rows and badges), and the two faces db-font and db-font-mono. A theme that sets the accent should set all five, as above, or hover and selected rows keep the built-in blue. The other colour, type, radius and elevation tokens can be set too, but they may change between versions. The sizes of the layout (the bar height, the widths of the rail and drawers, the gaps) belong to the builder: do not set them.
The command palette
Ctrl+K (Cmd+K on a Mac) inside the builder, or the search button on its bar, opens a list of every command: workspaces, components to add or go to, edits on the selection, documents and views. open opens it from the page. register adds the page's own commands, read each time the palette opens, and returns a function that takes them out.
const off = builder.registerCommands({
commands: () => [{
id: "acme:publish",
label: "Publish to production",
group: "host",
keywords: ["release"],
shortcut: "Ctrl+Shift+P",
enabled: () => builder.dirty === false,
run: () => publish(builder.definition)
}]
});A command has an id, a label, a group, optional keywords that the search matches beside the label, an optional shortcut, an optional enabled function and a run function. The shortcut is shown beside the command and is never bound: bind the key yourself. enabled returns false to grey the command and skip it. The palette's own groups are workspaces, add, go to, edit, documents and view, so a command from the page belongs to host.
Driving the builder from the page
The methods are listed on The builder element: set, set, undo(), redo(), has, request, mark and the rest. Two notes belong here. has is true only while an edit is held outside the form, such as an inspector change not yet applied; the dirty property is the one that reports whether the definition differs from the saved one, so gate a Save button or a navigation on dirty. And set attributes such as workspace before the element connects: a method called straight after create has nothing to act on.
Slots
The bar has toolbar-start, toolbar and canvas-actions places for the page's own controls, drawn in the builder's look. Mark the main action with data-builder-primary for the accent pill. It also has history, comments, publish and account places, each drawn only when filled.
<datum-form-builder src="/forms/intake.json">
<button slot="toolbar-start">Preview on site</button>
<button slot="publish" data-builder-primary>Publish</button>
</datum-form-builder>A panel of your own
The activity strip down the side takes a button in the strip slot and the panel it opens in the panel slot. Give both the same data-panel id, or the button opens nothing. Add data-workspace="data" to the button to show it in that workspace only.
<datum-form-builder src="/forms/intake.json">
<button slot="strip" data-panel="acme-help" data-workspace="form">Help</button>
<section slot="panel" data-panel="acme-help">
<h2>Acme help</h2>
<p>Our field naming rules.</p>
</section>
</datum-form-builder>Icons
The builder draws its icons through an icon set. The icons property takes one for this builder, and set sets it for the page. A set that leaves a name out gets the builder's own drawing for it.
The builder's own icons are strokes drawn without a library behind them. datum-icons-fontawesome. is a bundle that registers Font Awesome Free's solid glyphs as the page's icon set. Load it before datum-builder., since the builder reads the set when it draws. The bundle also exports the set as FONT_, for a page that gives it to one builder with builder.. Switch the example to the builder's own icons to see what changes.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Form builder</title>
<link rel="stylesheet" href="/datum/datum-builder.css">
<!-- The icons bundle goes before the builder's. It registers Font Awesome Free's solid glyphs as the page's icon set. -->
<script type="module" src="/datum/datum-icons-fontawesome.js"></script>
<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>
<script type="module">
import { FONT_AWESOME_ICONS } from "/datum/datum-icons-fontawesome.js";
const builder = document.getElementById("builder");
// The icons bundle has registered the set for the whole page, so this line is not needed
// here. It gives the set to one builder, which is how a page uses a set it did not register.
builder.icons = FONT_AWESOME_ICONS;
builder.dataSources = {
countries: [
{ value: "CA", label: "Canada" },
{ value: "US", label: "United States" },
{ value: "MX", label: "Mexico" }
]
};
</script>
</body>
</html>Nothing yet.
A set of your own is one object with an id and an icon(name, { size, class function that returns markup for a name, or nothing for a name it has no drawing for. svg builds one from SVG glyph data, and markup from any markup, such as an icon font's class or a sprite's <use>. The names are listed in DATUM_. The example below draws a few of them itself and leaves the rest to the builder. A library such as Lucide or Material Symbols plugs in the same way, with one glyph per name taken from the library's own data.
<!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"
>
</datum-form-builder>
<script type="module">
// The bundle exports what a set is built from.
import { svgIconSet } from "/datum/datum-builder.js";
// A glyph is the markup inside an <svg> and the grid it was drawn on.
const glyph = (body) => ({ viewBox: "0 0 24 24", body });
// A real library plugs in the same way: each of its icons becomes a glyph under the builder's
// name for it. Any name left out is drawn with the builder's own icon.
const mine = svgIconSet(
"mine",
{
undo: glyph(`<path d="M9 14 4 9l5-5"/><path d="M4 9h10a6 6 0 0 1 0 12h-3"/>`),
redo: glyph(`<path d="m15 14 5-5-5-5"/><path d="M20 9H10a6 6 0 0 0 0 12h3"/>`),
"show-hidden": glyph(`<path d="M2 12s4-7 10-7 10 7 10 7-4 7-10 7S2 12 2 12z"/><circle cx="12" cy="12" r="3"/>`),
"hide-hidden": glyph(`<path d="M2 12s4-7 10-7 10 7 10 7-4 7-10 7S2 12 2 12z"/><path d="M4 4l16 16"/>`),
"drag-handle": glyph(`<circle cx="9" cy="6" r="1.5" fill="currentColor"/><circle cx="15" cy="6" r="1.5" fill="currentColor"/><circle cx="9" cy="12" r="1.5" fill="currentColor"/><circle cx="15" cy="12" r="1.5" fill="currentColor"/><circle cx="9" cy="18" r="1.5" fill="currentColor"/><circle cx="15" cy="18" r="1.5" fill="currentColor"/>`),
"components-panel": glyph(`<rect x="4" y="4" width="7" height="7"/><rect x="13" y="4" width="7" height="7"/><rect x="4" y="13" width="7" height="7"/><rect x="13" y="13" width="7" height="7"/>`),
"properties-panel": glyph(`<path d="M4 7h16M4 17h16"/><circle cx="9" cy="7" r="2.5" fill="var(--db-surface, #fff)"/><circle cx="15" cy="17" r="2.5" fill="var(--db-surface, #fff)"/>`),
"outline-panel": glyph(`<path d="M4 6h3M10 6h10M7 12h3M13 12h7M7 18h3M13 18h7"/>`),
"document-menu": glyph(`<circle cx="5" cy="12" r="1.5" fill="currentColor"/><circle cx="12" cy="12" r="1.5" fill="currentColor"/><circle cx="19" cy="12" r="1.5" fill="currentColor"/>`),
"new-form": glyph(`<path d="M14 3H6v18h12V7z"/><path d="M12 11v6M9 14h6"/>`),
"open-form": glyph(`<path d="M3 7h6l2 2h10v10H3z"/>`),
"download-form": glyph(`<path d="M12 4v11M7 11l5 5 5-5M5 20h14"/>`),
"field-text": glyph(`<path d="M5 6h14M12 6v13"/>`),
"field-number": glyph(`<path d="M9 4 7 20M17 4l-2 16M4 9h16M3 15h16"/>`),
"field-checkbox": glyph(`<rect x="4" y="4" width="16" height="16" rx="3"/><path d="m8 12 3 3 5-6"/>`),
"field-select": glyph(`<rect x="3" y="6" width="18" height="12" rx="2"/><path d="m9 11 3 3 3-3"/>`),
"field-date": glyph(`<rect x="4" y="5" width="16" height="15" rx="2"/><path d="M4 10h16M9 3v4M15 3v4"/>`),
"action-button": glyph(`<rect x="3" y="8" width="18" height="8" rx="4"/>`)
},
// Attributes for every glyph's <svg>: here a thick stroke that takes the control's colour.
{ attrs: 'fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"' }
);
const builder = document.getElementById("builder");
builder.icons = mine;
builder.dataSources = {
countries: [
{ value: "CA", label: "Canada" },
{ value: "US", label: "United States" },
{ value: "MX", label: "Mexico" }
]
};
</script>
</body>
</html>Nothing yet.
Both pages draw the whole builder, so press Expand to see the palette and the bar at their full size.
Events
The events are listed on The builder element. A host that enables a Save button from its own state listens to datum-builder-dirty-change and reads dirty:
builder.addEventListener("datum-builder-dirty-change", () => {
saveButton.disabled = !builder.dirty;
});