Table-Backed Forms

Table-Backed Forms are Forms connected to a selected Project Database table. They provide a focused modal experience for creating new records or editing existing records in that table.

A table-backed Form uses the selected table as its field source. You choose which fields users should complete, arrange them in the Page Editor, and configure how the Form is opened and how its result is handled.

Common uses include:

• Adding a customer or contact.
• Creating an order or registration.
• Editing a member profile.
• Updating an inventory item.
• Changing a support ticket's details.
• Recording information in an existing Project table.

For the visual parts shared by all Forms, see Form Layout and Fields.

When to Use a Table-Backed Form

Use a Table-Backed Form when the main task is to create or update a record in one Project table.

Requirement	Recommended Approach
Create a new record in one Project table	Table-Backed Form
Edit an existing record in one Project table	Table-Backed Form
Use input fields already defined by a Project table	Table-Backed Form
Collect values that will be processed before deciding what to save	Custom Form
Submit a request involving multiple tables or external services	Custom Form coordinated with Page Flow or trusted Backend processing, as needed
Collect input without directly creating or updating a table record	Custom Form

For example, a Project may have a Customers table with fields for Name, Email, Phone, Status, and Notes. A Table-Backed Form can present those fields in a compact Add Customer or Edit Customer modal.

A Table-Backed Form is not necessarily the right choice just because the workflow uses Database data. If submission requires a specialized process before any record is saved, start by considering a Custom Form.

How Table-Backed Forms Work

Four parts work together:

Part	Responsibility
Project Table	Defines the underlying data fields and relevant Database rules.
Form Configuration and Fields	Connects the Form to the selected table and collects the values for its configured fields.
Opening Workflow	Opens the Form as a modal and establishes whether the task is creating a record or editing a particular record.
Submission and Result Handling	Performs or coordinates the configured create or update operation and presents success or error feedback.

The Database table remains the data model. The Form is the user-facing interface for working with selected fields from that model.

The overall process is:

Project Database Table
  Defines fields and data rules
          |
          v
Table-Backed Form
  Form Block and connected field blocks
          ^
          |
Opening Page or Data Table Widget
  New or Edit action and record context
          |
          v
Form Submission
  Validate and create or update the record
          |
          v
Submission Result
  Show feedback; refresh the opening Page if configured

The diagram describes the responsibilities involved. It is not a specific Page Flow block sequence.

Before You Begin

Prepare the table and decide what the Form should accomplish before designing the modal.

Check that:

• The intended Project table exists.
• Its fields represent the information users need to create or edit.
• Required values and acceptable formats are understood.
• Selection fields have suitable choices.
• Any fields that users must not modify are identified.
• The intended Project Users have appropriate permissions for the required operations.
• Protected business rules are enforced through the appropriate Database or Backend mechanisms.

For example, an Orders table may include an internal status, customer reference, calculated total, and audit fields. The Form should expose only the information appropriate for the current user's task. It does not need to display every field merely because the table contains it.

Database schema and access configuration belong under Database. The Form's layout cannot replace those rules.

Creating a Table-Backed Form

A typical creation workflow is:

1. Open Pages & Forms in the Project Editor.
2. Create a new item of type Form, or open an existing Form intended for the record workflow.
3. Open the Form in the Page Editor.
4. Select the Form Block and configure its table-backed data setup using the intended Project table.
5. Select the Form Fields Area.
6. Add the Form-specific field blocks for the table fields that users should enter or edit.
7. Arrange the fields using supported layout elements and add concise instructions where helpful.
8. Configure the primary submit control and any appropriate secondary actions.
9. Design the Success Status Area and Error Status Area.
10. Configure the Page, Button, Data Table action, or Page Flow behavior that opens the Form as a modal.
11. Save the Form and Preview the complete workflow from the opening Page.

Choose the table before adding its field blocks. The selected table determines which table-backed fields are available to the Form.

The precise editor controls and available field blocks depend on the Form and table configuration. Use the settings shown for the selected Form rather than assuming that every field type has the same controls.

Choosing and Changing the Project Table

Select the table that directly owns the record being created or updated.

