Form Layout and Fields

Forms are built in the Page Editor using a dedicated Form structure and the same visual editing tools used for Pages. A Form is designed for a focused input task: collecting values, validating input, and completing a workflow in a modal.

The visual layout, Form data configuration, and submission behavior work together. A well-designed Form has clearly connected fields, an understandable primary action, and useful feedback when the operation succeeds or fails.

This page explains the Form's structural areas, how to place and configure fields, and how to design the input and status experiences. For the underlying data and submission approaches, see Table-Backed Forms and Custom Forms.

Understanding Form Structure

A Form is organized around a Form Block with areas for inputs and submission feedback.

Area	Purpose
Form Block	The outer Form structure and the point at which the Form's table-backed or custom-field configuration is associated with its content.
Form Fields Area	The editable area containing fields, labels, help text, layout elements, and submission controls.
Success Status Area	Content presented when the configured Form workflow reports successful completion.
Error Status Area	Content presented when the Form cannot complete its operation successfully.

A conceptual Form hierarchy is:

Form Block
  Form Fields Area
    Heading
    Form Field Block (Customer Name)
    Form Field Block (Email Address)
    Form Field Block (Phone Number)
    Button (Save Customer)
  Success Status Area
    Heading (Customer Saved)
    Text (Confirmation message)
  Error Status Area
    Heading (Unable to Save)
    Text (Error and recovery guidance)

This illustrates the roles of the areas, not a requirement to use those exact child elements. The available structure and field blocks depend on the Form's configuration.

The Form Fields Area contains the primary interaction. The two status areas provide feedback after a submission attempt and should be designed as part of the Form, not added as an afterthought.

Selecting the Right Part of a Form

Each part can contain nested Page Elements. When editing, make sure you select the intended parent or child element:

• Select Form Block when you need to review the Form's overall data-related setup.
• Select Form Fields Area or a layout element inside it when arranging the input experience.
• Select an individual field or its label when changing its supported settings or appearance.
• Select Success Status Area or Error Status Area when editing submission feedback.

The Selected Element Toolbar provides actions for the selected element. Use Element Settings for its available Options, Design, and Advanced configuration.

Form Data Setup and Field Sources

Before building the field layout, determine what information the Form collects and where those values belong.

Form Approach	Source of Form Fields	Typical Use
Table-Backed Form	Fields from a selected Project Database table.	Create or update a record in that table.
Custom Form	Fields defined in the Form's custom schema.	Collect input for a workflow that is not automatically saved to a single table.

For example:

• An Add Customer Form might use a customer table with fields for name, email, phone, and status.
• A Request a Quote Form might define custom fields for service type, budget range, preferred date, and project notes.

A Form's data configuration determines the fields available for Form-specific field blocks. The Page Editor determines where those fields appear and how they are presented.

Adding visual fields alone does not define whether a record is created, updated, or otherwise processed. That depends on the Form approach and its configured behavior.

Building the Form Fields Area

Design the Form Fields Area as the content users see when the modal opens.

A typical Form includes:

• A title identifying the task.
• A short instruction when context is helpful.
• Fields grouped in a logical order.
• Labels and optional help text.
• Clear indication of required information.
• One primary submit action.
• Optional secondary actions such as reset or cancel, where supported.

Example: Customer Form Layout

