Forms and submissions

A form on a Meridian site is a declared endpoint: an entry in the site’s endpoints.yaml that names the inputs a post carries, the checks they pass, the steps that run (store the submission, send mail, subscribe to the newsletter, and more) and the template that answers. You write no server code. The engine validates the input in the visitor’s language, applies CSRF protection, rate limits and spam controls, keeps the stored copy for the retention you declare, and draws an accessible form for you if you want it.

A contact formCopy Anchor Link

# config/sites/<site>/endpoints.yaml
endpoints:
  - key: contact
    path: /contact/send
    methods: [post]
    access: public
    rate_limit: 5/hour/ip
    spam: { proof_of_work: true, honeypot: true, min_fill_time: 3s }
    input:
      name:    { type: text, max: 120, required: true, autocomplete: name, label: { en: Your name } }
      email:   { type: text, format: email, required: true, autocomplete: email, label: { en: Your email address } }
      message: { type: text, multiline: true, max: 2000, required: true, label: { en: Your message } }
      consent: { type: boolean, required_value: true, label: { en: I agree to you keeping this message for 90 days } }
    steps:
      - store: { as: contact, retention: 90d }
      - mail:  { template: contact-to-staff, to: settings.contact_inbox }
      - mail:  { template: contact-receipt, to: $email }
    respond:
      fragment: partials/contact-sent.html

# config/sites/<site>/site.yaml
settings:
  contact_inbox: hello@example.org

