Form Page Flow

Form Page Flow adds browser-side behavior to a Form. Use it when a Form needs initialization, custom validation, field updates, custom submission behavior, shared context, or specific success and error handling beyond its basic configuration.

Not every Form needs custom Page Flow. A simple Table-Backed Form may only need its table configuration, connected fields, submit control, and status areas. Add Form Page Flow when the Form needs additional behavior as it opens, validates, submits, succeeds, or fails.

Form Page Flow runs in the visitor's browser. It can coordinate the Form experience and invoke supported Project capabilities, but it is not a trusted security or authorization boundary.

For the workflow that opens a Form and handles the modal result, see Opening Forms as Modals.

Form Page Flow and the Opening Page

A modal Form normally participates in two related workflows:

Location	Primary Responsibility
Opening Page Page Flow	Open the Form, provide edit data or shared context, respond to the modal outcome, and update surrounding Page content.
Form Page Flow	Initialize fields, read context and Form values, validate input, coordinate submission, and manage Form-specific success or error feedback.

For example, a Customers Page may open an Edit Customer Form with the selected record. The Form can validate and submit changes. After a successful result, the Customers Page can refresh its Data Table Widget.

The two flows should be coordinated without making the Form dependent on the specific layout of the Page that opened it. This makes it easier to reuse a Form from other Pages or Widgets.

When to Use Form Page Flow

Use Form Page Flow when you need to:

• Initialize fields from shared context or configured defaults.
• Detect New versus Edit mode and adjust instructions or allowed changes.
• Read original edit data or current Form values.
• Update a field in response to another field or user choice.
• Apply cross-field or workflow-specific validation.
• Run custom submission behavior, including calling Cloud Flow.
• Prevent repeated submissions while processing is underway.
• Provide specific success or error messages.
• Reset fields when the workflow calls for a new entry.
• Work with supported file-field operations.

Use the Form's ordinary field configuration for simple labels, required fields, and supported input rules. Avoid adding custom logic when built-in behavior already meets the need.

For Form layout, field blocks, and status areas, see Form Layout and Fields.

Before You Begin

Before configuring Form Page Flow, identify the Form's data source and intended submission outcome.

1. Determine whether the Form is Table-Backed or Custom.
2. Configure the Form Block and the appropriate field definitions or Project table.
3. Place the required Form field blocks in the Form Fields Area.
4. Decide how the Form will open and whether it needs edit data, shared context, or both.
5. Identify any additional validation or submission behavior.
6. Decide what constitutes success and what should happen after failure or cancellation.
7. Confirm which operations require Database permissions, Cloud Flow, or another trusted Backend capability.

Then open the Form in the Page Editor and use its Flow action to configure Form Page Flow. The available blocks and options depend on the Form and the selected workflow context.

Understanding the Form Lifecycle

Form Page Flow can respond to several points in the Form's lifecycle.

Lifecycle Event	Typical Responsibility
On Init	Prepare the Form, inspect mode and context, and set initial values where needed.
Before Validation	Check or prepare conditions before the Form's normal validation proceeds.
After Validation	Work with the values and validation result after validation has run.
On Submit	Coordinate a custom submission or other configured processing.
On Success	Respond to a successfully completed Form operation.
On Error	Display or coordinate feedback when the operation fails.

These are Form lifecycle events, not actions that must all be implemented. Use only the events required for the Form's behavior.

A conceptual lifecycle looks like this:

Form opens
  On Init
     |
     v
User reviews or enters values
     |
     v
Submission begins
  Before Validation
  Built-in and configured validation
  After Validation
     |
     +---- Validation failure ----> Error feedback / correction
     |
     v
  On Submit (when custom submission is configured)
     |
     +---- Successful result -----> On Success
     |
     +---- Failed result ----------> On Error

This illustrates the responsibilities involved; it is not an exact representation of the editor's executable block sequence. Configure event behavior and any required completion signaling using the supported Page Flow operations for the Form.

On Init

On Init is the place to prepare the Form when it opens.

Typical uses include:

• Read shared context supplied by the opening Page.
• Determine whether the Form is in New or Edit mode.
• Read original edit data when an existing record is being edited.
• Set defaults or preselect fields for a New workflow.
• Adjust a heading or supporting instruction to match the task.
• Prepare Form-specific state needed later in the workflow.

For example, a new registration Form may receive the selected event through shared context and use it to initialize an Event field.

Avoid overwriting valid values loaded for an Edit Form with defaults intended only for New mode. Always check the opening mode before applying mode-specific initialization.

Before Validation

Before Validation is useful for checks or preparation that must happen before normal Form validation continues.

