Custom Forms

Custom Forms collect values through fields defined for the Form itself, rather than fields supplied by one selected Project Database table.

Use a Custom Form when the input is part of a broader workflow: a request, approval, service call, calculation, multi-step process, or submission that needs custom handling before anything is saved.

Common uses include:

• Request a Quote.
• Submit a Support Request.
• Send an Approval Response.
• Collect Preferences.
• Start a Service Request.
• Gather information for Cloud Flow processing.
• Submit information to an external service through a configured workflow.

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

When to Use a Custom Form

Use a Custom Form when the submitted values are not simply creating or updating one Project table record.

Requirement	Recommended Approach
Collect values for a custom workflow	Custom Form
Run calculations or decision logic before saving	Custom Form with Page Flow or trusted Backend processing
Submit information to an external service	Custom Form with the appropriate Integration or Backend workflow
Collect approval or review details	Custom Form
Create or edit one record in one Project table	Table-Backed Form
Use fields already defined by a Project table	Table-Backed Form

For example, a Request a Quote Form might collect service type, budget range, timeline, contact details, and project notes. The submission may then call Cloud Flow, send a notification, create records, or route the request based on the submitted values.

A Custom Form is useful when the Form's input is the start of a process, not the whole process. It does not automatically persist submitted values merely because the user completed the Form.

How Custom Forms Work

A Custom Form combines its own field definitions with a configured submission workflow.

Part	Responsibility
Custom Field Definitions	Define the values the Form collects.
Form Layout	Presents those fields, labels, help text, submit controls, and status areas.
Form Page Flow	Coordinates custom initialization, validation, submission, and result behavior where needed.
Backend or Integration Workflow	Performs trusted processing, external calls, or protected operations where required.

The overall process is:

Custom Form Fields
  Define values the Form collects
          |
          v
Form Layout
  Presents inputs and submit action
          |
          v
Form Submission
  Validate and run configured behavior
          |
          +---- Failure ----> Error Status Area / recovery
          |
          +---- Success ----> Success Status Area / next action

The diagram describes the responsibilities involved. It is not a specific Page Flow block sequence. The final outcome depends on the workflow configured for that Form.

Custom Forms vs. Table-Backed Forms

The key difference is where the Form's field definitions and submission responsibility come from.

Area	Table-Backed Form	Custom Form
Field source	A selected Project Database table.	Field definitions configured for the Form.
Typical purpose	Create or edit one table record.	Collect input for a custom workflow.
Submission expectation	Record creation or update in the selected table.	Workflow-specific processing.
Best fit	Standard record management.	Requests, approvals, service calls, calculations, or multi-step actions.

Choose the simpler table-backed approach when the task is truly a record create or update. Choose a Custom Form when the workflow needs to decide what happens after the user submits the values.

Before You Begin

Before creating a Custom Form, define the workflow the Form supports.

Confirm:

• What information the Form must collect.
• Which fields are required.
• Which values need selectable choices.
• Whether the submission creates records, calls Cloud Flow, sends data to an Integration, or only affects the current Page workflow.
• Which success and error messages users should see.
• What should happen to the opening Page after the Form succeeds.
• Which operations require trusted Backend processing or authorization.

Do not start only from the visual layout. A Custom Form's usefulness depends on the submission behavior as much as the fields.

Define What Success Means

Before building the Form, decide what successful submission must accomplish.

Example Workflow	Success Means
Quote request	The request has been accepted by the configured processing workflow.
Approval response	The response has been recorded or processed by the intended operation.
Service intake	The service request was created or successfully passed to the next step.
Calculation request	The requested calculation completed and the result is available.
External submission	The configured external operation reported an appropriate successful outcome.

Do not use the same success message for every workflow. For example, Request received may be accurate even when a team still needs to review and approve the request. Service booked would be misleading unless the booking was actually confirmed.

Creating a Custom Form

A typical setup 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 custom workflow.
3. Open the Form in the Page Editor.
4. Select the Form Block and configure it as a Custom Form.
5. Define the custom fields the Form should collect.
6. Select the Form Fields Area.
7. Add field blocks for the custom fields.
8. Arrange the fields and add labels, helper text, instructions, and submit controls.
9. Design the Success Status Area and Error Status Area.
10. Configure Form Page Flow for validation, submission, and result handling where needed.
11. Configure the Page, Button, or Page Flow behavior that opens the Form as a modal.
12. Save and Preview the complete workflow from the opening Page.

The exact field controls depend on the custom field definitions and supported Form settings. Use the options shown for the selected Form.

