Skip to main content
Version: 1.28 (Current)

Forms 2.0 - Lifecycle

caution

This page is preliminary and subject to change as Forms 2.0 continues to be developed.

This page explains what happens, and in what order, from the moment a page with a form is requested until the user's click has been handled. Knowing the order tells you where to put your actions, which tokens they can use, and what data is still there when the user submits.

A form's life has two halves: opening, when the form is built and sent to the browser, and submitting, each time the user clicks a button. Between them the form lives in the browser, and the server keeps nothing in memory. What the server needs at submit travels with the form, encrypted.

Opening the form​

StepWhat happensWhere you come in
1. Page loadThe server builds the page that holds the form.On Page Load actions run. They can redirect the user or show an error instead of the form.
2. Pre-InitThe browser asks for the form.On Preinit actions run, before any field exists. Load data here, and add dynamic fields.
3. Field initializationEvery field gets its starting value, one field at a time, top to bottom.Set by each field's Initial Value, or by a token created in On Preinit with the field's name.
4. After initializationAll fields have their values.After Fields Initialization actions run. They can read, and change, every field's token.
5. Active fieldsEach field's Active setting is evaluated. Inactive fields are left out.Set by Active and its condition.
6. Sent to the browserThe fields, their values, and the encrypted form state are sent to the browser.
7. In the browserA saved draft, if any, replaces the values. Then the fields' Value automations and visibility rules start.Client-side expressions in Common Field Settings.

See Settings for where to add the actions for each event.

On Page Load​

On Page Load runs on the server while it builds the page, before the form exists. Use it to send the user somewhere else, for example to a login page, or to set tokens used in the form's Root CSS Classes.

Its tokens aren't available to the steps that follow, because the form's fields are loaded in a separate request. Load the data that fields need in On Preinit instead.

On Preinit​

On Preinit runs before the fields are created. It's the place to:

  • Load data that fields need, for example a record from a database with Run SQL Query.
  • Set starting values. A token created here with a field's name becomes that field's starting value, replacing its Initial Value. For example, a token Email fills the Email field. A field inside a Section uses its full name, such as Billing:City. A token that exists but is empty still counts, and leaves the field empty.
  • Fill Repeaters, by creating the list named in a Repeater's Initial Entries. See Repeater.
  • Add fields with the Dynamic Fields actions. This is the only event where they work. See Dynamic Forms.

Money and Phone fields also take a second part: a token Price:Currency sets a Money field's currency, and Phone:CountryCode sets a Phone field's country. A currency or country the field doesn't allow is ignored, and the field's own setting applies.

If On Preinit redirects the user, or ends with a message or an error, the fields aren't initialized and the form isn't shown. If it ends any other way, the fields are initialized but After Fields Initialization doesn't run.

Field initialization​

Each field takes its starting value in turn:

  1. A token with the field's full name, created in On Preinit, if there is one.
  2. Otherwise, the field's Initial Value, with its tokens resolved.

The field then writes its own token, so fields further down, and the actions in After Fields Initialization, can use it.

After Fields Initialization​

Runs once every field has its value. Every field's token is available, for example [Email]. Use it for work that depends on the starting values, such as looking up data for the value a field received.

The form shows each field's token as it is after this event, so changing a token named like a field here changes what that field shows. Still, prefer On Preinit for starting values: there, fields further down that use the value in their own Initial Value see it too.

Keeping data until submit​

Tokens created while the form opens are gone by the time the user clicks a button: every submit is a new request. To keep some of them, check Persist data for submit on the On Preinit or After Fields Initialization panel, and list the token names under Data Keys, one per line.

The listed tokens are stored in the form's encrypted state and restored before the button's actions run. The user can't read or change them, so this is the way to carry values such as a record ID or a price through to submit. In the classic Form module, hidden fields did this job. In Forms 2.0, use Persist data for submit instead: unlike a hidden field, the value never reaches the browser in a form the user can edit.

The form state also keeps which fields are active, and any fields added in On Preinit, so the submit sees the same form the user saw.

Submitting​

Each button click runs these steps:

StepWhat happens
1. CollectThe browser collects the values of the fields. Fields that are hidden or disabled are left out, unless they're set to submit their value anyway.
2. RestoreThe server restores the form from its encrypted state: its fields, which of them are active, and the persisted tokens. Active conditions aren't evaluated again.
3. TokensEach submitted value becomes a token with the field's full name, for example [Email] or [Billing:City]. [FormData] holds all of them as JSON. See Working with Form Data.
4. ValidateThe fields in the button's Validation Scope are checked. If any fails, the errors are shown and no actions run.
5. ActionsThe button's On Click Handler runs.
6. ResultsThe results are sent back to the browser as they happen: messages, redirects, refreshed values, or a confirmation question.

A Cancel button skips steps 3 and 4: the values aren't turned into tokens and nothing is validated. Its actions run, and an automatically saved draft is cleared.

The form stays open after a submit, unless an action redirects the user or closes it. To show new values in the form, use a refresh action such as Refresh Field Data.


Last updated: November 18, 2026