Form Purpose	Example Project Table
Add or Edit Customer	Customers
Create Order	Orders
Register Attendee	Registrations
Update Inventory Item	Inventory
Edit Support Ticket	SupportTickets

These are example table names; use the actual names and field definitions in your Project.

If the Table Changes

Changing the selected table after designing the Form can invalidate assumptions about its fields and how they are used.

After a table change, review:

• Which Form-specific field blocks are still available and correctly connected.
• Required fields, field types, and selection values.
• Initial values and edit-record context.
• Page Flow references to fields or record data.
• New and Edit submission behavior.
• Database permissions for the new table.

Renaming a visible field label is different from changing the underlying table field. When the data definition changes, confirm that the Form still uses the intended field binding.

Adding and Connecting Table Fields

After selecting the table, build the Form using its available field blocks.

A Customer Form might use this structure:

Form Block (Customers)
  Form Fields Area
    Heading (Add Customer)
    Form Field Block (Name)
    Form Field Block (Email)
    Form Field Block (Phone)
    Form Field Block (Status)
    Form Field Block (Notes)
    Button (Save Customer)
  Success Status Area
    Text (Customer saved.)
  Error Status Area
    Text (We could not save the customer.)

This is a conceptual layout. The heading and Button labels do not, by themselves, configure data submission.

Form-Specific Field Blocks

When a Form is configured against a table, the Element Library can provide field blocks based on that table's field definitions. Depending on the field, a block may include:

• A compatible input control.
• A label.
• Required-field configuration.
• Selectable values where supported.
• The field connection used by the Form to identify the value.

Prefer these blocks for ordinary table-backed values. They are prepared for the Form's data source and reduce the risk of creating a visual input that is disconnected from the intended table field.

Form Field Blocks vs. Generic Inputs

Component	Appropriate Use
Table-backed Form field block	Collect a value connected to a field in the selected Project table.
Generic Input, Dropdown, or Multiline Input	Build an independently configured input interaction when its relationship to the Form is explicitly handled.
Heading, Text, Label, or other content element	Provide instructions, context, and presentation around the input fields.

A generic Input is not automatically connected to a table field merely because it is placed inside a Form. If you replace a generated field block with a generic control, verify how its value is initialized, validated, and submitted.

For broader guidance, see Element Library and Form Layout and Fields.

Choosing Which Fields to Show

A table may contain many fields, but the modal should support a specific task.

Field Category	Guidance
User-entered required fields	Include them unless a valid value is supplied through another configured mechanism.
Optional fields	Include those that matter for this workflow; omit unrelated fields.
System-managed fields	Do not expose them for editing unless that is intentionally supported.
Sensitive fields	Show them only when the intended user and workflow require access.
Selection fields	Check that choices are accurate and understandable.
Long-text fields	Provide enough room and useful guidance.
File or media fields	Test the supported upload and edit behavior if such fields are used.

For example, an Edit Customer Contact Details Form may only need Name, Email, and Phone even if the table has additional internal fields for account status, creation time, and administrative notes.

Labels, Field Names, and Bindings

A Form field has several distinct aspects:

Aspect	Purpose
Field in the Project table	Defines the underlying data value.
Form field binding	Associates a Form input with that table field.
User-facing label	Explains what the user should enter or review.
Page Element Name	Helps identify the Page Element in the editor and related configuration where applicable.

For example, a table field with a concise internal name could be shown with the label Customer Email Address. Changing that label does not automatically rename the table field.

Keep the Form field bindings consistent with the selected table. If you alter the table schema or replace field blocks, inspect the Form and any related Page Flow before publishing.

New-Record Workflows

A New workflow uses the Form to create a record that does not yet exist.

A typical sequence is:

1. The user selects New, Add, or another configured create action.
2. The opening Page opens the Table-Backed Form as a modal in the appropriate new-record context.
3. The Form shows empty fields or the configured starting values.
4. The user enters the required information.
5. The Form performs its configured validation and submission.
6. The create operation either succeeds or returns an error.
7. The Form presents the corresponding status or closes according to the workflow.
8. The opening Page updates its displayed records where configured.

Initial Values for New Records

New-record Forms can sometimes use starting values such as:

• Status set to New.
• A category selected on the opening Page.
• An associated customer or event identifier.
• A date or other value supplied by the workflow.

