Forms

Forms are specialized Pages for collecting information, validating user input, and completing focused workflows in an ioLoop Project.

Forms are typically opened as modals from another Page, a Data Table Widget, or a Page Flow interaction. This lets users complete a task without leaving the surrounding Page. A Form can create a new record, edit an existing record, collect a custom request, or gather information for further processing.

Common uses include:

• Adding or editing customers, orders, registrations, and other records.
• Updating profile information or an existing request.
• Submitting a support ticket or requesting a quote.
• Joining a waitlist or registering interest.
• Providing approval details, notes, or a response to a workflow.

A Form is managed alongside Pages and Structured Pages under Pages & Forms, but it is designed specifically for input and submission rather than general page content. For the differences between these types, see Page Types.

How Forms Fit Into a Project

A Form brings together a visual input interface, a data configuration, and—when needed—application behavior.

Concept	Role
Form	The specialized Page that provides the input experience.
Form Layout	The fields, labels, instructions, buttons, and status areas the user sees.
Table-Backed Form	Connects the Form to a Project Database table for record creation or editing.
Custom Form	Collects values using fields defined for the Form, with submission behavior configured for the workflow.
Opening Page	The Page or interface from which a user starts the modal workflow.
Page Flow	Coordinates browser-side behavior where needed, such as initialization, validation, context, or post-submission actions.
Database and Cloud Flow	Provide Project data storage and trusted Backend processing, subject to the appropriate permissions and rules.

For example, a Customers Page can display records through a Data Table Widget. Its New and Edit actions can open a customer Form. The Form handles the input task, and the opening Page can refresh the Data Table after the operation succeeds.

Typical Form Lifecycle

A Form workflow generally follows this sequence:

1. A user selects an action on a Page, such as Add Customer or Edit.
2. The configured action opens the Form as a modal. For an edit workflow, the Form receives or retrieves the context needed to identify the intended record.
3. The user reviews or enters values in the Form fields.
4. The Form validates the input and performs the configured submission behavior.
5. The Form displays an appropriate success or error state.
6. Where configured, the opening Page responds—for example, by refreshing a record list or updating a summary.

The exact submission behavior depends on the Form type and its configuration. Opening a Form, saving data, closing the modal, and refreshing the opening Page are related steps, but they should not be assumed to happen automatically in every workflow.

Form Types

ioLoop supports two main approaches to Form implementation.

Form Type	Best For	Data and Submission Approach
Table-Backed Forms	Creating or editing records associated with one Project table.	Fields are based on a selected Project Database table, with the Form configured for the relevant record operation.
Custom Forms	Collecting input for an application-specific request or process.	Fields are defined for the Form; the application workflow determines what happens to the submitted values.

Table-Backed Forms

Choose a Table-Backed Form when the information belongs directly in a Project Database table.

Examples include:

• Adding a customer to a Customers table.
• Editing a registration in a Registrations table.
• Updating contact information in a Members table.
• Creating or updating an order record in an Orders table.

A Table-Backed Form is generally the simpler starting point for these tasks because its fields are tied to the selected table. You still need to design the Form, choose the appropriate fields, configure the opening workflow, and verify that the intended user has permission to perform the record operation.

Custom Forms

Choose a Custom Form when collecting input is only one part of a broader process and the submitted information is not simply saved to one selected table.

Examples include:

• A request for a quotation that needs additional calculations.
• A support request sent through an external service.
• An approval workflow that evaluates several related records.
• A submission that requires trusted processing through Cloud Flow.

A Custom Form does not, by itself, define the complete business process. Configure the required submission and follow-up behavior using the supported Form and Page Flow capabilities, together with Backend processing where appropriate.

For a more detailed comparison, see Table-Backed Forms and Custom Forms.

Form Structure and Layout

Forms are designed in the Page Editor using a dedicated Form structure.

A typical Form is organized around a Form Block with these areas:

Form Area	Purpose
Form Block	Defines the Form's overall structure and whether its fields are table-backed or custom.
Form Fields Area	Contains the input fields, labels, help text, layout, submit controls, and supporting content.
Success Status Area	Presents confirmation or next-step information when the configured operation succeeds.
Error Status Area	Presents a useful error message or recovery guidance when the operation cannot complete.

The Form Fields Area is where most visual editing takes place. Like other Page content, it can use supported Page Elements and layout controls to arrange the interface.

Fields and Validation

A well-designed Form typically includes:

• A title or short instruction explaining the task.
• Input fields connected to the Form's data configuration.
• Clear labels and help text where necessary.
• Required-field indicators and appropriate input validation.
• A primary submit action and any necessary secondary actions.
• Meaningful success and error messages.