The Form Block defines the Form's data approach. The Form Fields Area contains the visible controls, and the Success Status Area and Error Status Area provide feedback. Configure all three areas even when the submission logic is handled elsewhere.

Saving the Form retains development changes. It does not by itself publish the changed application. Test through Preview and publish the Project when the workflow is ready.

Defining Custom Fields

Custom fields define the values the Form collects.

Examples include:

Form Purpose	Example Custom Fields
Quote Request	Service Type, Budget Range, Timeline, Project Notes, Contact Email
Support Request	Issue Type, Priority, Description, Related Order
Approval Response	Decision, Reviewer Notes, Requested Change
Service Intake	Location, Preferred Date, Contact Method, Special Instructions
Feedback Form	Rating, Category, Comments, Follow-Up Permission

Define only the fields the workflow needs. If the workflow later creates or updates Database records, it can map submitted values to the appropriate operation.

Field Design Guidance

Field Need	Guidance
Short text	Use for names, titles, identifiers, and concise responses.
Long text	Use for notes, descriptions, requests, and explanations.
Choice fields	Use when users should select from known options.
Yes/no values	Use for confirmation, opt-in, or simple decisions.
Dates or numbers	Use appropriate supported field types where available.
Sensitive information	Collect only what is necessary and process it through the appropriate trusted workflow.

Custom Form fields should be understandable to both the user completing the modal and the person maintaining the workflow later.

Field Definitions, Visible Labels, and Element Names

These concepts have different purposes:

Concept	Purpose	Example
Custom Field Definition	Identifies the value collected by the Form and the supported field behavior.	A field representing ContactEmail.
Field Label	Explains to the visitor what to enter.	Email Address.
Form Field Block	Presents the connected input control inside the Form Fields Area.	An email input linked to the contact email field.
Element Name	Helps a Creator identify a Page Element for editing or supported Page Flow references.	QuoteContactEmailField.

The display label and element Name do not automatically define which custom field is submitted. Use the Form-specific field block and confirm its connection to the intended custom field.

For example, changing a visible label from Contact Email to Work Email should not be assumed to rename the underlying value expected by the submission workflow.

Changing Field Definitions

If a custom field is added, renamed, or removed after Page Flow has been configured, review the field blocks and any logic that reads or supplies its value. A visual control may remain on the Page even when the workflow no longer receives the value it expects.

Review required-field behavior, choice options, and defaults whenever you change the custom field setup.

Adding Custom Fields to the Layout

After defining the fields, add the corresponding field blocks to the Form Fields Area.

For example:

Form Block (Custom Quote Request)
  Form Fields Area
    Heading (Request a Quote)
    Text (Tell us about the project.)
    Form Field Block (Service Type)
    Form Field Block (Budget Range)
    Form Field Block (Timeline)
    Form Field Block (Project Notes)
    Form Field Block (Contact Email)
    Button (Submit Request)
  Success Status Area
    Text (Your request was submitted.)
  Error Status Area
    Text (We could not submit the request.)

This is a conceptual layout. The visible Button text and field labels do not, by themselves, define the workflow that processes the submission.

Prefer Form-specific field blocks for values that should participate in the Custom Form's validation and submission behavior. If you add generic inputs, confirm how their values are read and used by the workflow.

Static Content Versus Collected Values

Headings, explanatory Text, and helper messages can remain ordinary Page Elements. They do not need custom field definitions unless their content is intended to become a submitted value.

For example, Tell us about your project is an instruction, while the visitor's Project Notes should be collected through an appropriately connected field.

Required and Optional Values

Make required fields recognizable in the interface and confirm that their validation matches the configured field definition or Page Flow rule. For optional values, decide how the workflow should handle an empty response rather than assuming every field will have a value.

A Form should collect only information relevant to its stated purpose. Do not add fields solely because an external integration or Database table has additional fields that the visitor should not supply.

Submission Behavior

A Custom Form does not automatically save to one selected table. Its submitted values must be handled by the configured workflow.

Possible outcomes include:

• Calling Cloud Flow to process the request.
• Creating one or more Database records through a trusted workflow.
• Sending information to an external service through an Integration.
• Updating the opening Page or a visible workflow state.
• Showing a success message and letting a team handle the request elsewhere.

The correct behavior depends on the application. Define the outcome explicitly rather than assuming submission means “save.”

Submission Lifecycle

A typical Custom Form submission involves these stages:

1. The visitor opens the Form and enters values.
2. The Form applies supported required-field and format checks.
3. Form Page Flow performs any additional browser-side checks or prepares the submission data.
4. The configured Project data operation, Cloud Flow, or Integration processes the request as needed.
5. The Form receives or determines the result of the configured operation.
6. The Success Status Area or Error Status Area presents the appropriate outcome.
7. The opening Page closes the modal, refreshes content, or advances the workflow when configured to do so.

A submission is not complete merely because the visitor clicked Submit or client-side validation passed. Wait for the relevant operation to report its outcome before presenting a success message.

Prepare Values for the Workflow

The custom fields define what the Form collects. The processing workflow determines how those values are used.

For a quote request, the Form may collect Service Type, Budget Range, Timeline, Project Notes, and Contact Email. The workflow can then associate those values with a request record, prepare an external call, or perform an appropriate calculation.

This mapping must be configured deliberately. A similarly named field in a Database table or Integration does not establish an automatic connection.

For details about the supported Form and Page Flow operations, see Form Page Flow and Page Flow.

Validation

Custom Forms should validate input before the workflow continues.

Common validation concerns include:

Validation Concern	Example
Required value	Contact Email must be provided.
Supported format	Email Address should be in an email format.
Allowed choice	Priority must be one of the configured choices.
Cross-field rule	Preferred End Date should not be before Preferred Start Date.
Workflow rule	A selected service must be available in the user's region.

Use built-in field validation where it fits. Use Page Flow when the Form needs extra checks before submission.

Where Validation Belongs

Validation Layer	Purpose
Field configuration	Required values, supported formats, and field-specific constraints.
Form Page Flow	User-facing checks that involve multiple fields or the current Form state.
Trusted Backend behavior	Authorization, protected business rules, and conditions that must be enforced regardless of browser input.

For example, Page Flow might warn that a requested service date precedes today's permitted range. If the business must strictly reject unavailable dates or enforce account-specific eligibility, the trusted operation processing the request must make that decision as well.

For protected rules, use trusted Backend processing. Browser-side validation can improve the user experience, but it must not be the only enforcement for security-sensitive decisions.

Page Flow with Custom Forms

Custom Forms commonly use Form Page Flow because the submission is workflow-specific.

Use Page Flow when you need to:

• Set initial field values when the modal opens.
• Read submitted values.
• Validate relationships between fields.
• Prepare data for Cloud Flow or another Project capability.
• Call trusted Backend behavior.
• Set the success or error message.
• Decide what should happen after the workflow completes.
• Use context from the opening Page.

Page Flow can coordinate the browser-side experience. When the workflow involves protected credentials, authorization, external provider operations, or data changes that must be trusted, route that work through the appropriate Backend or Integration capability.

Form Page Flow and Opening Page Flow

A modal workflow can involve two distinct Page Flow contexts:

Context	Typical Responsibility
Opening Page	Starts the modal, provides supported request context, and updates the surrounding Page when the Form completes.
Custom Form	Initializes Form values, coordinates field validation, submits values through the configured workflow, and communicates success or failure.

For example, a Product Page may open a Request a Quote Form using the currently selected product as context. The Custom Form collects the visitor's details and submits the request. After a confirmed success, the opening Page may update its interface or allow the modal to close.

The existence of Page Flow on both sides does not mean they automatically share every variable or value. Use the supported modal-opening and context mechanisms for the selected workflow.

For Form-specific lifecycle guidance, see Form Page Flow.

Passing Context Into a Custom Form

The opening Page may provide context that helps the Custom Form behave correctly.

Examples include:

Opening Context	Possible Use
Selected product	Ask for a quote about that product.
Selected order	Start a support request related to that order.
Current category	Preselect a request type.
Current Project User	Personalize or associate the submission where appropriate.
Prior Page choice	Continue a multi-step workflow.

Only pass the context the Form needs. Treat browser-provided values as input to validate, not proof of permission or identity.

For example, a provided OrderId can indicate which order the visitor is asking about. It does not prove that the visitor is authorized to view or modify the order. Any protected operation must independently enforce the required access rules.

Defaults and Pre-Filled Values

When supported by the Form and opening workflow, context can supply starting values such as a selected category, service, or product. Distinguish these from values the visitor is expected to confirm or change.

When the same Form can be opened from several Pages, test each entry point. The starting context may differ, but the Form's required fields and submission responsibilities should remain clear.

For modal-opening patterns, see Opening Forms as Modals.

Success and Error Feedback

Custom Forms should clearly communicate the result of the configured workflow.

The Success Status Area should confirm what happened:

• Your request was submitted.
• Your approval response was saved.
• We received your message.

The Error Status Area should help the user recover:

• We could not submit the request. Review the required fields and try again.
• The approval response could not be processed. Refresh the page and try again.
• The service is temporarily unavailable. Try again later.

Show success only after the configured workflow reports success. A user selecting Submit does not necessarily mean the request was processed.

Processing and Repeated Submissions

For operations that may take time, provide understandable progress feedback where the supported UI and workflow allow it. Help visitors distinguish a request still being processed from one that failed or finished.

If the submission creates records, sends notifications, or calls an external provider, repeated clicks or retries may cause duplicate operations. Where supported, disable or otherwise guard the submit action while processing. For important workflows, enforce duplicate protection in trusted processing as needed; a disabled browser Button alone is not sufficient.

When a submission fails, keep appropriate values available for correction or retry where supported. Do not show a success state and silently drop the request.

Custom Forms and Backend Processing

Use trusted Backend behavior for work that should not be performed only in the browser.

Examples include:

• Writing records that require protected authorization.
• Calling external services.
• Processing payments or provider-specific operations.
• Using private credentials.
• Enforcing business rules.
• Sending notifications.
• Making decisions that must not be controlled by the user's browser.

Page Flow can gather values and initiate the workflow. Supported Project data operations may also be invoked from Page Flow where Database access rules permit. Use Cloud Flow or another trusted mechanism when operations require protected credentials, authoritative authorization, or business rules that cannot be entrusted to the browser.

A Custom Form is not automatically an authorization boundary. Page access restrictions, Database permissions, and Backend checks must be configured for the operations involved.

Example: Approval Response

A Custom Form could collect Decision and Reviewer Notes. The visible Form might offer Approve or Reject choices, but the trusted processing must determine whether the signed-in Project User is allowed to make that decision for the particular request.

Passing a request ID or hiding the approval control is not proof of permission. For approvals with consequential effects, validate the permitted reviewer, the request's current state, and the result of the operation before confirming success.

Example: Building a Request a Quote Form

Consider an application with a Services Page. A visitor can select a service and request pricing from the Project team.

1. Define the Workflow Outcome

Decide what the Form should accomplish. In this example, successful submission means the request is accepted by a configured workflow, which records the request and optionally sends a notification. It does not mean that a quote has already been approved or issued.

2. Create and Configure the Custom Form

Create a Form in Pages & Forms, open it in the Page Editor, select the Form Block, and use the custom field approach.

Define fields appropriate to the request:

Custom Field	Visitor-Facing Label	Purpose
Service Type	Service	Identifies the requested service.
Budget Range	Estimated Budget	Provides pricing context.
Timeline	Preferred Timeline	Describes when the service is needed.
Project Notes	Project Details	Collects additional requirements.
Contact Email	Email Address	Provides a contact channel.

These are example names and labels, not mandatory ioLoop field identifiers.

3. Build the Modal Layout

Add connected Form-specific field blocks to the Form Fields Area, with a short introduction and a Submit Request action. Keep the fields in a logical sequence and mark essential information as required.

Design the Success Status Area with a message such as:

Your quote request has been received. Our team will review the details.

Design the Error Status Area with a message that helps the visitor retry if processing fails.

4. Open the Form with Context

Add a Request a Quote control to the Services Page. Configure it to open the Custom Form as a modal. If supported by the opening workflow, provide the selected service as initial context so the visitor does not need to identify it again.

5. Configure Submission Processing

Use Form Page Flow to coordinate validation and the configured request operation. For example, a trusted Cloud Flow workflow may record the quote request and notify the appropriate team.

Treat the request as successful only after the operation reports the intended result. If processing fails, display the error state without claiming that the request was submitted.

6. Update the Opening Page

When the Form completes successfully, the opening Page can close the modal or update a relevant status message through its configured workflow. Do not assume that these actions happen automatically.

7. Preview the Entire Experience

Test the Services Page, modal opening, field validation, successful and failed processing, responsive layout, and any resulting Page update. Use appropriate test data because Preview may invoke real Project operations.

The example illustrates an application workflow, not a prescribed Page Flow block sequence or Cloud Flow API.

Responsive and Accessible Form Design

Custom Forms are often used in constrained modal space, so avoid making every field depend on a wide desktop layout.