A starting value may come from the table or Form configuration, or from supported Page Flow behavior. Confirm where the value is defined and whether the Form allows the user to change it.

If a required table field is omitted from the visible Form, the submission still needs a valid way to supply that field when required by the data model. A hidden or omitted control does not guarantee that a required value is available.

Example: Add Customer

A Customers Page contains an Add Customer Button and a Data Table Widget.

• The Button opens the configured customer Form.
• The Form collects Name, Email, and Phone, with any other required values provided through the supported configuration.
• After successful creation, the opening Page refreshes the Data Table as needed.
• If creation fails, the Form presents an error rather than claiming the record was saved.

This example is a workflow pattern; it does not imply that a Button automatically submits or refreshes a Widget without configuration.

Edit-Record Workflows

An Edit workflow changes an existing record. Unlike a New workflow, it must identify which record is being updated.

A typical sequence is:

1. The user selects Edit for a record.
2. The opening workflow identifies that record and supplies the relevant context through the supported Form-opening mechanism.
3. The Form opens in the intended edit-record context.
4. Connected fields display the record's current values where supported.
5. The user changes the allowed fields.
6. The Form validates and submits the update.
7. The update succeeds or returns an error.
8. The modal and opening Page respond according to the configured result-handling behavior.

Record Identity Matters

Showing values from a record is not the same as identifying the record to update.

For an Edit workflow, confirm that:

• The record context corresponds to the row or item the user selected.
• The Form is configured to perform an update rather than an unintended create operation.
• The correct record is targeted, even if several records have similar displayed values.
• The user is authorized to modify that record.

Use the Project's supported record identification and Form-opening mechanisms. Do not infer that matching a name, email address, or visible row position is sufficient to identify the record safely.

Example: Edit Customer

1. A user selects the Edit action for a customer in the Data Table Widget.
2. The configured workflow opens the customer Form for that record.
3. The Name, Email, and Phone fields show the existing values where supported.
4. The user changes the phone number and selects Save Changes.
5. After a confirmed successful update, the table refreshes and displays the new value.

Test this path with several different records, not just one example. A modal that opens correctly but updates the wrong record is a serious workflow error.

Defaults, Related Records, and Opening Context

The opening Page may know information the Form should use, such as the selected customer, event, category, or account.

That information can help initialize supported Form fields or identify the record being edited. However, the specific mechanism must be configured; context does not automatically transfer simply because the modal was opened from a particular Page.

Examples of context include:

Context	Possible Use
Selected event	Associate a new registration with the event.
Selected customer	Create a related record or edit the selected customer.
Current workflow category	Preselect a category field.
Current Project User	Support appropriate user-specific defaults or display.

Only provide values the Form needs. Treat identifiers and defaults received through browser-side workflows as input, not proof of authorization.

For detailed context-passing patterns, see Opening Forms as Modals and Form Page Flow.

Validation and Data Rules

A Table-Backed Form should prevent avoidable entry mistakes and give useful feedback when submitted values are invalid.

Form and Field Validation

Common concerns include:

Validation Concern	Example	Where to Handle It
Required value	A customer must have a Name.	Supported field and Form validation.
Value format	An Email field should contain a valid email address.	Supported input type and validation.
Allowed choice	Order Status must be an allowed value.	Field configuration and applicable data rules.
Cross-field relationship	End Date cannot precede Start Date.	Page Flow for user feedback, with trusted enforcement if the rule is protected.
Data-dependent rule	A value must be unique or a record must remain available.	Applicable Database rules or trusted Backend logic.
Authorization	Only a permitted user can edit an order.	Database access rules or trusted Backend authorization.

Not every field type exposes the same validation options. Use the supported controls provided for the field and verify the result during Preview.

Browser Validation Is Not Authorization

Page Flow runs in the browser. It is useful for checking inputs and presenting messages before submission, but browser-side checks can be bypassed.

A Form must not rely on hidden controls, disabled fields, or Page visibility to enforce protected rules. Use the Project's Database access rules and trusted Backend operations for sensitive permissions and business decisions.

For example, if an application allows users to edit their own profile, the underlying data operation must enforce that restriction; hiding another user's profile from the UI is not enough.