For example, an approval Form may require Notes when the user chooses Reject, even though Notes is optional for an Approve decision.

Use supported Form status or validation behavior when the workflow must stop. Do not assume that merely displaying an error message automatically cancels the submission; ensure the configured flow prevents an invalid operation from continuing.

After Validation

After Validation lets the Form work with the collected values after its validation stage.

This can be useful for:

• Reviewing the values about to be submitted.
• Preparing data for a custom processing step.
• Coordinating additional supported behavior based on the validation outcome.

Do not use this event to bypass required field checks or Backend rules. The exact continuation behavior depends on how the Form Page Flow is configured.

On Submit

On Submit coordinates custom processing when the Form's submission requires more than its ordinary configuration.

A Custom Form may need to read its values, combine them with shared context, call Cloud Flow, and report the resulting status. A Table-Backed Form may not need a custom On Submit workflow when its built-in record operation is sufficient.

When implementing custom submission, handle both successful and failed results and use the supported completion mechanism expected by the Form. An asynchronous Backend request starting is not the same thing as that request completing successfully.

On Success and On Error

On Success runs Form-specific behavior associated with a successful operation. On Error handles the failure path.

Use these events to coordinate clear feedback, preserve or reset appropriate state, and prepare information needed by the opening Page when supported.

Do not show success merely because the user selected Submit. Success should mean the configured operation has reported success.

Shared Context, Edit Data, and Current Form Data

A Form may work with three distinct types of information:

Information	Source	Purpose
Shared context	Additional information passed from the opening Page.	Set defaults, identify a related item, or continue a Page-specific workflow.
Edit data	Original record information supplied when the Form opens for editing.	Identify and initialize the existing record being updated.
Current Form data	Values currently held by the Form's connected fields.	Validate and submit the values the visitor has entered or changed.

Shared context is independent of edit data. A New Form may receive shared context without editing an existing record. An Edit Form may receive both edit data and shared context.

For example:

• New registration: The opening Page passes the selected event as shared context. The visitor enters attendee information into the Form. There is no original registration record to edit.
• Edit order: The opening Page supplies the selected order as edit data and may also pass a current category or filter as shared context.
• Quote request: The opening Page passes the selected product as shared context. The Custom Form collects contact details and request notes.

Shared context should not be assumed to appear automatically among current Form field values. If a submission needs it, read it separately or deliberately map the relevant value into a connected field.

Use Only the Context You Need

Pass concise, purposeful information. A Form often needs a record identifier, selected category, or related item rather than every value visible on the opening Page.

Context received in the browser is input, not proof of identity or authorization. If a record relationship or user permission matters to the operation, verify it through the appropriate trusted Project capability.

Working with New and Edit Modes

A Form can be opened to create new information or edit an existing record.

Mode	Typical Initialization	Submission Outcome
New	Empty fields, configured defaults, and optional shared context.	Create a new record or complete a new custom request.
Edit	Original edit data for an existing record, plus optional shared context.	Update the intended existing record or carry out the configured edit workflow.

Use the supported Form mode information rather than inferring mode from the heading text or the Button that opened the Form.

Example: Different Headings for New and Edit

On Init
  If Form is in Edit mode
    Read original edit data
    Display heading: "Edit Customer"
  Otherwise
    Display heading: "Add Customer"
    Apply New-record defaults where appropriate

This is conceptual logic, not the literal syntax or names of Page Flow blocks.

Original Values and Current Values

In Edit mode, original edit data and current Form data serve different purposes.

For example, an Order Form may open with Status = Pending. If the user changes it to Shipped:

Value	Meaning
Original Status	The value supplied when the Edit Form opened: Pending.
Current Status	The value currently selected in the Form: Shipped.

Comparing these values can help the UI decide whether a change requires an explanation or confirmation. It does not replace a trusted check that the user may make that change or that the record remains eligible for the update.

Ensure the correct existing record identity is used for an Edit operation. A matching customer name or other visible value is not necessarily a reliable record identifier.

Reading and Setting Form Field Values

Form Page Flow can read and update supported fields during the workflow.

Common operations include:

• Set a default value from shared context.
• Fill a related field based on another selection.
• Read values before validation or submission.
• Clear or reset a field when the workflow requires it.
• Prepare values for a Custom Form submission.

For example:

On Init, New mode
  Read selected event from shared context
  Set Event field to the selected event
  Set Status field to "New"

Another example:

When the user changes Request Type
  Read the selected request type
  Update supported related fields or instructions

Use the field definitions and names available to the Form. A visible field label, the Form field identifier, and the name of a surrounding Page Element are related concepts but are not necessarily interchangeable.

