Kindly EditDocumentationTry the editor

Move a page form to Kindly Forms

Turn a page's built-in Form into a Kindly form, bring its past answers, and see what carries over.

The Simple form element (called Form before this release) is the quick built-in form described in Forms, fields, and actions. It keeps working. When a page form needs more (conditions, payments, connections, an entries hub, reports), move it to Kindly Forms. The move makes a Kindly form from it, swaps the element on the page for that form as one Undo step, and can bring its past answers along. Nothing of the old form is changed or deleted.

Move a form#

  1. Open the page in the editor and select the old form.
  2. Choose Move to Kindly Forms. The words above it say what you gain: Emails, connections, payments and answers, all in one place.
  3. If the form has stored answers, a box reads Bring its past answer or Bring its N past answers. It starts ticked. Untick it to leave them behind.
  4. The page now shows the Kindly form in the old form's place, and the new form is selected. A message confirms it: Moved to Kindly Forms. Publish the page to show it. (or with the number of past answers that came). Anything that didn't carry over exactly is added to the same message.
  5. Look the form over, then Publish the page. Until you do, visitors keep the old form: the swap is in the page's draft.

Where the button is depends on the editor mode:

  • Simple mode (Developer mode off): selecting the old form (a Simple form) shows a Form group, already open, whose one setting is the move.
  • Developer mode: the move sits at the top of the Form's settings, above its fields, messages and actions, which stay available.

The move is offered to people who can edit the page and manage forms. On a site without Kindly Forms, or for someone who can't manage forms, nothing is shown.

Undo and moving again#

The swap is one step in the page's history. Undo puts the old form back on the page. The Kindly form that was made stays in Kindly Edit > Forms.

Moving the same form again never makes a second copy. While the first copy exists (and isn't in the trash), the button reads Use its Kindly Forms copy and puts that copy on the page. Past answers are only brought once: an answer that already came is skipped.

What carries over#

From the old form Becomes
The form's name The form's title (or the page's title when it has none)
Fields, in page order The matching Kindly fields: text, email, web address, password, number, paragraph, drop-down, choose one, choose several, file upload, hidden value
Phone fields Phone fields that take any digits, spaces and + ( ) . -, as before (no country picker or number check)
Date and time fields Date and time fields with the picker, keeping the earliest and latest dates
The acceptance box A terms agreement
Labels, required, placeholders, lengths, patterns, number ranges, default values, a drop-down's empty choice, file types, sizes and counts The same settings
Side-by-side widths (a quarter, a third, a half, two thirds, three quarters) A row of columns with the same widths, stacked on phones
Steps Page breaks with the same titles. The first step's title becomes the first step title, with step names as the progress
Next and back button words, the send button's words, the error message The same words
The success message The default confirmation, a message that hides the form
Redirect The confirmation goes to that address instead (an address starting with / is on this site)
Open a popup The confirmation opens the same popup
Keep submissions on or off Whether entries are kept
Email and second email Two emails with the same recipients, subject, from, reply-to, copies and plain or HTML format, on or off as before
[field id="x"] and [all-fields] in emails {inputs.x} and {all_data} smartcodes
The date, page, browser and IP lines an email included The same lines at the end of the email body, as smartcodes
Files sent as attachments The first email attaches the uploads, and each entry now also keeps them
Webhook A webhook connection to the same address, sent as JSON

Field names are kept, in lower case with _ in place of other characters (first-name becomes first_name). The new names are what the emails and smartcodes use.

The webhook sends a different shape#

The old form posted its own format. The Kindly webhook sends each answer under its field name, plus an _entry part with the entry's id, form, created_at and source_url. The move adds this note to its message: The webhook now receives each answer by its name, plus an _entry part. Check the service that receives it. Check the receiving service before you publish the page. See Connections.

Past answers#

When Bring its past answers is ticked, each stored answer for this form on this page becomes an entry of the new form:

  • with its answers under the new field names and its original date
  • marked read, with the page it came from and the browser
  • with its uploaded files, when the site still has them (forms that only attached files to the email didn't keep them)
  • with a record on the entry of which old submission it came from

The old submissions stay where they were, in the older Submissions screen. See Submissions and file uploads.

Settings the move reads on the server#

Emails, recipients and the webhook address are private settings of the old form. The move reads them on the server from the page's saved settings, so they never pass through the browser. The fields, steps and widths are read from the form as the editor has it now, unsaved changes included.

REST#

/wp-json/cantata-edit/v1/forms/{post}/{form}/convert, where {post} is the page ID and {form} the old form's data-cb-form ID. Both methods need permission to edit that page and to manage forms.

Method Does
GET { entries, converted }: how many past answers the form has, and the Kindly form ID if it was moved before (0 if not, or if that form is in the trash)
POST { html?, entries? } Makes the Kindly form (or returns the earlier one) and brings past answers unless entries is false. html is the form's markup as the editor has it; without it, the page's saved content is read. Answers { id, title, reused, entries, notes, edit }, where edit is the builder address

After a move, the action kindly_forms_legacy_converted runs with the new form ID, the page ID and the old form ID.

About this page

Documents Kindly Edit 0.9.16. Source: includes/forms/legacy.php, assets/form-settings.js, assets/editor.js. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.