Submitting and Handling Results

A Form's visual submit control, validation, and data operation are related but separate stages.

User selects Submit
       |
       v
Form validates input
       |
       v
Configured create or update operation
       |
       +---- Failure ----> Error Status Area / recovery
       |
       +---- Success ----> Success Status Area / next action

A submit click does not prove that a record was saved. Show the success state only after the configured data operation reports success.

Success Status Area

Use this area to confirm the completed task:

• Customer created successfully.
• Contact details updated.
• Registration saved.

If the Form closes immediately after success, the opening Page may need to reflect the completed operation. Configure that follow-up separately where required.

Error Status Area

Provide an explanation the user can act on:

• The customer could not be saved. Review the fields and try again.
• The record could not be updated. Refresh the list and try again.
• You do not have permission to change this record.

Avoid exposing internal database errors, stack traces, or sensitive system details directly in the modal.

Repeated Submissions

For create operations, repeated submissions may create duplicate records if the workflow does not handle them appropriately.

Where supported, provide an in-progress state or otherwise discourage repeated clicks. For operations requiring strict duplicate prevention, use the appropriate data rules or trusted Backend processing. Disabling a Button alone is not a reliable guarantee.

Using Table-Backed Forms with Data Table Widgets

Table-Backed Forms commonly work with the Data Table Widget on an administrative or record-management Page.

Data Table Interaction	Form or Page Behavior
New	Open a configured Form in new-record context.
Edit	Open a configured Form with the intended selected-record context.
Successful submission	Refresh or update displayed records as needed.
Failed submission	Show useful feedback without implying that the table changed.

A Page may use the same Form layout for New and Edit when its supported configuration allows that approach, or separate Forms when the fields or user experience differ.

Example: Customer Management Page

A simple implementation could include:

Customers Page
  Heading (Customers)
  Button (Add Customer)
  Data Table Widget (Customers)

Customer Form (Modal)
  Form Block (Customers)
    Form Fields Area
      Field Block (Name)
      Field Block (Email)
      Field Block (Phone)
      Button (Save)
    Success Status Area
    Error Status Area

The Page displays and selects records. The Form collects and submits values. The opening Page's supported actions or Page Flow can coordinate opening, context, and refresh behavior.

For a detailed explanation of the Data Table's New and Edit actions, see Data Table Widget.

Page Flow and Table-Backed Forms

Page Flow is optional for a straightforward Table-Backed Form. The selected table, connected fields, and supported Form submission configuration may be sufficient for an ordinary create or update workflow.

Use Page Flow when additional interaction is needed, such as:

• Supplying initial values from the opening Page.
• Reading or updating supported Form field values.
• Validating relationships between fields.
• Coordinating new and edit record context.
• Showing specialized user feedback.
• Refreshing a Data Table or another Page area after success.
• Calling a supported Backend capability when the workflow requires trusted processing.

Two contexts may participate:

Page Flow Context	Typical Responsibility
Opening Page	Starts the modal, supplies the relevant record or workflow context, and responds to completion.
Form	Initializes and validates Form fields and coordinates any additional Form-specific behavior.

Do not assume a custom Page Flow must be written for every table-backed create or update, or that a particular block or API exists without checking the supported Page Flow documentation.

For more information, see Form Page Flow and Page Flow for Forms and Widgets.

Access Control and Protected Data

A Table-Backed Form can display and submit values, but it is not itself a security boundary.

Consider the following separately:

Concern	Appropriate Configuration
Who may open a Page	Page access configuration.
Who may read, create, or update records	Database permissions and supported data-access rules.
Who may change protected fields or perform sensitive operations	Applicable Database rules and trusted Backend authorization.
How the modal looks and behaves	Form layout and supported Page Flow.

A visible Form field does not grant permission to update the corresponding data. Conversely, hiding a field from the Form does not by itself prevent someone from attempting to change that field through another interface.

If the application has role-specific editing rules, enforce them through the data and Backend mechanisms intended for that purpose. Do not rely solely on client-side checks or the state of the modal.

Responsive Design

Table-Backed Forms are commonly used inside modals, where space may be limited.

