Forms and Widgets

Page Flow coordinates browser-side interactions between Page Elements, Forms, Widgets, and other supported Project capabilities.

Use Page Flow when an action on the Page needs to open a Form, pass information between components, respond to a result, refresh a Data Table, update a Widget, or continue a larger application workflow.

Not every Form or Widget requires Page Flow. A basic Table-Backed Form can use its configured fields and submission behavior, and some Widgets work through their Element Settings and associated Project configuration. Add Page Flow when the experience requires additional coordination.

This page focuses on the Page Flow side of those interactions. For the configuration of individual components, see Forms and Widgets.

How Page Flow Fits Into the Interaction

A Page may have several components participating in the same workflow:

Component	Responsibility
Page Elements	Present the interface and provide actions, inputs, labels, and layout.
Opening Page Page Flow	Responds to user actions, opens Forms, passes context, coordinates Widgets, and updates surrounding Page content.
Form	Collects and validates input through its Form Block, field blocks, and status areas.
Form Page Flow	Handles Form-specific initialization, validation, custom submission, and success or error behavior when required.
Widgets	Provide configured interfaces such as Data Tables, AI Agent conversations, payments, and display utilities.
Cloud Flow and other Backend capabilities	Perform trusted processing when authorization, protected credentials, or server-enforced business rules are needed.

For example, an Edit Customer action in a Data Table can open a modal Form. The Form updates the record, and the opening Page refreshes the Data Table after the operation succeeds.

The opening Page does not need to implement the Form's internal validation, and the Form does not need to know how the opening Page arranges its Data Table.

Choosing the Right Interaction Pattern

Requirement	Recommended Approach
Open a Form from a Page Button	Use Page Flow with Show Popup Form.
Attach a Form to a Data Table's standard New or Edit action	Use Data Table Attach Form.
Add a record-specific option to a Data Table	Configure a custom Data Table action and use its row context.
Refresh a Data Table after an operation	Use Data Table Refresh in the appropriate success path.
Supply filtered records to a Data Table	Enable Custom Query on the Widget and coordinate the query through Page Flow.
Provide context to an AI Agent Widget	Use supported Widget runtime commands when needed.
Supply a variable amount to a Payment Widget	Configure the Widget for a dynamic amount and provide it through supported runtime behavior.
Display chart output	Use Chart Area as the target and separately implement the chart-rendering behavior.
Display information about the signed-in user in navigation	Use Login Info and the Project's authentication configuration; Page Flow is not inherently required.

Prefer the component's built-in behavior when it already meets the requirement. Use Page Flow for the additional behavior that connects components into a workflow.

Opening Forms from Page Flow

Forms are normally opened as modal input experiences. The opening Page remains the surrounding context while the Form collects and processes information.

The Show Popup Form block is the standard Page Flow block for opening a Form directly from another Page. It can be used with a Button action or another supported event.

Show Popup Form Inputs

The block provides these inputs and result-handling areas:

Input or Area	Purpose
Form Slug	Identifies the Form to open.
Title	Supplies the modal title.
Data	Optionally supplies data for the Form, commonly the existing record in an Edit workflow.
Customization	Provides supported modal presentation options.
Shared Info	Passes a separate object of additional workflow context to the Form.
On Save Success	Runs the configured statements when the Form reports a save-success result.
On Form Close Success	Runs the configured statements when the modal closes with a success result.
On Form Close Failure	Runs the configured statements when the modal closes with a failure result.

These are the documented block inputs and callbacks. For exact input types and behavior, see Show Popup Form.

Configure the relevant result paths deliberately. A save-success event and the eventual closing of the modal are different moments. Do not assume they should trigger the same Page update twice.

Edit Data, Shared Context, and Current Form Data

These three concepts serve different purposes:

Information	Meaning	Example
Edit data	The existing record supplied when the Form opens for editing.	The selected Customer record.
Shared context	Additional information passed by the opening Page for a New, Edit, or Custom Form workflow.	The selected region, event, product, or parent record.
Current Form data	Values currently entered or changed in the Form.	The customer's updated name and phone number.

A New Form can receive shared context without being in Edit mode. For example, a new registration Form can receive the Event ID from the opening Page while creating a new Registration record.