For fields bound to a Project table, preserve the correct table-field connection. Adding a generic input does not automatically make it part of the Form's collected or submitted data.

Current Form Data

Current Form data represents the collected values at the point when the workflow reads them.

Typical uses include:

• Check a combination of entered values.
• Prepare a request to Cloud Flow.
• Construct an application-specific submission object.
• Compare new values with original edit data.
• Generate contextual success or validation messages.

A conceptual quote-request submission might combine:

Information	Example	Source
Contact Email	[email protected]	Current Form data
Project Notes	Need 20 units by December	Current Form data
Product ID	PRODUCT-104	Shared context

The selected Product ID is not necessarily a Form field simply because the opening Page supplied it. If it is needed for submission, the workflow must include it intentionally.

Validation with Form Page Flow

Form validation serves two different purposes:

1. User-facing validation helps people enter complete, appropriately formatted information.
2. Trusted validation and authorization determine whether an operation is permitted and whether protected business rules are satisfied.

Use field configuration for supported required and type-specific checks. Use Form Page Flow for custom browser-side checks and to coordinate trusted validation where needed.

Common Validation Scenarios

Requirement	Form Page Flow Approach	Trusted Check When Needed
End Date must not precede Start Date	Compare current field values and show a correction message.	Recheck if the dates govern a protected operation.
Rejection requires a reason	Check Decision and Notes together.	Enforce required approval rules in trusted processing.
Quantity must be available	Provide early feedback using permitted data.	Verify inventory availability during the trusted transaction.
Event must accept registrations	Show a warning if registration appears closed.	Recheck capacity and registration status before accepting the record.
User may update a record	Adapt the visible workflow as appropriate.	Enforce record- and role-specific authorization.

Example: Cross-Field Validation

Before Validation
  Read Start Date
  Read End Date
  If End Date is earlier than Start Date
    Set an appropriate error status and message
    Stop invalid submission using supported Form behavior

The pseudocode demonstrates intent; the actual status controls and flow continuation must use supported Form Page Flow operations.

Keep validation messages specific. For example, "End Date must be on or after Start Date" gives a clearer next step than "Invalid input".

Custom Submission Behavior

Custom Forms typically require a defined processing outcome because their values are not automatically saved to a single Project Database table.

Possible submission behaviors include:

• Call Cloud Flow to create records or carry out server-side processing.
• Pass values to an Integration-backed workflow.
• Initiate a calculation and return a result.
• Submit an approval decision with a reason.
• Update a supported Page workflow after processing.

A simple Table-Backed Form may already perform the required record creation or update without custom submission logic. Avoid duplicating its built-in save behavior unless the workflow explicitly requires a different approach.

Custom Submission Lifecycle

A reliable custom submission follows these principles:

1. Validate the information needed to proceed.
2. Prevent repeated submission while processing is underway.
3. Read current Form data and required shared context.
4. Invoke the configured operation.
5. Wait for its result before determining success or failure.
6. Report the outcome through the supported Form status and completion behavior.
7. Restore appropriate interactivity if the user needs to correct and retry.

Example: Request a Quote

Consider a Custom Form opened from a product Page. The opening Page supplies the selected Product ID as shared context. The Form collects contact details and notes.

On Submit
  Lock Form
  Read current Form data
  Read selected Product ID from shared context
  Call Cloud Flow with required request values

  If trusted processing succeeds
    Set success status and a confirmation message
  Otherwise
    Set error status and a recovery message

  Unlock Form as appropriate for the workflow
  Signal completion using the supported custom-submit mechanism

This example is a conceptual sequence, not a list of exact Page Flow blocks or API calls. In particular, the completion signal and status behavior must be configured using the Form's supported Page Flow functionality.

The server-side process can validate the Product ID, enforce access rules, create the request, and send notifications. Page Flow should use the returned outcome to decide what the visitor sees.

Confirming Submission Completion

Starting an operation does not prove it succeeded. For custom submissions, keep the Form's processing state and final result aligned with the actual operation.

For example, a Cloud Flow call that fails should not lead to a success message or cause the opening Page to refresh as though the request had been accepted.

If the workflow requires explicit custom-submit completion signaling, provide it through the supported Form Page Flow mechanism after the result has been determined. Do not leave the Form indefinitely locked or in a pending state.

Success, Error, and Modal Outcomes

Form Page Flow controls Form-specific feedback. The opening Page separately decides what to do with the modal result.