Form Fields Area
  Heading (Add Customer)
  Text (Enter the customer's contact details.)
  Container
    Form Field Block (Customer Name)
    Form Field Block (Email Address)
    Form Field Block (Phone Number)
    Form Field Block (Status)
  Button Group
    Button (Save Customer)
    Button (Cancel)

The example shows a possible visual arrangement. It does not automatically configure the Button actions or the Form's submission workflow.

Adding Fields to a Form

1. Open the Form from Pages & Forms in the Page Editor.
2. Review the Form Block's data setup so the intended table-backed or custom fields are available.
3. Select the Form Fields Area or an appropriate child layout area.
4. Open the Element Library.
5. Add the appropriate Form-specific field blocks for values that participate in Form processing.
6. Arrange the blocks using Containers, Rows, Columns, or other supported Layout Elements.
7. Review each field's label, input presentation, required state, and supported settings.
8. Add the appropriate submit control and any secondary actions.
9. Configure the Success Status Area and Error Status Area.
10. Save the Form and preview it through the Page or workflow that opens it.

Select the intended insertion location before adding a field. Form content follows the Page Editor's parent-child element structure; adding a field to the wrong parent can produce an unexpected layout.

Form-Specific Field Blocks vs. Generic Input Controls

The Element Library provides both ordinary input controls and, when editing a configured Form, blocks associated with the Form's fields.

Approach	What It Provides	Recommended Use
Form-specific field block	An input arrangement prepared for the selected table-backed or custom Form field, including its supported label, required state, selectable values, and field binding.	Values that the Form needs to initialize, validate, or process as part of its configured workflow.
Generic Input	An independently configured input control.	A standalone or specialized input interaction where its data relationship and behavior are deliberately configured.
Generic Dropdown	A selection control with its supported option configuration.	Independently configured selections or special interaction needs.
Generic Multiline Input	A control for longer free-form text.	Independently configured notes or other long-text input.

For ordinary Form fields, start with the field blocks generated from the Form's data definition. These blocks help preserve the intended field relationship rather than requiring you to reconstruct it manually.

What a Form Field Block Can Include

Depending on its source field and supported configuration, a generated field block can provide:

• A compatible input control.
• A corresponding label.
• The required state associated with the field.
• Selectable options where relevant.
• The field binding used by ioLoop to identify and process the value.

The exact control and available options depend on the field. A text field, selection field, checkbox, date, or numeric value may require different input presentation.

Do not assume that replacing a generated block with a generic input preserves its original field binding. Review the Form configuration and any related Page Flow after changing or replacing input elements.

Common Input Presentations

Information to Collect	Possible Control
Name, short description, or email address	Input with an appropriate supported type.
Notes, comments, or a longer explanation	Multiline Input.
One choice from a defined list	Dropdown.
A yes/no choice or opt-in	Checkbox-style Input.
Date or time	Input using the relevant supported date or time type.
Number or quantity	Numeric Input.

These are typical control choices, not a guarantee that every field type or setting is available in every Form context. Use the field blocks and options offered for the selected Form.

For broader element descriptions, see Element Library.

Connecting Displayed Fields to Form Values

A user-facing label and a Form field binding have different jobs.

• The label tells the user what information to provide.
• The Form field identifies the value collected by the Form's configured data definition.
• The input control provides the way the user enters or selects that value.
• The element Name, where used, helps identify an element in the editor and related configuration; it is not automatically the underlying data field name.

For example:

Label Shown to the User	Value Represented
Customer Name	The Form's customer-name field.
Email Address	The Form's email field.
Phone Number	The Form's phone field.
Account Status	The Form's status field.

A label can be more descriptive than the corresponding data field. For example, a field stored under a concise internal name can have a readable label such as Preferred Contact Method.

When a field is renamed, removed, or changed in the Form's underlying data definition, review the associated field blocks and any behavior that depends on them. A visual label change and a data-definition change are not the same operation.

Labels, Helper Text, and Field Order

Well-labeled fields reduce confusion and avoid unnecessary validation failures.

Labels

Use a visible, meaningful label for each important input. Prefer Email Address to Email, and Delivery Instructions to Notes when those descriptions better explain the required information.

Placeholder text inside an input can provide a short example, but it should not replace the visible label. Placeholder text may disappear as soon as the user starts typing.

Helper Text

Add concise instructions where the expected format or decision is not obvious. For example:

• Order Reference: Use the reference from your confirmation email.
• Project Notes: Include the scope, deadline, and any special requirements.
• Preferred Contact Time: Select a time when your team is available.

Avoid placing long procedural instructions before every field. Put common instructions near the top and field-specific guidance next to the relevant input.

Field Order and Grouping

Arrange fields in the order users naturally provide information. Group related values and put the most important fields first.

For a customer form, a practical order is:

1. Name and identity.
2. Contact information.
3. Account or request details.
4. Optional notes.
5. Primary submit action.

A Row with multiple Columns can work well for related short fields on desktop, but a single-column arrangement is often easier to complete on mobile.

Initial Values and Editing Existing Records

New-record and edit-record workflows may use the same general field layout, but they have different initialization requirements.

New Record

A new-record Form normally begins with empty values or appropriate defaults defined by its field setup or supported Page Flow behavior.

Examples include a default status, a previously selected category, or a value supplied by the Page that opened the Form.

Edit Record

An edit Form needs the correct existing record context and values. The connected fields can then present those values for review and modification.

For example, when a user selects Edit for a customer in a Data Table Widget:

1. The opening workflow identifies the intended record.
2. The Form opens with the relevant record context.
3. The configured fields display the existing values where supported.
4. The user changes one or more fields.
5. The configured Form workflow submits the update.
6. On confirmed success, the opening Page can refresh its Data Table.

The mechanisms for identifying the record and initializing values are covered in Table-Backed Forms, Opening Forms as Modals, and Form Page Flow.

Do not assume a field will be populated just because it has been added to the visual layout. Confirm the actual data binding and opening context when testing edit workflows.

Required Fields and Validation

Validation helps users correct incomplete or invalid information before the workflow continues.

Use the Form's supported field configuration to indicate required values and applicable formats. When more specialized checks are needed, coordinate them with Page Flow and, where required, trusted Backend behavior.

Types of Validation

Validation Concern	Example	Where It Belongs
Required value	Customer Name must be provided.	The field's supported required configuration and Form handling.
Supported input format	An email field should contain an appropriate email address.	The relevant input type and supported validation behavior.
Cross-field rule	End Date must not be earlier than Start Date.	Additional Form logic where supported.
Data-dependent rule	A requested identifier must be available.	Permitted data operations, and trusted Backend checks when necessary.
Protected business rule	A user must be authorized to change an order.	Database access rules or trusted Backend authorization.

The Form layout should make errors understandable. Prefer a message such as Enter a valid email address over a generic Invalid input when the issue can be explained safely and accurately.

Browser Validation vs. Backend Enforcement

Page Flow executes in the visitor's browser. It can improve the user experience by checking entered values and displaying feedback, but browser-side validation is not a security boundary.

For restricted records, protected business rules, or sensitive operations, use the appropriate Database permissions or trusted Cloud Flow behavior. A hidden field or disabled Button must not be treated as authorization.

Submit, Reset, and Secondary Actions

A Form should have one easily recognizable primary completion action, with secondary actions only when they serve a real purpose.

Action	Purpose	Design Consideration
Submit / Save	Starts the configured create, update, or custom submission workflow.	Use a task-specific label such as Add Customer or Save Changes.
Reset	Clears or resets values when a supported reset behavior is configured.	Consider whether clearing input could surprise the user.
Cancel / Close	Leaves the modal without completing the task.	Distinguish cancellation from successful submission.
Additional Action	Supports an intentional alternative workflow.	Avoid competing with the primary submit action.

Adding a Button only creates the visible control. Its action must be provided by the Form's supported behavior or explicitly coordinated through Page Flow where needed.

For example, a Save Customer Button should not be assumed to save data merely because it has that label. Test the actual submission operation.

Avoid Accidental Repeat Submissions

Where the workflow supports it, provide a clear in-progress state while a submission is being processed. This can help discourage repeated clicks and reassure users that the operation is underway.

For workflows that could create duplicate records or trigger costly operations, trusted backend processing should also handle repeated requests appropriately. Visual button states alone cannot guarantee that an operation runs only once.

Success Status Area

The Success Status Area provides the user-facing confirmation after the configured Form operation completes successfully.

A useful success state answers:

• What happened?
• Was the information saved or the request submitted?
• What should the user do next, if anything?

Examples:

• Customer added successfully.
• Your profile changes have been saved.
• Your request was submitted. Our team will review it.

Keep the wording aligned with the actual operation. For a custom Form that sends a request for later processing, avoid claiming that the entire downstream process is complete unless the workflow has confirmed that result.

Depending on the configured modal workflow, the Form may remain visible with confirmation content, close, or notify the opening Page to update its display. These are workflow decisions; do not assume the same response is automatic for every Form.

Error Status Area

The Error Status Area communicates that a submission could not be completed and should offer a useful recovery path.

For example:

• The customer could not be saved. Review the details and try again.
• The request could not be submitted. Please try again.
• You do not have permission to update this record.

When a problem is associated with a specific field, show an understandable indication near that field where supported. Use the Error Status Area for the overall failure message.

Avoid exposing database errors, credentials, internal service responses, or other sensitive details directly to visitors. Log or handle implementation-level details through the appropriate Project tools.

Success and Failure Must Reflect the Operation

A click on the submit Button is not the same as a successful save. Likewise, completing browser-side validation does not prove that a database write or other Backend operation succeeded.

Show the success experience only after the configured workflow establishes successful completion. Show an error or recovery state when the operation fails.

Form Page Flow and the Opening Page

Forms are commonly opened by another Page, including through a Button, Data Table Widget, or a Page Flow action.

Two application contexts may need to work together:

Context	Responsibility
Opening Page	Starts the modal, supplies supported context, and updates its interface after the Form completes or closes.
Form	Displays and collects input, applies its configured field handling, and performs or coordinates its submission behavior.

Page Flow can add browser-side behavior, such as initial values, conditional fields, additional validation, status handling, or updating the opening Page after an operation.

For a simple table-backed workflow, the Form's built-in data configuration may cover much of the work. Use extra Page Flow only where the workflow requires it. For custom submissions, additional Form logic may be central to how values are processed.

For details, see Form Page Flow and Page Flow for Forms and Widgets.

Responsive Design for Modal Forms

A modal has less room than a full Page. Design fields, labels, and actions to remain understandable without excessive scrolling or cramped controls.

Area	Desktop Consideration	Mobile Consideration
Field Layout	Short related fields may share a Row.	Prefer stacking essential fields vertically.
Labels and Help	Use available horizontal space without creating long instructions.	Keep labels visible and helper text concise.
Inputs	Maintain comfortable control widths.	Avoid narrow or side-by-side essential inputs.
Buttons	Make the primary action prominent.	Keep actions accessible and practical to tap.
Status Areas	Keep feedback clear within the modal.	Ensure messages remain visible and readable.

Use the responsive options in Element Settings where available. Review both individual controls and their surrounding Containers, Rows, and Columns.

Accessibility and Clarity

• Use visible labels that describe each input.
• Do not rely only on color to identify required fields or errors.
• Keep tab and reading order logical through the chosen layout.
• Make status messages understandable without needing to infer meaning from icons.
• Check that controls are usable with keyboard interaction and on touch devices.

These are design and testing practices; the precise behavior depends on the selected elements and their configuration.

Example: Add and Edit Customer Modal

Consider a Customers Page that contains a Data Table Widget and supports New and Edit actions.

1. Prepare the Form

Create a Form with a table-backed configuration linked to the appropriate customer table.

Ensure that the necessary fields exist in the Project table before building the layout.

2. Build the Fields Area

Add the Form-specific field blocks for Customer Name, Email Address, Phone Number, and Status.

Give the Form a clear heading, keep fields in a logical order, and add a primary save control.

3. Configure Feedback

Use the Success Status Area for a message such as Customer saved successfully.

Use the Error Status Area for failures, with a message that tells the user whether they can correct input or retry.

4. Connect the Opening Workflow

Configure the New action to open the Form for a new customer. Configure Edit to open it with the intended customer's context, using supported Data Table and Form behavior.

5. Test Both Paths

For New, confirm that expected defaults appear and that submission creates the intended record.

For Edit, confirm that existing values load and the intended record is updated rather than a new record being created.

After successful submission, ensure that the Customers Page refreshes or otherwise reflects the change through its configured workflow.

Previewing and Testing

Test the Form through the same entry point that visitors will use, not only as an isolated layout.

Test	What to Verify
Open Form	The correct Form opens from the intended Page or Widget action.
Field Configuration	Labels, input types, options, required states, and bindings are correct.
New Record	Initial values are appropriate and submission creates the intended record.
Edit Record	Existing values load and the correct record is updated.
Required Fields	Missing required information is handled clearly.
Invalid Input	Supported formatting and business validation report understandable errors.
Submission Success	The Form shows accurate confirmation and the opening Page responds as intended.
Submission Failure	The Form displays a useful error and permits appropriate recovery.
Cancel / Close	Leaving the Form does not accidentally submit changes.
Responsive Layout	The modal is usable on desktop, tablet, and mobile.
Access Control	Different Project Users can perform only the operations they are authorized to perform.

When Preview is connected to real Project data or external services, test carefully: Form submissions can have effects beyond the visual preview.

Good Practices

• Start with the Form's field source. Confirm the table-backed or custom schema before placing fields.
• Prefer Form-specific field blocks. Use the generated blocks when values need to participate in Form operations.
• Design for one focused task. Keep the modal centered on one clear outcome.
• Use readable labels. Explain information from the user's perspective rather than exposing internal field names.
• Keep fields in a logical order. Group related inputs and avoid unnecessary steps.
• Make required information clear. Provide guidance where the expected value is not obvious.
• Use one clear primary action. Configure and verify its behavior rather than relying on its label.
• Treat success and error content as part of the design. Confirm that messages reflect actual workflow results.
• Preview from the opening Page. Include the surrounding Page's refresh or update behavior in testing.
• Apply Backend authorization. Keep sensitive decisions and protected data operations out of solely browser-side enforcement.
• Review on smaller screens. Modal space is constrained and multi-column layouts may need adjustment.

Common Mistakes

Avoid these patterns:

• Adding generic inputs for table-backed or custom Form fields without establishing their proper binding.
• Using a field label or element Name as though it automatically determines the underlying data field.
• Removing a generated field block and assuming its replacement inherits the same Form configuration.
• Forgetting to configure the Form's data source or custom field definitions before adding inputs.
• Designing fields without a clear submit action or meaningful status feedback.
• Showing a success message as soon as a Button is clicked, before the operation succeeds.
• Treating browser-side required fields, hidden inputs, or disabled Buttons as data security controls.
• Opening an Edit Form without identifying the record that should be updated.
• Using vague error messages that leave users unsure how to proceed.
• Forgetting to update a Data Table or other opening Page display after a successful submission.
• Testing only the happy path or only the desktop layout.

Form Layout and Fields works best when the visual structure, field bindings, validation, submission behavior, and feedback are designed together. The Form should make the task clear to the user while its configured data and workflow behavior reliably handle the result.

Related Topics

• Forms
• Table-Backed Forms
• Custom Forms
• Opening Forms as Modals
• Form Page Flow
• Element Library
• Layout Elements
• Buttons and Actions
• Selected Element Toolbar
• Element Settings
• Data Table Widget
• Page Flow
• Database
• Cloud Flow