In a Table-Backed Form, fields are based on the selected Project table. In a Custom Form, the field definitions belong to the Form itself.

The label shown to a user and the field receiving the value serve different purposes. For example, an input labeled Customer Name should be connected to the appropriate data field, rather than relying on its visible label to identify the stored value.

Use built-in field validation where it meets the requirement. Add Page Flow when the workflow needs more specialized checks or processing. For security-sensitive rules, validation in the browser is not a substitute for trusted Backend enforcement.

For the detailed layout, field, validation, and status-area workflow, see Form Layout and Fields.

Opening Forms as Modals

Forms are generally used as modal input experiences initiated by another Page or workflow.

Typical opening points include:

Opening Point	Example
Page Button	An Add Customer button opens a new-customer Form.
Data Table New action	Opens a Form to create a record.
Data Table Edit action	Opens a Form for the record selected in the table.
Page Flow	Opens a Form in response to a supported event or a preceding workflow step.

The Page that opens the modal provides the surrounding context. The Form provides the focused input experience.

Passing Context to a Form

Some Forms need information from the opening Page.

For example:

• An Edit Form needs to know which record is being edited.
• A support request may be associated with a selected order.
• An approval Form may need an identifier for the request being reviewed.
• A registration Form may need context about the event selected on the opening Page.

Configure this relationship through the supported Form-opening and Page Flow mechanisms. Do not assume that selecting an element or opening a modal automatically passes every value available on the opening Page.

After the Form Completes

The intended result of a submission should be clear to both the user and the surrounding Page.

On success, the workflow may close the modal, refresh a Data Table, update displayed information, or continue to another step. On failure, it should communicate that the operation did not complete and let the user recover appropriately.

Also consider how users cancel or close a Form before submitting. Closing a modal should not be confused with saving the entered values.

For implementation patterns, see Opening Forms as Modals.

Forms and Page Flow

Page Flow runs in the browser and is used when a Form needs interaction or workflow behavior beyond its basic configuration.

There are two related but distinct contexts:

Page Flow Context	Typical Responsibility
Opening Page Page Flow	Initiates the modal, supplies relevant context, and updates the opening Page after the Form completes.
Form Page Flow	Initializes the Form, works with its fields, performs additional validation or custom submission behavior, and manages Form-specific outcomes.

A Form does not necessarily need a custom Page Flow for every ordinary table-backed operation. Use additional Page Flow logic when the experience requires it.

Common reasons to add Form Page Flow include:

• Setting default or initial field values.
• Reading or updating fields during the interaction.
• Validating relationships between multiple inputs.
• Working with information passed from the opening Page.
• Handling a Custom Form's submission workflow.
• Invoking supported Project data operations or Cloud Flow.
• Coordinating success, failure, and subsequent actions.

Page Flow is appropriate for client-side interaction. Operations involving protected credentials, sensitive authorization decisions, or trusted business rules belong in the appropriate Backend configuration or Cloud Flow.

For the Form-specific guidance, see Form Page Flow. For the broader programming model, see Page Flow.

Creating and Using a Form

A typical implementation workflow is:

1. Open Pages & Forms in the Project Editor and create a new item of type Form.
2. Decide whether the Form should be table-backed or custom, and configure the corresponding data setup.
3. Open the Form in the Page Editor and build its Form Fields Area.
4. Connect the input elements to the required table fields or custom field definitions.
5. Configure required fields, validation guidance, submit controls, and the Success and Error Status Areas.
6. Add Form Page Flow when the submission or interaction requires additional logic.
7. Configure a Page button, Data Table action, or Page Flow interaction to open the Form as a modal.
8. Configure any necessary context passing and follow-up actions on the opening Page.
9. Save and Preview the complete experience, including success, failure, cancellation, and mobile behavior.
10. Publish the Project when the workflow has been tested and is ready for application users.

The exact configuration varies by Form type. The detailed child pages explain the relevant fields, settings, and workflow behavior.

Example: Customer Management

Consider a customer management application with a Customers Page and a Project Database table named Customers.

1. Display the Customers

Add a Data Table Widget to the Customers Page and configure it to display the fields users need, such as Name, Email, Phone, and Status.

2. Create a Customer Form

Create a Table-Backed Form associated with the Customers table. Add the fields needed to create or edit a customer and configure useful success and error messages.

3. Connect New and Edit Actions

Configure the Data Table's New action to open the Form for a new record. Configure Edit to use the selected customer record, so the intended values can be loaded and updated.

4. Handle the Result

After a successful create or update operation, configure the opening Page to refresh the Data Table so the current information becomes visible. If the operation fails, keep the failure clear and avoid presenting the change as completed.

