Skip to content
Docs
Start

Changing a form

The person says: “Add a phone number question to the application form, and look it over before it goes live.”

A form is the forms plugin’s data on the site, not theme code, and the plugin checks every change itself: its refusal comes back in its own words. In a change set the change is held with the form as it was, so it can be read before it is applied and put back after.

The loop

Section titled “The loop”
  1. Empress:site_status — the site, and an open change set to put the change in.
  2. Empress:changeset_create — title is the person’s sentence.
  3. Empress:site_call — tool: "empress.form_get" with form (its slug) reads the fields and rules as they are; then tool: "empress.form_set" with changeset: form and addFields (each field a name, label and type, after to place it), or fields for the complete list, or settings for notification emails and spam protection. With no form it creates one (name, slug, fields). tool: "empress.form_duplicate" copies one.
  4. Empress:site_status — section: "changeset" shows the held change in words and what it replaces, with the form as it is now.
  5. Empress:changeset_promote — once the person agreed; confirm: true. The plugin applies the change then.

Judgment

Section titled “Judgment”
  • fields is the complete list. A field named like an existing one keeps everything you do not restate; a field left out is removed. To add one field, use addFields; to take one away, removeFields.
  • Submissions are not touched. A new field is empty on the submissions already stored. Retiring a form keeps its submissions; deleting them is the console’s.
  • Retire last, and not while it is on a page. tool: "empress.form_retire" (needs the person’s yes) is refused while a published page holds the form, and inside a change set. Take the form off the page first.
  • Check after the yes. Read the form again with empress.form_get: the plugin applies the change at the promote and may refuse it then, and the promote’s answer says where it stopped.
  • The undo is the set. Empress:version_revert with to: "changeset:<id>" puts the form back as it was; a form the set created is retired by it, which needs an Admin.