Outcome	Inside the Form	On the Opening Page
Success	Show confirmation or finalize the Form state.	Refresh a Data Table, update content, close the modal, or continue a workflow where configured.
Error	Show the Error Status Area or another supported error message; allow correction when appropriate.	Avoid displaying a completed state or refreshing as though the operation succeeded.
Close / Cancel	End the input session without treating it as a successful submission.	Leave data unchanged and clear temporary opening state when needed.

The Form's Success Status Area and Error Status Area are part of its visual structure. The messages shown there should accurately reflect the result of the configured operation.

Success Behavior

On success, the Form may:

• Confirm the completed action.
• Leave a confirmation visible in the modal.
• Reset values if another entry is intended.
• Supply supported result information to the opening workflow.

A create or update operation should be confirmed before the opening Page refreshes its record list.

Error Behavior

On error, the Form may:

• Show a message describing what failed.
• Preserve user-entered values for correction.
• Unlock the Form for another attempt.
• Ask the user to retry when the failure is recoverable.

Avoid resetting entered values after an error when those values are still needed.

For the opening Page's responsibilities, see Opening Forms as Modals.

Locking and Resetting a Form

A long-running submission can lead to repeated clicks, duplicate requests, and confusing status messages.

Use supported Form locking behavior when processing needs to prevent another submission until the current one finishes. Unlock the Form when retry or correction is appropriate.

For valuable operations—such as payments, approvals, registrations, or inventory changes—also consider duplicate protection in the trusted Backend workflow. Disabling a browser control alone cannot guarantee that an operation is executed only once.

Use reset behavior intentionally:

Situation	Recommended Approach
New Form opens	Apply defaults or clear values as appropriate for a new entry.
Edit Form opens	Initialize from the record rather than clearing its values.
Submission succeeds	Reset only if the Form should support another entry.
Validation or submission fails	Preserve values when the user needs to correct and retry.
Modal is cancelled	Discard or retain temporary state according to the configured user experience; do not treat it as a submission.

Working with File Fields

Supported file-field operations may be used in Form Page Flow when a Form collects or edits files.

Depending on the field and configuration, a workflow may need to distinguish:

• Files already uploaded and associated with an existing record.
• Files newly selected but not yet uploaded.
• Pending files that should be removed before submission.
• Existing files marked for deletion.
• A deletion mark that should be cancelled.
• Whether new uploads or file removal should be temporarily disabled.

New versus Edit File Behavior

In a New Form, the user may be selecting files for a record that does not yet exist. In an Edit Form, the workflow may also need to preserve existing files, replace them, or mark them for removal.

Do not assume that selecting a file means it has already been permanently uploaded, or that removing a displayed file immediately deletes stored data. The behavior depends on the supported file-field operation and submission lifecycle.

Test file workflows separately for New and Edit modes, including a failed submission and a cancelled modal. Apply Database or Backend authorization for protected file operations where required.

End-to-End Example: Event Registration

Consider a Project with an Events Page and a Registration Form. Visitors select an event and register through a modal.

1. Opening Page

The Events Page shows available events and a Register Button for each one.

The opening Page's Page Flow:

1. Identifies the selected event.
2. Opens the Registration Form in New mode.
3. Passes the Event ID as shared context.
4. Responds after successful registration by updating relevant Page content if configured.

No edit data is needed for a new registration.

2. Form Initialization

The Form's On Init behavior can:

1. Read the selected Event ID from shared context.
2. Set a supported Event field or display the selected event's name.
3. Apply new-registration defaults.
4. Leave attendee fields ready for input.

Keep the association between the registration and the event explicit. Do not assume shared context automatically becomes current Form data.

3. Validation and Submission

The Form can validate attendee details in the browser. The submission can then call trusted Backend processing that verifies the selected event, enforces registration limits, and creates the registration record.

Capacity checks must be enforced at the trusted operation, because availability can change between the moment the Form opens and the moment it is submitted.

4. Handling Results

• Success: Display a registration confirmation and allow the opening Page to update the event's displayed registration state.
• Error: Explain why the registration did not complete and preserve correctable attendee details.
• Cancel: Close the Form without creating a registration.

5. Editing an Existing Registration

An administrative Page may open the same or a related Form in Edit mode. That workflow must supply the existing registration as edit data. It may also pass the selected event or current filter as shared context.

The Form should initialize from the intended existing record, apply edit-specific restrictions, and use trusted processing to update that record rather than create a duplicate.

This example demonstrates how Form Page Flow can support both mode-specific behavior and shared context while keeping authorization and protected record changes in the appropriate Project capabilities.

Previewing and Testing Form Page Flow

Preview from the Page, Button, Data Table action, or Page Flow event that opens the Form. Testing only the Form layout may miss problems with context, edit identity, or the opening Page's response.