An Edit Form can receive both edit data and shared context. For example, the current record can be supplied as edit data while a selected region or workflow option is supplied as shared context.

Inside the Form, use the documented Form Page Flow capabilities to read the shared information, determine Edit mode, inspect original edit data, and read current field values. Do not assume shared context automatically becomes part of the submitted Form data.

For more detail, see Opening Forms as Modals and Form Page Flow.

Example: Open a Registration Form

Consider an Event Details Page with a Register Button.

1. The visitor opens the Event Details Page.
2. The visitor selects Register.
3. The Button's Page Flow action opens the Registration Form using Show Popup Form.
4. The opening Page supplies the selected Event ID as Shared Info.
5. The Form reads the shared context and initializes the appropriate field or workflow state.
6. The visitor completes and submits the Form.
7. After success, the opening Page updates its registration summary or other relevant content.

Conceptually:

Event Details Page
  Register Button action
    Show Popup Form
      Form: Registration Form
      Data: none (New workflow)
      Shared Info: selected event
      On Save Success:
        Update the registration summary

Registration Form Page Flow
  On Init:
    Read selected event from shared context
    Initialize the registration context
  Submission:
    Validate and process the registration

This is a workflow outline, not literal Page Flow block syntax. Configure the actual blocks and Form behavior through the editor.

Handling the Modal Result

The opening Page should respond according to the result of the configured Form operation.

Outcome	Typical Opening Page Response
Save succeeds	Refresh a Data Table, update a summary, or show a confirmation.
Modal closes successfully	Continue any workflow that depends on a successful close, if needed.
Modal closes with a failure result	Preserve or restore Page state and provide appropriate feedback.
User cancels or closes without submitting	Usually leave existing records unchanged and avoid reporting a successful save.

The exact modal callbacks and close behavior depend on the configured interaction. Test cancellation separately rather than assuming every close maps to a particular callback result.

For record-changing workflows, refresh the opening Page only after the operation has actually succeeded. Avoid interpreting a Submit click or modal close as proof that data was saved.

Opening Page Flow and Form Page Flow

The opening Page and the Form may each have their own Page Flow.

Opening Page Page Flow typically:

• Opens the intended modal Form.
• Supplies edit data and/or shared context.
• Handles the modal's supported result callbacks.
• Refreshes Data Tables or updates surrounding Page content.
• Continues a larger browser-side workflow when appropriate.

Form Page Flow typically:

• Initializes fields and reads shared context.
• Determines New versus Edit mode.
• Reads original edit data and current Form values.
• Adds custom validation and submission behavior.
• Sets Form-specific success and error feedback.
• Coordinates trusted Backend calls where required.

A simple Table-Backed Form may not need additional Form Page Flow at all. A Custom Form usually needs a configured submission workflow because its values are not automatically saved to one selected Project table.

Keep the responsibilities separate so the same Form can be opened from different Pages or Widgets.

Coordinating Data Table Widgets

The Data Table Widget provides a configured interface for viewing Project records. Page Flow can extend its built-in behavior with Form attachments, custom actions, queries, refresh, and paging.

For basic table display, use the Widget's Table setting and selected columns. For runtime behavior, use the appropriate Page Flow controls.

Data Table Page Flow Controls

Control	Purpose
Data Table Attach Form	Associates a Form with the Data Table's New action, Edit action, or both.
Data Table Action Menu Customize	Configures visibility of supported standard row actions.
Data Table Add Action	Adds an application-specific action to the Data Table.
Data Table: Data	Provides selected-row data in a supported row-action context.
Data Table: Table Name	Provides the related table name in a supported Data Table action context.
Data Table Refresh	Reloads the Data Table's records.
Data Table Load Next Page	Moves to the next available page of records.
Data Table Load Prev Page	Moves to the previous page of records.
Data Table Custom Query	Supplies records and, where supported, an optional page size for a custom-query table.

These are Page Flow authoring controls, not ordinary Table Element Settings. For exact block inputs and outputs, use the Page Flow Blocks reference.

Attaching a Form to New and Edit

Use Data Table Attach Form when the Table's standard record actions should open a configured Form.

A typical setup is:

1. Add a Data Table Widget to the Page and configure its selected Project table.
2. Create a suitable Table-Backed Form with the required fields and status areas.
3. Open the Page's Page Flow.
4. Add Data Table Attach Form and select the intended Data Table element.
5. Choose whether the Form should be attached to New, Edit, or both actions.
6. Provide the Form slug and modal title.
7. Configure any additional success-handling or refresh behavior needed by the Page.
8. Preview New and Edit separately with realistic records.

When configuring a Page Flow block that targets a Data Table, use the element's HTML ID or the editor's supported element lookup. Do not substitute the element's display Name or an unrelated internal editing identifier for the required element ID.

For more information, see Data Table Widget.

New and Edit Contexts

The two standard record workflows have different input requirements:

Workflow	What the Form Needs
New	An empty or default-initialized Form, plus any optional shared context.
Edit	The selected record's edit data and identity so the intended record is updated.

A single Form can support both workflows when its table configuration and fields are appropriate. Test that defaults used for New do not overwrite existing Edit values.

Custom Row Actions

Use a custom Data Table action when the standard New, Edit, Refresh, and Delete choices do not cover the workflow.

For example, an Orders Data Table might provide Request Approval for a selected order.

A conceptual sequence is:

1. The user selects Request Approval on an order row.
2. The custom action receives the selected row context.
3. Page Flow identifies the relevant Order ID.
4. Page Flow opens an Approval Form or invokes another permitted workflow.
5. The result is processed through the configured Form or Backend behavior.
6. On success, Page Flow refreshes the Orders table or updates the selected order's status display.

Use the selected record identifier, not just visible text such as a customer name or order description, to associate the action with the correct record.

For exact row-action block inputs, see the relevant Page Flow Blocks reference.

Refreshing, Paging, and Custom Queries

Refresh is appropriate after successful record creation, editing, or another operation that changes the displayed data.

Next Page and Prev Page coordinate pagination with surrounding Page controls when needed.

Custom Query is appropriate when the record source depends on Page state, such as a selected event, status filter, current user, or related record. Enable Custom Query on the Data Table Widget before expecting Page Flow to supply the table's records.

For example:

Event selector changes
  Retrieve permitted registrations for selected event
  Supply results to the Data Table's Custom Query behavior
  Show the selected event's registrations

Registration Form saves successfully
  Refresh the registrations Data Table

This describes an application pattern, not a query language or executable block sequence. Query results and asynchronous completion must be handled using the supported blocks and results of the selected data operation.

Filtering records in Page Flow is not an authorization rule. Database access permissions or trusted Backend processing must prevent unauthorized records or operations from being exposed to the browser.

AI Agent Widgets and Page Flow

An AI Agent Widget exposes a configured Project AI Agent through an in-page or floating conversational interface.

The AI Agent's instructions, knowledge, functions, and sensitive behavior are configured in AI Agents. Page Flow can coordinate supported browser-side interactions with the Widget, but does not define the Agent's core behavior.

A basic AI Agent Widget may work without additional Page Flow once its Agent and appearance are configured.

Supplying Page Context

When supported by the Page's implementation, Page Flow can provide context such as:

• The currently selected record or item.
• The current Page or workflow step.
• A category or filter selected by the user.
• Other permitted information relevant to the conversation.

The AI Agent Widget documents these runtime commands for advanced interactions:

Runtime Command	Purpose
set-request-context	Supplies Page-specific request context.
set-prompt-context-cbFn	Supplies prompt context through a callback.
set-hook	Registers a supported Widget hook.
set-client-op-hook	Registers a supported client-operation hook.

Use supported Widget commands only when the Page requires that additional behavior. For command signatures and available options, see the Client API and AI Agent Widget documentation.

Example: Order Assistance

An Orders Page might allow a user to choose an order and ask an AI Agent about it.

1. The user selects an order.
2. Page Flow identifies the selected order context.
3. A supported Widget interaction supplies the appropriate context to the AI Agent experience.
4. The user asks a question using the AI Agent Widget.
5. The Agent responds according to its configured knowledge, functions, and permissions.

Adding an AI Agent Widget does not automatically make it aware of the selected record. Supplying context must be explicitly configured through supported behavior.