{# templates/_shared/partials/contact-sent.html #}
<div id="form-contact" role="status"><h2>Thank you</h2><p>We have your message.</p></div>

{# templates/_shared/emails/contact-to-staff.html #}
{% extends "emails/_layout.html" %}
{% block subject %}A message from {{ name }}{% endblock %}
{% block preheader %}Sent through the contact form.{% endblock %}
{% block body %}
<h1>A message from {{ name }}</h1>
<p>{{ name }} ({{ email }}) wrote:</p>
<blockquote>{{ message }}</blockquote>
{% endblock %}

# config/strings/en.yaml
strings:
  form.leave.blank: Leave this field blank
  form.submit: Send

# config/schema/page.yaml
extends: page
fields:
  - name: contactForm
    type: form
    endpoints: [contact]
    label: { en: Form }

{% if entry.contactForm %}
<section aria-labelledby="contact-heading">
  <h2 id="contact-heading">Send us a message</h2>
  {{ entry.contactForm.render(submit="Send my message") }}
</section>
{% endif %}

The form posts in place when JavaScript is available and as an ordinary post without it. A failed post draws the form again with what the visitor typed, an error summary and each field’s error; a successful post answers with partials/contact-sent.html.

engine-dmo dev endpoint add <key> writes the start of an enquiry endpoint like this one (--from recipe:newsletter for a subscription). It writes endpoints.yaml and exits 0, but it writes no templates: engine-dmo check then fails until you write the response fragment, the on_error form and each mail template it names. Its labels are in the source locale only.

What happens to a postCopy Anchor Link

A post passes the endpoint’s gates in this order, and only a post that passes all of them runs its steps:

flowchart TD
  post["POST /contact"] --> access{"CSRF token<br/>and access"}
  access -->|refused| deny["refused<br/>(401 member, 404 staff)"]
  access --> rate{"rate limits"}
  rate -->|over| r429["429, form drawn again"]
  rate --> spam{"honeypot, fill time,<br/>proof of work"}
  spam -->|refused| fake["fragment with empty values<br/>(looks like success)"]
  spam --> valid{"inputs and validation"}
  valid -->|invalid| again["form drawn again<br/>with errors"]
  valid --> steps["steps in order:<br/>store, mail, subscribe, ..."]
  steps --> respond["respond: fragment,<br/>location, json or stream"]
  steps --> kept[("stored submission")]
  kept -->|"retention passes"| purge["hard deleted with<br/>its uploads"]

The endpointCopy Anchor Link

Each entry of endpoints: in config/sites/<site>/endpoints.yaml:

InputsCopy Anchor Link

Each key under input: is an input name, and its value is a field declaration with the same grammar as a content type’s fields (Field types): text, select, boolean, number, date, relation and the rest. blocks, repeater and portable_text have no place in a visitor form. The order you write them is the order of the drawn form and of the error summary.

A relation input names a published document by id, and a step can then reach that document’s fields ($listing.organisation). A relation’s to must name types that exist.

File uploadsCopy Anchor Link

input:
  cv: { type: file, accept: [pdf], max_bytes: 10MB, label: { en: Your CV } }

A file input needs a post endpoint, is read from the body, accepts image (JPEG, PNG, WebP, AVIF), pdf and csv, and is at most max_bytes (default media.max_upload_bytes, at most 50MB). The file is sniffed from its bytes and stored as a private library asset that only the submissions inbox can open. A file input needs a store step, whose retention deletes the file with the submission.

ValidationCopy Anchor Link

Each input is validated by its field type. validation: adds rules across inputs:

validation:
  - rule: "message != empty"
    message: { en: Tell us what you would like to know. }
    fields: [message]

An invalid post runs no steps.

StepsCopy Anchor Link

Steps run in order after the input is valid and the abuse checks pass. Each step is one keyed entry.

A value in a step is a literal, $input (an input’s value), $input.field (a field of the document a relation input names) or settings.key (a value from the site’s settings: in site.yaml).

storeCopy Anchor Link

- store: { as: contact, retention: 90d }

while_open keeps a shared submission longer once the organisation’s partners reply to it or write a note on it; it must be longer than default and needs share_with_organisation: true.

A store step with no retention is refused: a form that keeps data must say for how long.

mailCopy Anchor Link

- mail: { template: contact-to-staff, to: settings.contact_inbox }
- mail: { template: contact-receipt, to: $email }

A subject key is accepted and ignored: the subject always comes from the template’s subject block.

The template receives every input by name, submission (the stored submission, when a store step ran first), replyTo, and the common mail context. Every message a post sends, the staff notice included, is rendered in the locale the visitor posted in. A send that cannot be queued (a suppressed address, a template that fails) is recorded against the submission and does not fail the post. When neither to nor fallback_to resolves, the submission stays received.

ResponsesCopy Anchor Link

respond: names exactly one shape:

Without on_error, an endpoint drawn as a form answers a failed post with the form drawn again; any other endpoint renders its fragment with the errors.

The response template receives:

A refusal for spam reasons looks like success to the sender: the fragment renders with empty values.

Drawing the formCopy Anchor Link

engine-dmo check does not check the key you pass to enquiryForm() or subscribeForm(): a misspelt key passes and prints nothing, so render the page once to see the form.

A printed form and render() write the CSRF and abuse-control fields, the error summary after a failed post (focus moves to it), and each input with its label, help, error message and aria-invalid and aria-describedby wiring, then the submit button. submit sets the button’s text (by default the string form.<key>.submit, then form.submit). enhance=false leaves out the in-place post, so the form is a plain post with or without JavaScript. Any other keyword becomes an attribute of the <form> element; id, action, method, enctype and data-on:submit are the engine’s. The drawn form’s id is form-<key>, its error summary form-<key>-errors and its button form-<key>-submit.

To write your own markup, use the description’s keys:

{% with form = enquiryForm("contact") %}
<form method="post" action="{{ form.action|url }}" id="form-contact"{% if form.challenge %} data-mrd-challenge="{{ form.challenge }}"{% endif %}>
  {{ csrfInput() }}
  {% for k, v in form.hidden %}<input type="hidden" name="{{ k }}" value="{{ v }}">{% endfor %}
  {% if form.honeypot %}<p hidden><label for="hp">Leave this blank</label><input id="hp" name="{{ form.honeypotName }}" tabindex="-1" autocomplete="off"></p>{% endif %}
  {% for fld in form.inputs %}
  <p><label for="c-{{ fld.name }}">{{ fld.label }}</label>
     <input id="c-{{ fld.name }}" name="{{ fld.name }}" value="{{ values[fld.name] }}"{% if errors[fld.name] %} aria-invalid="true"{% endif %}></p>
  {% endfor %}
  <button type="submit">Send</button>
</form>{{ form.challengeScript }}
{% endwith %}

Your own markup must keep what the drawn form does for accessibility: a visible label for every control, an error summary, and the errors tied to their fields (Accessibility).

The drawn form draws text, email, URL and telephone inputs, textareas and checkboxes. It does not draw a select input’s options or radio buttons: a select input is drawn as a text box. For a choice, write your own markup from form.inputs (each input carries its options).

Forms in more than one languageCopy Anchor Link

• One path for every locale. An endpoint has one path. The drawn form’s action adds the locale’s prefix, so on a site with cy the Welsh form posts to /cy/contact while the English one posts to /contact. Write the action from form.action in your own markup, never by hand.
• An endpoint and a page may share a path. Endpoints answer only their declared methods, so a post-only endpoint at /contact and a page whose address is /contact live side by side: GET shows the page, POST runs the endpoint. The Welsh page can have its own slug (/cy/cysylltu); its form still posts to /cy/contact.
• Give every label, help and validation message a value in every locale. engine-dmo check does not warn when an endpoint label lacks a locale (it does for schema labels), and a missing one falls back to the source locale’s text without notice.
• Email templates have no t(). The interface strings are not available in email templates: t() prints nothing there, and check does not flag it. Branch on the recipient’s locale instead:

{% block subject %}{% if locale == "cy" %}Mae eich neges gyda ni{% else %}We have your message{% endif %}{% endblock %}

Spam protectionCopy Anchor Link

There is never a CAPTCHA. A public post is protected by three controls, each checked against the fields the drawn form carries:

Each challenge can be posted once: the same drawn form posted twice stores once. A page’s form fetches its challenge with challengeScript after the page loads; a browser without JavaScript posts without one, gets the form back with a challenge in it and what was typed kept, and its second post goes through. Refusals for the honeypot, a bad or replayed challenge or a bad proof answer as if they succeeded, so a bot learns nothing.

The install defaults in engine.yaml apply to every public post endpoint. An endpoint may add a control or lengthen min_fill_time, and may not remove a control the default sets. Spam controls need the forms module, which both bundles compile.

Rate limitsCopy Anchor Link

A limit is <count>/<window>/<key>: window is second, minute, hour or day, and key is what is counted:

Each endpoint starts with the install default for its class (public post 10/hour/ip, public get 60/minute/ip, member 60/hour/session, staff 600/minute/session); a limit it declares replaces the default with the same key, and other keys are added. A public endpoint with a mail step also carries the install’s mail cap (500/day/endpoint). A post over a limit answers 429 with the form drawn again, what was typed kept, and “Too many attempts. Try again in …”.

The submissions inboxCopy Anchor Link

The admin’s Submissions screen lists what visitors sent through the site’s endpoints that have a store step, newest first, filtered by endpoint and status (received, failed, forwarded, delivered, opened, replied, spam). A submission’s page shows its values labelled from the declaration, its uploads (downloaded as attachments, never displayed inline), what became of each mail it sent, and when it will be deleted.

Reading needs submissions.view on the site, which the built-in Administrator role holds; grant it to others in config/access/roles.yaml. Every read and download is audited.

RetentionCopy Anchor Link

A scheduled task, at forms.purge_schedule, hard deletes every submission past its declared retention, with its uploads, and every submission of an endpoint that has left the configuration once forms.orphan_retention has passed.

When check reports a problemCopy Anchor Link

engine-dmo check reports every endpoint problem together. An endpoint’s diagnostic carries the line of the endpoint’s - key: entry (or of the step) and column 0, not the column of the offending key, so read the message for which key it means.

Configuration referenceCopy Anchor Link

In config/engine.yaml:

Headless sitesCopy Anchor Link

On a headless site, a post endpoint is submitted through the content API’s forms operation, which answers JSON and hands out the challenge; a respond on such an endpoint is unused and engine-dmo check warns. See the content API.