Guide 10 · Developer docs

Forms and data capture

Building forms with the Forms module: how a form is put together and placed on a page, validating and branching, presenting it, where submissions are stored, and what happens after one arrives, from jobs and records to CRMs and payments.

L1–L2 Start reading
7
units
20
pages

A form on Core dna is a record like a page: a tree of steps, groups and elements, with its own layout and layout areas, revisions and publishing. Submissions are stored as records too, and what happens next is the job of the Orchestration module. This guide follows a form from building it to acting on what it collects.

Who this guide is for

Theme developers who render and style forms, content modellers who build them in the admin, and integrators who send submissions on to other systems. It assumes you know layouts and templates (Input types, layouts, components and images) and, for the last unit, jobs (Automation, jobs and integration). Every template example is given in both engines.

The units, in order

  1. Building a form: how a form is put together and placed on a page, its fields, groups and static elements, and multi-step forms.
  2. Validating answers: what the server checks, how a rejected submission comes back, and accessible error messages.
  3. Branching forms: showing and hiding fields, groups and steps by earlier answers.
  4. Presenting a form: the markup the platform prints, styling it, client-side helpers and the captcha.
  5. Storing submissions: reading and exporting them, file uploads, retention and privacy, and submitting through the API.
  6. Acting on a submission: jobs, notifications and confirmations, creating records, pushing to a CRM, and taking payments.
  7. Reference: every input type, and the platform's three form scripts.

Two ways to run a form

The platform supports two submission models, and the choice affects almost everything else in this guide. The form layout decides which one a form uses.

Page per stepAll steps in one page (JS)
How it submitsAn ordinary POST to the page the form is on, one step at a timeThe platform's /assets/forms/js-forms.js moves between steps in the browser, then sends every step in one JSON POST to /cdna-api/forms/submission/<form id>
Stored between stepsYes: each step is saved as it is submitted, and a token in the page ties the steps togetherNothing, until the final submit. A reload loses everything typed
Back to an earlier stepNo. The server always shows the first step that is not yet validYes: .navigate-previous and .go-to-step links
Conditions that look at an earlier stepNot on the server, which sees only the current step's answers. See Conditional logicYes: every answer arrives together
Works without JavaScriptYesNo
Validation errorsThe step is rendered again with the answers kept and an error under each failing fieldReturned as JSON. Add the handling on Validation rules and error handling so that the visitor's answers are kept

Use page per step for one-step forms and for anything that must work without JavaScript. Use the JS layout for multi-step forms whose later steps depend on earlier answers, or that need a back button, together with the error handling on the validation page. The details of each are on Multi-step forms.

Five things to know first

  1. Every form needs a layout with a template. Check the layout first when you place a form (How a form is put together).
  2. Branching on an earlier step needs the JS model. The server sees only the current step's answers, so a condition that looks further back needs the JS submission model (Conditional logic).
  3. The CSRF token is for signed-in members only. Public forms are not CSRF-checked, and _csrfToken exists only when someone is signed in, so print it guarded (How a form is put together).
  4. Uploaded files are public. A form's uploads go to the file manager, where anyone with the link can read them (File uploads).
  5. What follows a submission is a job. Notifications, records and CRM pushes are jobs on the form's submissions, and run in the background by default (Jobs, notifications and confirmations).

Contents

7 units, in reading order.

Building a form

How a form is built as a record, from the whole form down to a single element, and placed on a page; then which input suits which answer, and what changes once a form spans more than one step. 3 pages

How a form is put together The four levels of a form and what each is for, why a form is a revisioned record with its own layout areas, the two ways to put a form on a page, what happens on submit, and a minimal form layout. Read more Fields, groups and static elements The settings every input shares, which type to use for which answer, the three pairs that are easy to confuse, element groups, and the two static elements, one of which runs its scripts on every page the form is on. Read more Multi-step forms Steps, and what happens between them in each of the two submission models: what is saved and when, how each model moves between steps and keeps answers, the markup the platform's JS form needs, a progress indicator, and how many steps is too many. Read more

Validating answers