• Use a clear title and a short description of what will happen after submission.
• Group related fields and place the most important inputs first.
• Prefer readable single-column arrangements for essential inputs on mobile.
• Keep long-text fields large enough to review entered content.
• Use meaningful labels and clear indications of required fields.
• Make the submit control easy to find and distinguish it from Cancel or Close.
• Ensure errors can be understood without relying only on color.
• Check keyboard and touch interactions with the chosen input controls.

Preview desktop, tablet, and mobile widths. Review the modal itself, not just how the Form appears within the Page Editor.

Previewing and Testing

Preview the Custom Form from the Page or workflow that opens it.

Test these cases:

Case	What to Verify
Opening	The intended Form opens as a modal.
Context	Values from the opening Page are available where expected.
Required fields	Missing values produce clear validation feedback.
Workflow submission	The configured processing runs with the expected submitted values.
Success state	The Form confirms success only after the workflow succeeds.
Error state	Failures show a useful recovery message.
Opening Page update	The surrounding Page refreshes or updates where configured.
Cancel and close	Leaving the modal does not accidentally submit the workflow.
Permissions	Protected operations are allowed only for the intended users.
Responsive layout	The modal remains usable on desktop, tablet, and mobile widths.
Repeated submission	Accidental double clicks or retries do not cause unintended duplicate operations.
Backend failure	A rejected, unavailable, or timed-out operation does not display success.
Sensitive information	The Form exposes and transmits only information needed for the intended workflow.

Use realistic values when testing. Include long notes, missing optional values, invalid formats, and any unavailable-service or failure case the workflow should handle.

Preview can perform real operations. If a Custom Form writes Project data, sends email, or calls external services, use an appropriate test context and verify the affected records or recipients. Saving the Form does not itself publish changes.

Common Issues and Troubleshooting

Issue	What to Check
A custom field does not appear	Confirm that it was defined for the Form and that the corresponding field block was added to the Form Fields Area.
A value is visible but missing from submission	Verify the Form-specific field connection or how a generic input's value is read by Page Flow.
Submitting does nothing	Check the submit control's configured behavior, Form Page Flow, and the operation responsible for processing the values.
Validation rejects an expected value	Review required rules, accepted formats, choice values, and cross-field checks.
The Form always shows success	Confirm that the success state depends on the actual result of the configured operation.
The request reaches the wrong record or service	Check the opening Page's context, field mapping, and the trusted operation's target.
A processing failure loses the visitor's work	Review error handling and whether entered values remain available for correction or retry where supported.
Duplicate requests are created	Review repeated submit actions and any required duplicate protection in trusted processing.
The opening Page does not update	Confirm the configured completion behavior; closing a Form is not necessarily a Page refresh.
The modal is difficult to complete on mobile	Review layout width, Rows and Columns, input sizing, button placement, and status-message visibility.

Good Practices

• Start with the workflow outcome. Decide what should happen after submission before designing every field.
• Collect only needed values. Avoid asking for information the workflow does not use.
• Use clear field labels. Users should understand what to enter and why.
• Keep the modal focused. A Custom Form should still support one clear task.
• Handle protected work in Backend capabilities. Do not rely on browser-side logic for sensitive operations.
• Design success and error states. The result is part of the Form experience.
• Test failure paths. Custom workflows often depend on external data, integrations, or backend processing.
• Confirm actual success. Show completion only when the configured operation reports the intended outcome.
• Pass minimal context. Treat any browser-supplied identifiers and values as untrusted input.
• Avoid unnecessary repeats. Account for duplicate submissions when processing can create records or trigger external actions.

Common Mistakes

Avoid these patterns:

• Using a Custom Form when a Table-Backed Form would directly create or edit one table record.
• Defining fields without deciding what the submission should do.
• Assuming that a submit button automatically saves the values somewhere.
• Handling protected business rules only in browser-side Page Flow.
• Collecting sensitive information without a clear processing and access plan.
• Showing success before the workflow has actually completed.
• Forgetting to test the Form from the Page that opens it.
• Building a long Custom Form when the workflow should be split into clearer steps.
• Assuming a Form field label or element Name automatically maps values to a Project Database field or Integration.
• Treating information supplied by the opening Page as proof that a visitor is authorized to act.
• Failing to account for accidental repeat submissions or retries.

Custom Forms are best for input-driven workflows where the submitted values need custom handling. Keep the field definitions, modal layout, Page Flow behavior, and trusted processing aligned so the user gets a clear result.

Related Topics

• Forms
• Form Layout and Fields
• Table-Backed Forms
• Opening Forms as Modals
• Form Page Flow
• Page Flow
• Cloud Flow
• Database
• Element Library
• Element Settings
• Integrations