Forms
Forms are built in the editor under Forms: fields, the words on the button, what a visitor is told afterwards, and who is emailed. What visitors send arrives there too, new first, with spam set apart.
Drawing a form
Section titled “Drawing a form”siteForm gives a page one of the site’s forms as it is today: its fields, where it posts and the hidden values to
send along. Your component writes the markup.
---import { FORM_SCRIPT, siteForm } from '@velocity-astro/cms-astro';
const form = await siteForm(Astro, 'contact');---
{form && ( <form action={form.action} method="post" data-cms-form data-cms-form-failed="That could not be sent. Please try again."> {Object.entries(form.hidden).map(([name, value]) => <input type="hidden" name={name} value={value} />)}
{form.fields.map((field) => ( <div> <label for={field.key}>{field.label.en}</label> <input id={field.key} name={field.key} required={field.required} /> <p data-cms-form-error={field.key} role="alert" hidden /> </div> ))}
<!-- Hide this from people with CSS. A post that fills it is kept as spam. --> <div class="trap" aria-hidden="true"> <input type="text" name={form.trap} tabindex="-1" autocomplete="off" /> </div>
<button type="submit" data-cms-form-sending="Sending…">{form.submitLabel?.en ?? 'Send'}</button> <p role="status" data-cms-form-status hidden /> </form>)}<script is:inline type="module" src={FORM_SCRIPT}></script>siteForm(Astro, 'contact')finds a form by its key.siteForm(Astro, { id })finds one by its id, which is what aformfield stores when an editor chooses a form for a section.- It answers
nullfor a form that is closed or gone, so the section is left out. It never throws. - The form works as a plain HTML form. With scripts on,
FORM_SCRIPTsends it in place and writes each problem under its field, in the elements markeddata-cms-form-error. - The example draws every field as a text input to stay short. The starter’s
Form.astrodraws each kind: multi-line text, email, phone, dates, choices and checkboxes.
A field added under Forms is on the page at once: a page that draws a form is cleared from the cache when the form changes.
Where a form posts
Section titled “Where a form posts”Every form posts to one address, /api/cms/submit/<form key>. It is the only thing on the site anyone may write to
without signing in, so it trusts nothing it is sent:
- It checks where the post came from, how large it is and how many one address has sent.
- It keeps only the form’s own fields, each checked by its kind.
- A post that filled the hidden field, or carries no true mark of when its form was drawn, is kept as spam and answered like any other.
- Nothing a visitor typed is written back into the page that answers them.
Notices
Section titled “Notices”A form names the addresses to email about each submission. Notices go out through the same mail settings as sign-in links (see People and sign-in). A notice that cannot be sent never loses the submission.
The visitor is never emailed. There is no confirmation email in the beta.
Forms and the CRM
Section titled “Forms and the CRM”A form says which of its fields hold the sender’s name, email and phone. Whoever sends it, and is not marked as spam, becomes a contact, or adds to the one with that email. See CRM.
- A form can fill a contact’s custom fields from its answers, only where the contact holds nothing yet.
- A form set to start a deal does so when it is sent from an entry’s own page, for a type that takes deals: an
enquiry on a listing’s page becomes a deal about that listing. A page can also say which entry a form is about:
siteForm(Astro, 'enquiry', { about: { type: 'listings', slug } }).
What visitors send is personal data
Section titled “What visitors send is personal data”- Submissions are read only by owners and editors.
- Nothing from a submission reaches a page, a cache, the search index or a log.
- Everything one person sent can be exported as a file or erased, from Forms or from their contact.
- A form can say how many days submissions are kept, after which they are removed.