What the server checks without being configured, the rules you add yourself, how a rejected submission comes back in each submission model, and the patterns that keep errors accessible and preserve what the visitor typed. 1 page

Validation rules and error handling What each input type checks without configuration, what to check yourself, the rules you configure (with a regex that works on both sides), what a server rejection returns, and the patterns that make errors accessible and keep what the visitor typed. Read more

Branching forms

Showing, hiding and requiring fields, groups and steps as a visitor answers earlier ones, and the patterns that keep the browser and the server agreeing about what a form needs. 1 page

Conditional logic Showing, hiding and requiring fields, groups and steps as the visitor answers. The browser applies the rules as the visitor types and the server applies them on submit; these patterns give the same result on both. The safe patterns, and how to keep a branching form maintainable. Read more

Presenting a form

The markup the platform prints for a form and how far you can style or override it, the client-side helpers production sites add, and the captcha element that keeps spam out. 3 pages

Rendering and styling The markup the platform prints for every field and the classes to style; replacing one input type's markup without forking the form, and what you then take over; and styling a form to a design without fighting the platform. Read more Client-side helpers The four helpers production sites ship with their forms: an international phone field, timezone capture, prefilling from a link or from the signed-in member, and campaign capture. What each contributes, and where its code lives. Read more Captcha What the Captcha element does, the form setting that keeps failed submissions out of your data, where the captcha belongs, the script conflicts to avoid, and how to diagnose a captcha problem. Read more

Storing submissions

Where a submission is stored and how to read, export and accept file uploads on it, how long the platform keeps one and how to delete it, and sending a submission from outside a Core dna page altogether. 4 pages

Reading and exporting submissions The three levels a submission is stored at and the flattened answers; reading submissions in the admin and through the API, with a real response; and exporting them without turning an export into a leak. Read more File uploads Where a file uploaded with a form is stored, what the submission records about it, who can open it afterwards, the size and type limits, and the steps that keep uploads under control. Read more Retention and privacy What the platform keeps from a form and for how long, how to delete it, how to answer a request for someone's data, and what to agree with the client before launch. Read more Submitting a form through the API A Core dna form can be filled from a React or Vue front end, a mobile app or another system, with no Core dna page involved. The three routes, the body they take, what each status means, how to continue a submission that came back incomplete, and why the request has to come from your server. Read more

Acting on a submission

Everything that follows a submission is a job you build, under Customization › Orchestration (jobs were called hooks before the module was renamed). Starting one, creating records, pushing to a CRM and taking payments. 4 pages

Jobs, notifications and confirmations Starting a job when a form submission completes and what the job receives, then the two messages almost every form needs: a notification to staff, routed by an answer if need be, and a confirmation to the person who wrote in that cannot be turned into a spam relay. Read more Creating records from a submission The complete worked example of turning a submission into a person, without duplicates, step by step; then a lead, and a custom entity record created through the site's own API. Read more Pushing to a CRM Sending each submission to a CRM so that the CRM being down never fails or loses one: an idempotent push with retries, an hourly re-send that needs no state, and a daily check for anything still missing. Read more Taking payments Taking a donation, fee or deposit inside a form: where a form ends and a checkout begins, the setup, what a payment creates, and sending a receipt. Read more

Reference

Every element the form builder offers, and the three scripts the platform ships to run a form in the browser: the JS submission model, its conditional logic and its payment element. Look things up here rather than in the units that explain them. 4 pages

Form input reference Every element the form builder offers, one entry each: what the editor configures, the markup the platform renders, what is stored, what the server validates, and the accessibility notes. Read more js-forms.js reference The platform's script for the JS model: the markup it expects, the five callbacks and what each receives, the request it sends, what it does with the answer, and how to show an error answer so the visitor sees it and keeps what they typed. Read more js-forms-conditionals.js reference The platform's script that applies a form's conditional logic in the browser: when it starts, the data the layout must print, the markup it looks for, when it re-evaluates, and what it does and does not undo. Read more js-payment-element.js reference The platform's script behind a form's payment element: the markup it binds to, how it takes over two of js-forms.js's callbacks and hands them back, what it adds to the request, and what it does with each kind of answer. Read more