← All plugins

Forms

Forms designed with blocks (contact, newsletter, registration …), embedded as a block. Every submission starts events - e.g. a new record and e-mails.

Download forms.zip
Version
1.3.0
Activated
Per project
Size
20 KB

Install

  1. Download the ZIP.
  2. In the admin app: Administration › Plugins › Upload plugin (ZIP).
  3. Install (runs its migrations), then activate it in the projects that need it.

Forms designed with blocks in the admin app, embedded as a block, sent by websites – every submission starts events (e-mail, new record …). The plugin stores no submissions itself: the events decide (e.g. a record of contact_message).

In the CMS

  • Forms are records of the entity "Forms" (forms), which the plugin creates in every project: tab Form with name and a block editor, tab Settings with slug, text of the button, confirmation and redirect. A form is active while it is published (drafts: inactive).
  • Field blocks (created as blocks in every project): text, e-mail, text area, number, phone, URL, date, select, radio buttons, checkbox (consent), checkboxes, hidden - each with name (key), label, required, placeholder, help, width, min/max, options (value|Label). Fields side by side: the block Columns of the CMS (category Layout) - its columns take the fields like any other blocks; fields inside other blocks with block lists count too. Response marks where the answer appears after sending - confirmation, errors or both, anywhere in the form and as often as needed (e.g. above the fields and next to the button); without one the errors appear above the button and the confirmation replaces the form. Any other block of the project (texts, images …) can be part of a form too - websites render it like their other blocks.
  • Block "form": title, text and the field type Form (forms.form) - add it to the blocks of a page entity.
  • Events › Reacts to › Form submissions: for all forms or one; the values are {{record.<field>}}, plus {{record.form}}, {{record.submitted_at}}. E-mail steps can go to users of the CMS (their address when sending) and to addresses like {{record.email}}.
  • Example (setup of every project, once): the form "Contact" (name, e-mail, message, consent), the entity "Contact messages" (contact_message) and the event "Contact form": it creates the message, e-mails the administrators and thanks the sender by e-mail.

On websites

The content API delivers the form with the record (field type forms.form): {id, slug, name, fields, submit_label, success_message, redirect_url, action, token, token_url} - fields are the elements: fields {name, type, label, required, placeholder?, help?, width, min?, max?, options?, default?}, {type: "columns", columns: [{span, fields}]} (the block Columns), {type: "block", block, fields?} for other blocks (with the fields inside them), {type: "response", show: "all"|"success"|"error"} (where the answer goes). Send the values (JSON or form data) to action:

POST /api/v1/<project>/plugins/forms/submit/<form>
→ 200 {id, message, redirect}   422 {error_data: {field: [messages]}}   429 too many (rate limit of the content API)

Token: every submission needs _token, a token of its form signed by the CMS. The form delivers one (token), GET /api/v1/<project>/plugins/forms/token/<form> a fresh one ({token}). It is valid from 2 seconds (faster: a bot) to 7 days after it was issued (setting Forms stay valid). Without one, with one of another form or an expired one the answer is 422 with the code form_expired ("please reload the page"). The template of the plugin sends the token of the page and fetches a fresh one when someone starts typing - pages from a cache keep working.

Bots: a field _hp must stay empty (they look like they were sent, nothing happens; the log says why). Hide it with display: none (not just off-screen): browsers and password managers fill visible fields.

Rendered by the CMS

The plugin brings templates for its blocks: the block "form" renders the whole form (fields, columns, hidden field against bots, a small script that sends in the background and shows errors at the fields; without JavaScript the browser posts the form and is sent back to the page with ?sent=forms). Websites ask for the HTML of blocks (content API ?render=html, PHP SDK ->html()) and output it - no extra package. Classes to style: excellent-form, form-field, columns__grid, column (block Columns), form-label, form-error, form-success, form-response (with is-success / is-error) …