This pattern combines a record-oriented Widget with a focused modal Form. It avoids turning the entire Customers Page into an editing interface.

Choosing the Right Form Approach

If You Need To...	Start With...
Create a record in one Project table	Table-Backed Forms
Edit an existing record	Table-Backed Forms
Collect inputs for a custom business workflow	Custom Forms
Design fields, labels, layouts, or status messages	Form Layout and Fields
Open a Form from a Page or Data Table	Opening Forms as Modals
Pass context or configure Form-specific behavior	Form Page Flow
Enforce trusted business rules or protected processing	Cloud Flow

Previewing and Testing Forms

Preview the complete modal workflow from the same Page or action that users will use in the published application.

Check the following cases:

• Opening: The intended Form opens and receives the expected context.
• New and Edit: New records start with appropriate values, while edit workflows load the intended record.
• Validation: Missing or invalid values are handled clearly.
• Success: The Form confirms completion only after the relevant operation succeeds.
• Errors: Failures provide usable feedback and do not imply that data was saved.
• Cancel and Close: Leaving the Form does not accidentally trigger the submission.
• Opening Page: Tables, summaries, or other Page content are refreshed or updated where configured.
• Responsive Layout: Fields, actions, and messages remain usable on desktop, tablet, and mobile screens.
• Permissions: The intended Project Users can perform only the data operations authorized for them.

A Form can look correct when previewed by itself but still fail when opened with missing context or when the surrounding Page does not respond to its result. Test the complete interaction before publishing.

Access and Data Protection

Forms are user-interface components, not security boundaries.

A Form may collect data that belongs in a Project Database table or passes through a custom workflow. Apply the relevant Database permissions and trusted authorization checks to the underlying operations.

For protected workflows:

• Use the Project's Page access configuration where appropriate.
• Enforce record access and modification permissions independently of hidden or disabled fields.
• Keep provider credentials and trusted business processing outside browser-side Page Flow.
• Validate important rules through the appropriate Backend capabilities before committing protected changes.

For example, hiding an administrative field in a Form does not prevent a user from attempting an unauthorized update through another route. Authorization must be enforced by the data or Backend operation itself.

For further information, see Page Settings, Database, and Cloud Flow.

Good Practices

• Keep each Form focused. Design the modal around one clear task and an obvious primary action.
• Choose the simplest appropriate Form type. Start with a Table-Backed Form for ordinary record creation or editing, and use a Custom Form when the workflow requires it.
• Configure meaningful status areas. Success and Error Status Areas should explain what happened and what the user can do next.
• Use clear labels and validation guidance. Make required information and recovery steps understandable.
• Separate responsibilities. Let the Form handle input, the opening Page coordinate its surrounding interface, and trusted Backend capabilities enforce protected rules.
• Reuse Forms where useful. A common Form can support consistent interactions from different opening points when those workflows are configured appropriately.
• Test with realistic data. Include existing records, missing values, long text, errors, and different user permissions.
• Design for constrained space. Keep modal layouts practical on smaller screens.

Common Mistakes

Avoid these patterns:

• Choosing a Custom Form for ordinary single-table record editing without a reason for custom processing.
• Assuming that adding a field visually connects it to a table or custom field definition.
• Assuming that a Custom Form automatically stores its submissions.
• Treating the opening Page's Page Flow and the Form's Page Flow as the same workflow context.
• Opening an Edit Form without supplying or resolving the intended record context.
• Assuming a successful submission automatically refreshes every related Page or Widget.
• Showing a success message before the operation has actually completed.
• Relying on hidden fields, client-side checks, or modal visibility to enforce permissions.
• Testing only a successful desktop submission and overlooking errors, cancellation, or mobile layout.

Forms are most effective when the input layout, data configuration, modal interaction, and submission outcome work together as one clear user experience.

In This Section

Topic	What You Will Learn
Form Layout and Fields	Organize the Form Block, connect input fields, design validation guidance, and configure success and error areas.
Table-Backed Forms	Create and edit records associated with a selected Project Database table.
Custom Forms	Collect and process values through a custom application workflow.
Opening Forms as Modals	Open Forms from Pages and Widgets, provide context, and handle the modal result.
Form Page Flow	Configure Form initialization, field behavior, validation, submission, and status handling.

Technical Reference

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

• Form Page Flow Blocks
• $io.form API
• $io.ui.showFormModal
• Page Actions

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

Related Topics

• Pages & Forms
• Managing Pages
• Page Types
• Page Editor
• Element Library
• Element Settings
• Data Table Widget
• Page Flow
• Database
• Cloud Flow