Do not supply secrets or unnecessary sensitive information as browser-side context. Any protected data access or operation performed for the Agent must enforce authorization independently of its instructions or visible interface.

Payment Widgets and Page Flow

Stripe Payment and Square Payment Widgets use configured payment provider connections. Page Flow can coordinate the browser-side steps around checkout.

Common uses include:

• Collecting required choices before presenting checkout.
• Calculating or supplying an amount that varies by visitor or record.
• Updating surrounding Page content as the checkout workflow progresses.
• Connecting a payment step with a Form, order, or registration workflow.

Fixed and Dynamic Amounts

A fixed-amount Payment Widget can generally use its configured Amount and Payment Connection without custom Page Flow.

For a dynamic amount:

1. Set the Widget's Amount to 0.
2. Obtain the selected options or permitted Project data used to calculate the amount.
3. Supply a valid amount greater than zero through the supported Widget runtime behavior.
4. Allow checkout to proceed when the Widget has a valid amount.
5. Test changes in selection to confirm the displayed amount remains correct.

The Widget documentation identifies these runtime commands:

Widget	Supported Commands
Stripe Payment	set-amount, post-payment-hook
Square Payment	set-amount, reinit, post-payment-hook

For their precise interfaces, use the Client API reference. The commands are not a substitute for payment-provider configuration.

Payment Confirmation Is a Backend Concern

A Page Flow success indication or a payment callback in the browser does not, by itself, establish that an order is paid or that fulfillment should occur.

For paid registrations, purchases, or account activation, use the supported provider integration or other trusted Backend mechanism to verify the transaction, amount, relevant record, and authorization before applying valuable changes.

See Payment Widgets and Cloud Flow for the related responsibilities.

Display and Utility Widgets

Page Flow may also coordinate supporting visual and account-related Widgets.

Chart Area

Chart Area provides a target for chart output. It does not automatically query Project data, select a chart type, or calculate visualization values.

A Page Flow may load the relevant data, respond to filters, and coordinate an implementation that renders into the Chart Area. The actual chart rendering must be supplied by supported custom behavior or chart logic.

Login Info

Login Info displays current Project User login information within a navigation area. It relies on the Project's user session and authentication context.

Login Info does not grant access to protected Pages or authorize Database or Backend operations. Use Page access settings, User Groups, Database rules, and trusted Backend checks for protected functionality.

For details, see Display and Utility Widgets.

Example: Managing Event Registrations

Consider an administrative Page where permitted users review registrations for different events.

The Page contains:

Event Registrations Page
  Event Selector
  Heading (Registrations)
  Data Table Widget (Registrations List)
  Button (Add Registration)
  Optional summary or status area

A possible workflow is:

1. Initialize the Page. Page Flow prepares the selected event and loads the permitted registration list.
2. Change the event. The user selects another event, and Page Flow supplies the corresponding records to the Data Table through its configured data-loading behavior.
3. Create a registration. The user selects Add Registration, and Page Flow opens the Registration Form with the selected Event ID as shared context.
4. Edit a registration. The user selects Edit on a row, and the configured workflow opens the Form with the selected record's edit data.
5. Process submission. The Form validates and submits, using trusted Backend processing if capacity restrictions or other protected business rules must be enforced.
6. Handle success. The opening Page refreshes the Data Table and any registration summary that depends on the changed record.
7. Handle failure or cancellation. The Page does not claim the record changed and leaves the surrounding interface in an appropriate state.

This is an example architecture. The data query, access rules, Form configuration, and Page Flow interactions must be configured as part of the Project.

Asynchronous Operations and Component State

Forms, data operations, Cloud Flow calls, and some Widget actions may complete asynchronously.

When coordinating them through Page Flow:

• Run dependent actions only after the relevant operation reports the required result.
• Handle failure instead of assuming an operation will succeed.
• Avoid triggering the same refresh or follow-up operation from multiple success paths unless necessary.
• Keep loading indicators or temporary action restrictions aligned with the current operation where supported.
• Avoid overlapping record updates or repeated submissions that could produce duplicate results.
• Preserve the Page's current filter or selected-record context when refreshing a Widget.

For asynchronous data access and Backend invocation, see Data and Cloud Flow.

