Form
The form field: lets an editor place one of the site's declared form endpoints on a page, with the endpoints it may offer, the checks, and the form value templates render.
A form field lets an editor choose which form appears on a page: a contact form, a newsletter sign-up, a booking request. The forms themselves are declared endpoints in a site’s endpoints.yaml (Forms and submissions); the field stores the chosen endpoint’s id, so renaming the endpoint’s key keeps every page’s choice. The value is the same in every locale, since the endpoint’s own labels are already translated.
fields:
- name: signup
type: form
endpoints: [newsletter]
label: { en-GB: Form on this page } Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
endpoints | list of endpoint keys | every form endpoint of the site | The endpoints an editor may choose. |
An endpoint is a form endpoint when it takes a post, its access is public or member, it answers with HTML (not json or a stream), it declares at least one input from the form body, and its path takes no {placeholder} (a form field has no subject to fill one). engine-dmo check reports, at the field:
unknown endpoint "x", with a suggestion or the list of the form endpoints of the type’s sites;endpoint "x" is declared on <site>, which type <type> is not on;endpoint x on site main is not a form: it answers with JSON(or one of the other reasons above);- a warning when the field offers every form endpoint of a site that declares none.
At save the value must be a form endpoint of the document’s site that the field offers (form_endpoint: Choose one of the forms this site declares).
Stored value and template value
The stored value is the endpoint’s id, "end_srhmvkf6j3". With index: true the id is projected. In a seed file, give the same id, as written in the site’s endpoints.yaml or listed by engine-dmo describe project: contactForm: end_srhmvkf6j3. It is a configuration id, not a database id, so a seed may hold it.
Printing the value prints the address the form posts to. The value has:
| Property or method | What it is |
|---|---|
render(submit=, enhance=, ...) | The whole form: the CSRF and abuse fields, the error summary after a failed post, each input with its label, help, error and ARIA wiring, and the submit button. It posts in place with script and as a plain post without. submit sets the button text (else the string form.<key>.submit, then form.submit); enhance=false makes it a plain post always; other keywords are the form element’s attributes. |
id, key | The endpoint’s id and key. |
action, method | Where and how it posts. |
inputs | The declared inputs in order, each with name, type, label, help, required, autocomplete, multiline, max, format and options, for a form you write by hand. |
hidden | The hidden fields the abuse controls need, name to value. |
honeypot, honeypotName | Whether there is a honeypot, and its field name. |
member | Whether the endpoint is for signed-in members. |
{% if entry.signup %}{{ entry.signup.render(submit="Sign up", class="signup") }}{% endif %} SEO
The seo field: a per-locale search title and description and their social-sharing pair, with length warnings, the stored shape, and how head() uses it.
Validation
When a document is checked (save and publish), required fields and required_in, visible_when and required_when, the expression language, cross-field validation rules with severity and timing, and the publish checks.