Components of your own
The standard types cover most forms. When one does not, a page adds a type of its own: a row of stars, a postcode lookup, a map pin. The form draws it, and the builder offers it on the palette and edits it like any standard type.
A type is one object, a component definition. The page's script holds all of it, so the example below is the whole page.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Customer survey</title>
<link rel="stylesheet" href="/datum/datum-form.css">
<script type="module" src="/datum/datum-form.js"></script>
</head>
<body>
<datum-form id="survey" src="/forms/customer-survey.json"></datum-form>
<script type="module">
// The bundle exports what a component type is built from, and the page's plugin registry.
import { plugins, standardFieldCapabilities } from "/datum/datum-form.js";
// A component type the bundle does not know: a row of stars, stored as a number.
const rating = {
type: "star-rating",
version: "1.0.0",
// The standard type it reads as, so the definition can be validated without this code.
base: "number",
// What lands on the canvas when the type is picked from the palette.
createDefault: () => ({ id: "rating", type: "star-rating", configuration: { label: "Rating", max: 5 } }),
// The inspector fields every field type shares (label, required, hidden, CSS classes)...
capabilities: standardFieldCapabilities({ placeholder: false, description: false }),
// ...and one of its own.
propertyEditor: {
mode: "extend",
fields: [{ id: "max", type: "number", propertyPath: "max", label: "Stars", min: 1, max: 10 }]
},
// How it draws, on the form and on the builder's canvas. It is handed the renderer's own
// lit, so the page loads none, and answers the field with the number of the star pressed.
adapter: ({ html }) => ({
kind: "field",
template: (state, on) => {
const max = Number(state.model.node.configuration.max) || 5;
const stars = Array.from({ length: max }, (_, index) =>
html`<button type="button" class=${index < Number(state.answer) ? "star-rating__star is-on" : "star-rating__star"} aria-label=${`${index + 1} of ${max}`} @click=${() => on.input(index + 1)}>★</button>`
);
return html`<div class="star-rating" role="group" aria-labelledby=${state.labelId}>
<span class="star-rating__label" id=${state.labelId}>${state.label}</span>
<span class="star-rating__stars">${stars}</span>
</div>`;
}
}),
// Its own rules, adopted into the form after the design system's.
css: [
".star-rating__stars { display: inline-flex; gap: 0.25rem; }",
".star-rating__star { font: inherit; font-size: 1.5rem; border: 0; background: none; color: inherit; cursor: pointer; }",
".star-rating__star.is-on { color: #b45309; }"
]
};
// The type, beside the standard catalogue.
survey.componentDefinitions = [rating];
</script>
</body>
</html>Nothing yet.
Try the form first. Press a star and the log shows the answer as a number. Then give the type to the builder: Rating sits on the palette under Survey, its inspector has a Stars field, and the canvas draws the stars with the same adapter.
Adding a type
The way to add a type is plugins.. A plugin carries the definition with its palette entry, and registering it once serves every <datum-form> and <datum-form-builder> on the page, including ones added later.
import { plugins, standardFieldCapabilities } from "./datum-form.js";
plugins.register({
id: "survey",
version: "1.0.0",
components: [{
type: "star-rating",
version: "1.0.0",
base: "number",
createDefault: () => ({ id: "rating", type: "star-rating", configuration: { label: "Rating", max: 5 } }),
capabilities: standardFieldCapabilities({ placeholder: false }),
palette: { label: "Rating", icon: "★", group: "Survey" },
adapter: ({ html }) => ({ kind: "field", template: (state, on) => html`...` })
}]
});A plugin can bring more than types: hooks, validators, a submission handler, formula functions and data sources. See Plugins.
Two lower routes exist for a single element:
componenton one element adds definitions to that element alone:Definitions form.. A builder lists a type fromcomponent Definitions = [definition] componentonly if a palette entry exists, whichDefinitions componentgives:Types builder.. Without it the type draws but is not on the palette.component Types = [{ type: "star-rating", label: "Rating", icon: "★", group: "Survey" }] pluginson one element takes a plugin for that element alone:element..plugins = [plugin]
What a definition holds
| Field | What it is |
|---|---|
type | The name a definition uses for it, such as "star-rating". A name that matches a standard type replaces that type. |
version | The version of the type. |
base | The standard type it reads as, an answer type or fieldset, panel or tabs. See Base and the kinds map. |
create | A function returning the component the builder adds when the type is picked from the palette. |
capabilities | The inspector fields the type shares with others. See Capabilities. |
property | The inspector fields of the type's own. See The inspector. |
children | For a container: { slots: [...] }, the named places children go. A slot has an id, multiple, and optionally min, max, allowed, allow, allow and empty (the words on the canvas while the slot is empty). |
adapter | How the type draws, on the form and on the builder's canvas. See The adapter. |
css | A list of CSS rules for what the adapter draws, adopted into the form after the design system's, so the type looks the same under every design system. |
palette | How the builder lists it: { label, group?, icon?, binding? }. group defaults from the type's name (Fields, Choices, Layout, Content, Actions, else Other). icon is a short text glyph. binding offers the type only while that design-system binding draws the canvas. |
pdf | { renditions, default: the ways the type appears in a PDF. See Plugins. |
validators | Validation stages that belong to the type. |
fixed | Marks a component that stands for something outside the author's hands, such as a field of a PDF template: its properties edit, but there is no Delete and it is never on the palette. |
Capabilities
A capability is a set of inspector fields with the code that writes them into configuration. standard returns the usual set for a value-bearing field, in the order the inspector shows them. Label, tooltip, hide label and disabled are always in it. The options turn the rest on or off:
| Option | Default | Adds |
|---|---|---|
description | on | Description. |
placeholder | on | Placeholder. Off for a control with no text box. |
required | on | Required. Off for a component that holds no value. |
data | follows required | The data key: the name the answer is stored under. |
messages | on | Validation messages per code. |
css | on | CSS classes. |
pdf | on | PDF rendition and leave out of PDFs. |
print | on | How it prints from the live form. |
pattern | off | Pattern and its message, for free text. |
length | off | Minimum and maximum length and the character count. |
rows | off | Visible rows, for a multi-line control. |
autocomplete | off | The autocomplete token. |
input | off | The keyboard and spell-check settings. |
affix | off | Prefix and suffix. |
attach | off | Attach uploaded files to a PDF, for a file type. |
css is exported too, for a container that lists its fields itself.
The inspector
property is { mode, fields?, sections?, features? }.
mode | Meaning |
|---|---|
default | The capabilities' fields only. |
extend | The capabilities' fields, then these. |
replace | These fields instead of the capabilities'. A container does this and lists the fields it wants. |
none | No fields. |
A field is { id, type, property. property is a path inside the component's configuration ("max", "tabs.). The field types:
type | Edits |
|---|---|
text, number, boolean | A string, a number (with min, max, step), a switch. |
select | One of choices: [{ value, label }]. |
localized-text | A text the form translates. |
color | A colour. |
expression, formula | A formula, in the Logic workspace's formula editor. |
component-selector | A component of the form. |
data-source-selector | One of the data sources. |
options-editor | Inline { value, label } options. |
messages-editor | Validation text per error code. |
chrome-editor | A region's header or footer parts. |
file | A file kept in the configuration (accept, and asset for ready-made values). |
path | A value path, with the form's saved paths offered. |
value-map | A table that translates one set of values to another. |
custom | Drawn by the definition's own render. |
Any field takes default (what the editor shows while the property is unset; nothing is written until the author changes it), visible and disabled ({ property, reading another property of the same component). sections group fields: { id, title?, field.
The adapter
adapter is an adapter object, a list of them told apart by when, or a function (lit, datum) => entry. A function receives the renderer's own lit namespace ({ html, ... }), so the page loads no template library, and Datum's own binding. A type that nothing draws shows the renderer's unknown-component note. An adapter is laid over whichever binding draws the form, so the type draws under every binding.
The kind says what it draws:
kind | Draws | template receives |
|---|---|---|
field | A leaf: input, choice, date, file, button, static content. | (state, on) |
group | A container around its children. | (state, children) |
tabs | A tabs container. | (state) |
grid | A data grid or repeating section. | (state) |
steps | A steps container. | (state) |
For a field, the renderer builds state and the adapter returns a template. The members a custom control uses:
state | Holds |
|---|---|
answer, value | The stored answer as it is, and as text. |
label, label, hide | The label and an id for it, so a group can name itself with aria-labelledby. |
hint, hint | The description and the id it must carry. |
id, name, value | The control's id, a name for grouped controls, and where the answer is stored. |
required, read, disabled, invalid, pending, busy | The field's states. Set aria-invalid="true" only while invalid. |
errors, error, notices, notice | The worded blocking errors and warnings, and the ids their elements carry. |
described | The ids that describe the control, in order. Write them as aria-describedby. |
locale, dir, mode, class | Language, direction, interactive, readonly or disabled, and the author's classes. |
words | The form's words for the locale, for any text the adapter draws. |
text(property) | One of the component's own configuration texts, in the locale. |
model | The engine's model: model. holds the properties the inspector wrote. |
on reports what the person did. The renderer ignores writes while the form is read-only or disabled.
on | Reports |
|---|---|
input(value, { interim?, bad | A new answer. interim: true while typing. |
commit() | The field was left or its value settled. It runs the leave-field check. |
parts({ day, month, year }) | A date typed in parts. |
files(list), remove(id), download(id) | A file field's picks, removals and downloads. |
The adapter's capabilities answer, per drawing capability, whether it draws it: drawn, degraded or none. The members and answers are the same as a design-system binding's; Writing a binding has the full contract, including after, ready, connect, focus and ids.
Base and the kinds map
The engine knows what a number is, how to validate it, how to print it and how a sandbox reads it. It knows nothing of star-rating. A definition's base says the standard type a type reads as, here "number". Types that hold an answer can have an answer type as a base, and containers can have fieldset, panel or tabs.
The builder copies the base into the form's kinds map, which is part of the saved definition:
{
"id": "customer-survey",
"kinds": { "star-rating": "number" },
"root": { "id": "root", "type": "form", "children": { "content": [] } }
}With the map in the definition, validation, the sandbox and the PDF treat a star-rating as a number without any of the type's code. The form can be checked on a server that has never heard of it. The definition below is the one the example loads:
{
"id": "customer-survey",
"version": "1.0.0",
"schemaVersion": "1",
"localization": {
"defaultLocale": "en",
"supportedLocales": [{ "code": "en", "label": "English" }]
},
"kinds": { "star-rating": "number" },
"root": {
"id": "root",
"type": "form",
"configuration": { "title": "Customer survey" },
"children": {
"content": [
{ "id": "fullName", "type": "text", "configuration": { "label": "Full name", "required": true } },
{ "id": "experience", "type": "star-rating", "configuration": { "label": "How was your experience?", "max": 5 } },
{ "id": "comments", "type": "textarea", "configuration": { "label": "Anything else?", "maxLength": 500 } },
{ "id": "submit", "type": "button", "configuration": { "label": "Submit", "action": "submit" } }
]
}
}
}Next
- Where components are placed and how the palette is limited: Components.
- The look of a type under a design system, and writing a binding of your own: Writing a binding.
- The inspector and palette on the builder: Customising the builder.