Data Access and Security

Page Flow executes in the visitor's browser. Its visibility and execution context make it suitable for interface coordination, not for protecting secrets or enforcing sensitive authorization by itself.

Mechanism	What It Controls
Page access settings	Who may open the Page under the configured access rules.
Form configuration and validation	Which fields users see and which input checks are performed in the Form experience.
Widget settings	How a Widget appears and which supported controls are presented.
Database access rules	Which permitted records and operations can be accessed through supported data interfaces.
Cloud Flow and trusted Backend processing	Protected credentials, centrally enforced rules, authorization-sensitive operations, and trusted integrations.

Hiding a button, excluding a Data Table column, disabling an action, or restricting which records are requested in the browser does not replace Backend authorization.

For sensitive workflows, test both authorized and unauthorized behavior, including direct attempts to access records or invoke operations without following the visible Page sequence.

Previewing and Testing

Test the interaction from the same Page, Button, Widget, or row action that users will use.

Test Case	What to Verify
Form opening	The intended Form opens with the correct title and mode.
New Form context	Shared information arrives without putting the Form into Edit mode.
Edit Form context	The intended record and original values are loaded correctly.
Form submission	Validation runs, and success is shown only when the configured operation succeeds.
Close or cancel	Closing without saving does not update records or show a false success state.
Data Table New/Edit	The correct Form is attached and acts on the intended record.
Custom row action	The selected row context identifies the correct record.
Data Table refresh	Records are refreshed after successful changes and relevant filters are retained.
Custom Query	Matching, empty, and failed query results are handled sensibly.
AI Agent context	Only intended, permitted context is supplied and the Agent behaves appropriately when context is absent.
Payment workflow	Test and failure states work, and protected completion depends on trusted confirmation.
Chart Area	The rendered chart has usable dimensions and handles missing or empty data.
Permissions	Users cannot access or modify data beyond their allowed scope.
Responsive layout	Modals, tables, and Widgets remain usable on desktop, tablet, and mobile.

Preview tests should use representative records, long values, missing information, failed operations, and realistic permission configurations.

Good Practices

• Use Page Flow for coordination. Let Forms and Widgets handle the behavior they already provide.
• Keep responsibilities clear. Separate opening Page actions from the Form's internal Page Flow.
• Pass minimal context. Keep edit data and shared context distinct, and avoid exposing unnecessary information.
• Use stable record identity. Custom actions should operate on the intended record, not a similar visible label.
• Prefer dedicated blocks. Use the Data Table and Form blocks before resorting to low-level Widget commands or custom JavaScript.
• Refresh only after success. Make Widget updates reflect completed operations rather than attempted ones.
• Handle asynchronous results. Coordinate follow-up actions with the actual completion path.
• Enforce security in trusted capabilities. Do not treat Page Flow or visible Widget controls as an authorization boundary.
• Test the entire interaction. Start from the real opening action, not only the Form or Widget in isolation.

Common Mistakes

Avoid these patterns:

• Treating the opening Page and Form as if they share one Page Flow.
• Passing all Page state to a Form when only a few context values are needed.
• Confusing edit data with shared context or current Form data.
• Opening an Edit Form without the selected record's identity.
• Treating a modal close or Submit click as proof that a record was saved.
• Refreshing a Data Table before a record update finishes.
• Running the same post-save action from multiple callbacks unintentionally.
• Expecting a Data Table Custom Query to work before enabling Custom Query on the Widget.
• Assuming AI Agent Widgets automatically read the current Page's selected record.
• Assuming Chart Area automatically produces a chart.
• Treating a browser-side payment callback as authoritative transaction verification.
• Using hidden buttons, columns, or browser-side filters as the only security controls.

Page Flow is most effective when it coordinates focused components without taking over their responsibilities. Use Forms to collect and validate input, Widgets for configured experiences, and trusted Backend capabilities for protected operations.

Related Topics

• Page Flow
• Choosing Blocks
• Events and Startup
• Data and Cloud Flow
• Opening Forms as Modals
• Form Page Flow
• Data Table Widget
• AI Agent Widget
• Payment Widgets
• Display and Utility Widgets
• Data Design
• Page Flow Blocks
• Client API