Saving forms
The builder has no Save until the page asks for one, because it has nowhere of its own to keep a form. There are four ways to ask. Pick the first row that describes your server.
| Your server | Use | Covered in |
|---|---|---|
Takes the whole form at one address, by a plain PUT or POST | save="/api/ | An address |
| Needs headers, a CSRF token or a request of your own | A bare save, and a datum-builder-save listener that hands its work to wait | A request of your own |
| Checks a revision, or you decide what counts as saved | file, and saved | A function |
| Is a Datum host (Spring Boot or FastAPI) | The host's page glue, Datum | A Datum host |
Every route puts Save in the builder's ⋮ menu and on Ctrl/Cmd+S inside the builder. The builder first asks about an edit still open in the inspector, so what is saved is what the author sees. It shows "Saving…" while the save is pending and shows the reason beside the menu if it fails. save-label names the item ("Save draft", "Publish") and a file wins over it.
An address
<datum-form-builder src="/forms/intake.json" save="/api/forms/intake"></datum-form-builder>save with an address has the builder send the definition itself, as JSON with content-type: application/, by PUT. save-method="POST" sends a POST instead. Any 2xx answer counts as saved. Any other answer, a server out of reach, or 30 seconds without an answer shows beside the menu as the reason the form was not saved, and the form stays unsaved.
A relative address reads against the page. The address in the attribute is held to the page's own origin: one on another origin is reported as datum-error and the attribute is treated as absent, unless allow-origins lists that origin. The save property is a script's own choice and may name any address.
The first example on Embedding the builder saves this way: edit, choose Save, and the log shows the PUT. A page that needs more than this plain request does not use an address. It uses one of the routes below.
The save property takes the same three states as the attribute: false for no Save, true for a bare save, or an address.
A request of your own
A bare save adds the menu item and sends nothing. Choosing it fires datum-builder-save, and the page stores the form in a listener. Hand the work to wait so the builder shows "Saving…" until it settles and shows the reason if it rejects:
<datum-form-builder id="builder" save save-label="Save draft"></datum-form-builder>
<script type="module">
document.getElementById("builder").addEventListener("datum-builder-save", (event) => {
event.detail.waitUntil(
fetch("/api/forms/intake", {
method: "PUT",
headers: { "content-type": "application/json", "x-csrf-token": csrfToken },
body: JSON.stringify(event.detail.definition)
}).then((response) => {
if (!response.ok) throw new Error(`the server answered ${response.status}`);
})
);
});
</script>The event is cancelable and its detail carries:
| Field | Meaning |
|---|---|
definition | The form as authored: what this save stores, and the saved baseline once it succeeds. |
locale | The net change to the form's languages since it was loaded or last saved. See Language changes. |
trigger | "agent" when a browser assistant asked for the save, absent when the person did. |
wait | Has the save wait for a promise. Call it while the event is being dispatched; any number of listeners may each hand one in. A rejection is the save failing. |
Once every promise has settled and none rejected, the builder takes the form as sent for the saved one, so dirty clears, and it stays set for an edit made while the save ran.
The event also fires with save="/url", before the request. A listener there can do its own work first with wait, or call prevent to leave the request out and do the storing itself.
A function
builder. takes a function, which wins over the attribute in either form. Use it when the page keeps its own idea of what is saved, such as a revision the server checks:
builder.fileActions = {
async save({ localeChanges }) {
const definition = builder.definition;
const response = await fetch("/api/forms/intake", {
method: "PUT",
headers: { "content-type": "application/json", "if-match": revision },
body: JSON.stringify(definition)
});
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. An edit made meanwhile stays unsaved.
builder.savedDefinition = definition;
},
saveLabel: "Save"
};The function is called after the builder's own question about an open edit. A thrown error or a rejected promise is the reason the builder shows beside the menu. The function fires no datum-builder-save, and it leaves the saved baseline to you: set saved to the form you sent, not to whatever the builder holds when the answer arrives, or an edit made during the save would be counted saved. The second live example on Embedding the builder does this against a server that refuses a stale revision.
A Datum host
A page served by a Spring Boot or FastAPI host (see Server hosts) does not write any of this. Datum in the host's datum-host. wires the builder to the host's form routes:
- It loads the author's copy of the form from
{apiand remembers the hash of the version it loaded, taken from theBase}/ forms/ {form Key}/ definition?public=false ETag. - Its Save sends the definition by
PUTto{apiwithBase}/ forms/ {form Key} If-Matchset to that hash, the host's CSRF token, and anX-Datum-Locale-Changesheader when languages changed. Requests go one at a time. A form that does not exist yet starts fromseed, and its first save is aPOSTto{api.Base}/ forms - On success it takes the new hash from the answer, says "Saved." on the
statuselement if you gave one, and firesdatum-host-savedon the builder with{ sha256 }. - On a 409 (
form.) somebody else saved first: nothing is overwritten, the message shows on the bar and inoutdated status, anddatum-host-outdatedfires so the page can offer a reload. A 422 lists the server's reasons, and 413, 503 and other answers are worded by status. - It refuses to save a form whose id is not
form, and it turns saving off when the builder refused the definition it was given, so a blank form never replaces the stored one.Key - It sets
filefor Save, Download, and, with aActions seed, New and Open, all keyed to this form's id, and has the browser ask before the page is left with unsaved work.
It resolves with { save, sha256, dispose }: save() saves as the menu does, sha256() is the hash the page builds on, and dispose() removes the listeners. A host needs datum. for the routes to exist.
Knowing what is unsaved
<datum-form-builder> treats the definition it loads as saved. Four members tell a page where it stands:
| Member | What it is |
|---|---|
dirty | Whether the form differs from the saved one, drafts held in a panel included. It is also a dirty attribute, so a Save button can be styled from CSS, and datum-builder-dirty-change fires when it flips. |
saved | The baseline dirty compares with. Setting it makes the form saved at that definition. |
mark | Tells the builder the page has saved: the definition and its languages as they stand become the baseline, and dirty clears. Use it after a save of your own, such as a button on the bar. |
has | Whether an edit is still open in a panel that a leave would lose. It is not "the form differs from the saved one": that is dirty. |
A page that saves from a control of its own, in the toolbar slot say, calls builder. first, so an edit still open in the inspector is settled, and then mark once the server has the form.
Leaving the page
A reload, a followed link or a closed tab would take unsaved work with it. While the form is dirty, or an edit is still open in a panel, the builder has the browser ask before the page goes. The question is the browser's own and its words cannot be changed. leave-guard="off" turns it off for a page that keeps the work some other way, such as autosave. It is read when the page is about to go, so it can change at any time.
A page that swaps the builder out without leaving, as a single-page app does on a route change, is not a page the browser is leaving. Call builder. there. It runs run at once when nothing is open, and otherwise after the person answers the builder's Save or Discard question.
Language changes
A form's languages are part of its definition, so a save that sends the definition sends them. A page that also keeps a catalogue of translations of its own needs to know which languages were removed or renamed since the last save. The builder reports them as locale, { removed, renamed }, to file, in detail. of datum-builder-save, and from builder. for a host that saves some other way. Languages describes what each means.
The count is reset when a save succeeds: the function resolving does it, as does a save by the save attribute. After a save of your own, call mark or mark. A failed save leaves the count as it was, so a retry sends the same changes again. Loading another form resets it too.