Test Case	What to Verify
New Form	Defaults and connected fields initialize correctly.
New with shared context	The Form receives and uses the expected context without entering Edit mode.
Edit Form	Correct edit data is available and the intended existing record is updated.
Edit with shared context	Edit data and shared context are handled independently.
Field updates	Programmatic values reach the correct Form fields.
Built-in validation	Required values and supported field formats are checked.
Custom validation	Invalid combinations prevent continuation and show useful messages.
Custom submission	Submitted values and required context reach the intended processing workflow.
Backend failure	The Form reports failure and does not display success.
Repeated clicks	A running submission does not unintentionally execute duplicate operations.
Reset and retry	Error paths preserve values where needed and unlock appropriately.
File fields	Pending and existing files behave correctly in New and Edit modes.
Modal outcome	The opening Page refreshes or advances only when configured and appropriate.
Responsive layout	The Form remains usable on desktop, tablet, and mobile widths.

Test with realistic values and failures, not only successful submissions. Where a Form calls Cloud Flow or an Integration, consider the data and service effects of Preview before testing against live systems.

Troubleshooting

Symptom	What to Check
A default value is missing	Confirm the opening Page passes the expected shared context and On Init reads the correct value.
New Form behaves like Edit	Check the opening mode; shared context alone should not be treated as edit data.
Edit Form shows incorrect values	Check the selected record and supplied original edit data.
Field updates do not appear	Confirm the Form-specific field connection and supported field operation.
A value is missing on submission	Verify whether it belongs to current Form data or shared context; they are not automatically the same.
Invalid submission continues	Check that the custom validation uses supported behavior to stop continuation, rather than only showing text.
Custom Form shows success too early	Check whether Page Flow waits for actual processing completion and reports the final result.
Form stays locked	Review all success and failure paths, including completion signaling and unlock behavior.
User input disappears after failure	Check reset behavior on validation and error paths.
Opening Data Table remains stale	Confirm that the opening Page handles successful modal completion and refreshes the Widget.
File changes are unexpected	Distinguish pending files, uploaded files, and deletion marks in the supported workflow.

Good Practices

• Use lifecycle events intentionally. Keep initialization, validation, submission, and result handling in their appropriate places.
• Keep three data concepts distinct. Shared context, original edit data, and current Form data have different purposes.
• Check New and Edit modes explicitly. Do not infer the mode from visible labels.
• Use Form-specific field connections. Keep field operations aligned with the Form's defined data source.
• Validate at the correct boundary. Browser-side feedback improves usability; trusted rules belong in Database or Backend processing.
• Wait for actual completion. A started request is not a successful submission.
• Prevent repeated actions. Use Form locking and appropriate Backend duplicate protection for important operations.
• Preserve recoverable input. Avoid clearing user-entered values unnecessarily after errors.
• Keep the Form reusable. Let the opening Page manage its own refresh and navigation response.
• Test through the opening workflow. Include new, edit, shared context, failure, and cancellation paths.

Technical Reference

For exact Form Page Flow block inputs and Client API signatures, see the Programming Guide:

• Form Page Flow Blocks
• Form Events block
• Form Data block
• Form Original Edit Data block
• Form is in Edit Mode block
• $io.form API

Use the Programming Guide for precise block and API details; use this product guide for workflow, concepts, and authoring guidance.

Common Mistakes

Avoid these patterns:

• Treating shared context as edit data or assuming shared context exists only in Edit mode.
• Assuming shared context values automatically appear in current Form data.
• Reading field values before they are initialized or using the wrong field identifiers.
• Applying New-mode defaults over existing Edit values.
• Using a generic input and assuming it is connected to the Form's field definitions.
• Showing an error message without actually preventing an invalid submission.
• Showing success before a custom Backend operation has succeeded.
• Calling built-in table submission and a second custom save unintentionally.
• Forgetting to signal custom submission completion when required.
• Leaving the Form locked after a failed operation.
• Resetting fields after an error and discarding values the user needs to correct.
• Relying on browser-side context, hidden fields, or Page Flow checks for protected authorization.
• Testing the Form directly but not through the Page that supplies context and handles the result.

Form Page Flow is most effective when it adds only the behavior the Form needs. Keep the Form's fields, lifecycle events, shared context, edit data, submission outcome, and opening Page response clearly separated so the workflow remains understandable and maintainable.

Related Topics

• Forms
• Opening Forms as Modals
• Form Layout and Fields
• Table-Backed Forms
• Custom Forms
• Page Flow
• Page Flow for Forms and Widgets
• Database
• Cloud Flow