• Put the most important fields first.
• Use one or two related fields per row only when the available width supports it.
• Prefer a vertical arrangement of essential fields on mobile.
• Keep field labels readable and input controls practical to tap.
• Make the primary submit action easy to find.
• Keep success and error states concise enough to work within the modal.

Preview the Form in the context of the Page that opens it. A Form may look correct in the editor while becoming crowded when presented in a narrow modal or on a smaller device.

For additional design guidance, see Form Layout and Fields.

Previewing and Testing

Test the Form through its real opening workflow, using records representative of the published application.

Test Case	What to Verify
New record	The intended Form opens with correct defaults and creates the expected record.
Edit record	The correct record opens, its values appear, and that same record is updated.
Required fields	Missing required values produce clear feedback.
Invalid fields	Unsupported formats or choices are handled appropriately.
Omitted fields	Required data not visible in the Form is supplied appropriately or causes a clear failure.
Permissions	Users can perform only the operations they are authorized to perform.
Submission failure	The error state appears and the user is not told the operation succeeded.
Repeated submission	The workflow handles accidental repeated attempts appropriately.
Data Table refresh	Newly created or changed records appear after success where configured.
Responsive layout	Inputs and status areas remain usable on desktop, tablet, and mobile.

Also test situations where an existing record has been changed or removed since the user opened the list. The workflow should handle a failed or outdated update clearly rather than suggest an update was successful.

Preview may execute real data operations. If the Form writes to Project data or calls other services, use an appropriate test record and environment before publishing. Saving the Form does not, by itself, publish the changes to the application.

Common Issues and Troubleshooting

Issue	What to Check
A field is not available	Confirm that the intended table is selected and that the field exists in its definition.
An input appears but its value is not saved	Check whether it is a connected Form field block or a generic control without the required Form binding.
A new record is rejected	Review required fields, defaults, supported validation, and data permissions.
An Edit Form shows the wrong values	Verify the selected-record context and field bindings.
An Edit Form creates a new record instead	Review the configured new/edit mode and how the existing record is identified.
The Form reports success but the list looks unchanged	Confirm the update succeeded and configure or trigger the appropriate Data Table refresh.
A user cannot save a record	Check both Form validation and the applicable Database permissions or trusted rules.
The modal is difficult to use on mobile	Review Form layout, row/column arrangement, sizing, and status areas.

Good Practices

• Start with the data model. Select the table that directly owns the record.
• Use connected field blocks. Prefer Form-specific blocks for values tied to table fields.
• Expose only necessary fields. Do not replicate the complete table schema in every modal.
• Keep New and Edit context distinct. Ensure an update targets the intended existing record.
• Handle defaults deliberately. Know where omitted but required values come from.
• Design both status outcomes. A Form needs meaningful success and error experiences.
• Use Page Flow only where it adds value. Do not add extra logic to an ordinary create or update without a reason.
• Refresh surrounding content when appropriate. Make saved changes visible to the user.
• Enforce protected rules outside the browser. Database and trusted Backend configuration remain responsible for sensitive access and operations.
• Test the full modal workflow. Include permissions, failures, repeated requests, and different screen sizes.

Common Mistakes

Avoid these patterns:

• Creating the Form before confirming the table and its required fields.
• Assuming that selecting a table automatically places every needed field in the Form.
• Replacing connected field blocks with generic inputs without checking their bindings.
• Exposing internal, audit, or sensitive fields without a user-facing need.
• Assuming a hidden or disabled field prevents unauthorized changes.
• Omitting required values without supplying a valid default or workflow value.
• Opening an Edit Form without identifying the intended record reliably.
• Treating successful validation or a submit click as proof that data was saved.
• Assuming the opening Data Table refreshes automatically after a modal completes.
• Testing only with a permitted administrator or a single ideal record.

Table-Backed Forms work best when the Project table, connected field blocks, new or edit context, and submission result all describe the same record operation. This keeps modal data entry straightforward for users and makes the workflow easier to maintain.

Related Topics

• Forms
• Form Layout and Fields
• Custom Forms
• Opening Forms as Modals
• Form Page Flow
• Data Table Widget
• Element Library
• Database
• Cloud Flow
• Page Flow