Opening Forms as Modals

Forms are designed to be used as modal workflows. A user starts an action from a Page, the Form opens in front of that Page, and the user completes a focused input task without leaving the surrounding context.

Use modal Forms for tasks such as adding a record, editing a selected record, submitting a request, providing approval details, or collecting information for a custom workflow.

Common opening points include:

• A Button on a Page.
• A Data Table Widget New action.
• A Data Table Widget Edit action.
• A Page Flow interaction after another event.
• A custom action in a workflow.

For designing the Form itself, see Form Layout and Fields.

A Form is created and maintained as a separate item under Pages & Forms, then opened from an appropriate Page interaction. Its visual layout, fields, and status areas belong to the Form. The opening Page decides when the modal is needed and what should happen around it.

Some Page Elements and Widgets support built-in actions for opening Forms. Page Flow is useful when opening the Form requires additional logic, values from the current Page, or handling after the Form completes. Not every simple modal needs a custom workflow on both sides.

How Modal Form Workflows Fit Together

A modal Form workflow has two sides:

Side	Responsibility
Opening Page	Starts the workflow, provides context where needed, and responds after the Form succeeds, fails, or closes.
Form	Collects values, validates input, submits or coordinates the configured behavior, and returns an outcome.

The opening Page and the Form are separately managed items under Pages & Forms. Each can have its own Page Flow. The opening Page's Page Flow can open the modal and coordinate its response to the result where the selected opening mechanism supports that interaction. The Form's Page Flow can initialize fields, validate values, process submission behavior, and set success or error feedback.

This separation matters. A Button on the opening Page does not automatically know how the Form submits values, and the Form does not automatically know how the opening Page should refresh or update afterward. Configure both sides of the workflow where needed.

Before Configuring a Modal Opening

Prepare the Form and the intended user interaction before wiring them together:

1. Create or identify the Form. Choose a Table-Backed Form for direct record creation or editing, or a Custom Form for workflow-specific processing.
2. Configure its fields and outcomes. Make sure the Form has the inputs, validation, submit control, and Success and Error Status Areas required for the task.
3. Choose the starting point. Decide whether the Form opens from a Button, a Data Table action, or another Page Flow interaction.
4. Choose the intended mode. For a table-backed workflow, determine whether the user will create a new record or edit an existing one.
5. Identify required information. Separate existing-record edit data from shared context such as a selected product, event, or parent record.
6. Plan the result. Decide whether the opening Page should refresh data, show a confirmation, continue a workflow, or leave its content unchanged.
7. Check permissions. Confirm that intended Project Users have access to the underlying data or operations, independently of whether a modal-opening control is visible.

This preparation avoids a common problem: the modal opens and looks correct, but does not have enough information to initialize or complete its workflow.

Typical Modal Flow

A common Form modal workflow follows this sequence:

1. The user selects an action, such as Add Customer, Edit, or Request Quote.
2. The opening Page opens the intended Form as a modal.
3. The opening workflow passes any needed information, such as edit data for a selected record and/or shared context for the Form workflow.
4. The Form initializes its fields.
5. The user enters or reviews information.
6. The Form validates and submits according to its configuration.
7. The Form reports success, failure, or close/cancel.
8. The opening Page responds, such as refreshing a Data Table or showing updated content.

The exact behavior depends on the Form type and the configured Page Flow or Widget interaction.

Opening Page
  Button, Data Table action, or Page Flow event
          |
          v
Modal Form
  Fields, validation, submission, status areas
          |
          v
Result
  Success, error, close, or cancel
          |
          v
Opening Page response
  Refresh, update, continue, or do nothing

This diagram explains responsibilities. It is not a specific Page Flow block sequence.

Understanding Modal Outcomes

A modal-opening workflow may need to distinguish several different outcomes:

Outcome	Meaning	Typical Opening Page Response
Success	The configured Form operation has completed successfully.	Refresh relevant data, update content, show confirmation, or continue.
Error	Validation or processing prevented successful completion.	Let the Form present recovery guidance; do not show a completed state.
Close	The modal was dismissed.	Return to the opening Page and clear temporary interface state if appropriate.
Cancel	The user chose not to continue.	Leave existing data unchanged and avoid success-only actions.

These are workflow outcomes, not a promise that every modal-opening mechanism exposes four separate result events. Configure responses through the actions and Page Flow capabilities available to the selected opening pattern.

A successful click is not the same as a successful submission. Opening the Form, selecting Submit, completing Backend processing, and closing the modal are different events. When a Page needs to refresh or advance after a completed operation, connect that response to the supported success behavior rather than to a generic modal close.

Opening from a Button

A Button can start a modal Form workflow through Page Flow.

Use this pattern when the Page has a clear action such as:

• Add Customer
• Request Quote
• Contact Us
• Submit Feedback
• Start Approval
• Update Details

A typical Button-driven workflow is:

1. Add a Button to the opening Page.
2. Give the Button a clear label that describes the task.
3. Configure Page Flow for the Button action.
4. Open the intended Form as a modal.
5. Pass any context the Form needs.
6. Respond to the Form result after success, failure, close, or cancel.

For example, a Request Quote Button can open a Custom Form that collects the request details. After successful submission, the opening Page may show a confirmation, refresh a section, or simply leave the user on the same Page.

For Button guidance, see Buttons and Actions.

Buttons That Need Context

A Button can open the same Form for different situations. For example, a product detail Page can offer Request Quote, while a customer portal can offer Ask About This Product. Both might open one Custom Form but pass a different selected product and request type as shared context.

If the Form requires information from the current Page, configure the Button's supported interaction or Page Flow to supply it. The Button label alone does not pass the product, user, or record information to the Form.

When a Button opens an Edit Form, the opening workflow must also provide the intended existing record data or the supported record reference needed by the Form. This is different from opening a new-record Form with preset values.

Opening from a Data Table

The Data Table Widget commonly opens Forms for record-oriented actions.

Data Table Action	Typical Form Workflow
New	Open a Form for creating a record.
Edit	Open a Form for updating the selected record.
Custom row action	Open a Form or workflow related to the selected row.

New Record

A New workflow usually opens a table-backed Form in a new-record context.

Example:

1. The user selects New in a Customers table.
2. The configured Customer Form opens as a modal.
3. The Form starts empty or with configured defaults.
4. The user enters the customer details.
5. The Form creates the record if submission succeeds.
6. After a successful submission, the configured opening workflow refreshes the Customers table so the new record is visible.

Use Table-Backed Forms when the New action directly creates a record in one Project table.

Edit Record

An Edit workflow must identify the selected record.

Example:

1. The user selects Edit for a row in an Orders table.
2. The configured Order Form opens as a modal.
3. The Form receives the selected record context.
4. Connected fields show the existing values where supported.
5. The user changes allowed fields and submits.
6. The intended record is updated if the operation succeeds and access rules allow it.
7. After a successful update, the configured opening workflow refreshes the Orders table so the changed value is visible.

Record identity is important. The workflow must update the intended record, not merely a record with similar visible values.

Reusing One Form for New and Edit

Where the configured Form and opening mechanism support both modes, the same table-backed Form layout can serve New and Edit actions. The displayed fields may be similar, but the operation is different:

• New starts without an existing record to update. It may receive defaults or shared context and ultimately creates a record.
• Edit must preserve the identity of an existing record. It initializes relevant fields from edit data and updates that record rather than creating a second one.

Test both paths independently. Never infer edit mode only from a heading, Button label, or a populated field. The opening context and Form's configured workflow determine the intended operation.

A Data Table may also expose custom row actions. Such actions should pass the selected row context needed by the Form; the row's visible text is not always sufficient to identify the intended record.

Opening from Page Flow

Page Flow can open a Form after another browser-side event or workflow step.

Use this when the Form should open only after a condition or preceding action, such as:

• The user selects an item from a list.
• A search result is chosen.
• A previous validation step succeeds.
• A custom action needs extra information.
• A workflow needs user confirmation or notes before continuing.

For example, a Page Flow workflow might let a user select a product, then open a Custom Form to request a quote for that product. The selected product can be passed as context to the Form.

Page Flow is useful for coordinating the interface. Protected operations, private credentials, and trusted business rules should be handled through the appropriate Backend or Integration capabilities.

Conditional Modal Opening

Page Flow becomes useful when the Form should open after another step instead of immediately following a click.

For example, a registration Page may follow this conceptual sequence:

Visitor selects an event
  Check whether registration can proceed
    If eligible
      Open Registration Form in new-record mode
      Pass selected event as shared context
    Otherwise
      Show an appropriate message on the opening Page

This is a conceptual workflow, not the name or syntax of a particular Page Flow block. Eligibility checks that must be trusted or that involve sensitive rules should be enforced through the appropriate Database permissions or Backend operation, even if Page Flow also checks them to improve the user experience.

Passing Context to a Form

Context is information from the opening Page that the Form needs to complete its task. It can be passed whether the Form is creating a new record, editing an existing record, or running a custom workflow.

There are two related ideas:

Information Type	Purpose
Edit data	The record data used when a Form opens to edit an existing record.
Shared context	Additional information the opening Page passes to the Form, independent of whether the Form is new, edit, or custom.

Edit data is only one part of context. A Form can receive shared context even when it opens in a new-record workflow.

Examples include:

Context	Possible Use
Selected record	Edit the correct record.
Selected product	Request information about that product.
Selected event	Create a registration for that event.
Current category or filter	Preselect a Form field.
Current Project User context	Personalize or associate the submission where appropriate.
Prior workflow choice	Continue a multi-step process.

Pass only the context the Form needs. Context should make the workflow easier and more precise; it should not become a substitute for permissions or trusted validation.

New vs. Edit Context

New and Edit workflows use context differently, but both can receive shared context.

Workflow	Context Need
New	Shared context can provide defaults or related values, such as a selected event, category, product, or parent record.
Edit	Edit data identifies and initializes the record being edited; shared context can still provide additional workflow information.
Custom request	Shared context can tell the Form what the request is about, such as selected product, order, event, or prior Page choice.

If an Edit Form opens without the correct edit data or record identity, it may show blank values, attempt to update the wrong record, or fail. Always test edit workflows from the actual Page or Data Table action that opens the modal.

If a New Form depends on shared context, test that path as carefully as an Edit workflow. For example, a Register for Event Form may create a new registration record while still needing the selected event from the opening Page.

Edit Data, Shared Context, and Current Form Data

The Form may work with three related but distinct sets of information:

Information	Where It Comes From	Typical Purpose
Edit data	The existing record selected for editing.	Identify and initialize the record being updated.
Shared context	Information supplied by the opening Page's workflow.	Set defaults, establish a relationship, or tell the Form what task the visitor is completing.
Current Form data	The Form's input fields as they are initialized or edited.	Validate and submit the values the user is providing.

These values need not be identical. In particular, shared context should not be assumed to be included automatically in current Form data. If a submission needs a shared-context value, the Form Page Flow should read or use it intentionally.

Example: New registration with context

The opening Page displays an event identified as EVENT-104. The visitor selects Register. The Registration Form opens in New mode and receives the event as shared context. The visitor then enters their name and email as current Form data. The event association and submitted attendee values can be processed together, subject to the configured workflow and trusted validation. No edit data is needed because the Form is creating a new registration.

Example: Edit order with extra context

An Orders Page opens an Edit Order Form using the selected order's data. It may also pass the current list filter as shared context. The Form uses the edit data to initialize the order fields; the list filter is useful to the surrounding workflow but does not identify the record being updated.

For supported initialization, field access, and lifecycle operations inside the Form, see Form Page Flow.

Form Title and Modal Presentation

The modal should make the task obvious.

Use a clear title such as:

• Add Customer
• Edit Order
• Request a Quote
• Submit Support Ticket
• Approval Notes

The Form content should match the title. If the modal title says Edit Customer, the Form should show the fields needed for that edit task and should not unexpectedly perform an unrelated operation.

Keep modal Forms focused and reasonably compact. If the user must complete a large number of unrelated fields, consider splitting the workflow into clearer steps or separate Forms.

Handling Success

After a Form succeeds, decide what the opening Page should do.

Common success responses include:

• Close the modal.
• Refresh a Data Table.
• Update a visible summary.
• Show a confirmation message.
• Continue to another workflow step.
• Leave the success message visible inside the modal.

For record workflows, refreshing the opening Data Table is often important. A successful create or update can feel broken if the user returns to a stale list that does not show the new information.

Do not show success until the configured Form operation has actually succeeded.

Handling Errors

When a Form fails, the user should understand that the operation did not complete.

Common error situations include:

• Required values are missing.
• A field value is invalid.
• The selected record is unavailable.
• The user is not allowed to perform the operation.
• A Backend or Integration workflow fails.
• Network or service conditions prevent completion.

The Form's Error Status Area should provide concise recovery guidance. The opening Page should avoid refreshing or showing a completed state when the Form reports failure.

For protected or trusted operations, error handling should reflect the result returned by the appropriate Backend capability.

Close and Cancel Behavior

Closing a modal is different from submitting a Form.

Plan what should happen when the user:

• Closes the modal without submitting.
• Selects a cancel action.
• Submits successfully.
• Submits and receives an error.

In most workflows, close or cancel should leave existing data unchanged. If the opening Page needs to clear temporary state after the modal closes, configure that behavior explicitly.

Do not treat closing the modal as proof that the Form succeeded.

Unsaved Changes and Repeated Submission

A user may close a modal after changing fields but before submitting. Consider whether the workflow needs to warn about unsaved changes or whether simply discarding those edits is acceptable. Do not assume a warning is provided automatically; implement it only through supported Form and Page Flow behavior.

When a Form starts an operation that takes time, prevent unintended repeated submissions through the Form's supported locking or submission controls. Form Page Flow can coordinate locking and unlocking during custom processing. The opening Page should also avoid launching overlapping copies of the same workflow if doing so could confuse the user.

A cancelled or dismissed Form should not normally trigger a Data Table refresh, success notification, or other completed-operation behavior unless the workflow has separately changed data.

Opening Page Page Flow vs. Form Page Flow

The opening Page and the Form can each have Page Flow, but they serve different purposes.

Page Flow Location	Common Responsibilities
Opening Page	Open the modal, pass context, handle success or close, refresh Widgets, update surrounding content.
Form	Initialize fields, validate input, submit values, set success or error status, coordinate Form-specific behavior.

For example:

Customers Page Page Flow
  Open Customer Form
  Pass selected record for Edit
  Pass selected region as shared context
  Refresh Customers table after success

Customer Form Page Flow
  Set default status
  Read shared context
  Validate fields
  Submit create or update operation
  Show success or error state

Keep the responsibilities clear. The opening Page should not need to know every internal detail of the Form's layout, and the Form should not assume how every possible opening Page wants to respond.

Reusing Forms Across Pages

A reusable Form can be opened from more than one Page or Widget, provided each opening path supplies the information the Form needs.

For example, one Contact Support Custom Form might be opened from:

• An Orders Page, which passes the selected order as shared context.
• A Product Page, which passes the product being viewed.
• An Account Page, which opens the Form without a selected order or product.

The Form can use shared context to prefill a field or tailor its instructions where supported, while keeping its own field definitions and submission behavior consistent.

To make this maintainable:

1. Decide which shared-context values the Form actually requires and which are optional.
2. Use meaningful names and consistent data meaning in each opening Page's workflow.
3. Handle absent optional context without confusing or invalid output.
4. Keep Form validation and submission logic within the Form where practical.
5. Let each opening Page decide how it should update its own content after the Form succeeds.

A Form should not assume that every opening Page contains the same Data Table, filters, or other Page Elements. This allows the Form to be reused without tightly coupling its logic to one particular Page.

End-to-End Example: Event Registration

Consider an application that shows event details to visitors and lets authorized administrators edit registrations.

Visitor Registration — New Form with Shared Context

1. A visitor opens an Event Details Page.
2. The visitor selects Register for a specific event.
3. The opening Page opens a Registration Form in New mode and supplies the selected event as shared context.
4. The Form initializes any supported defaults and collects attendee details.
5. The Form validates the entered fields and submits the registration through its configured table-backed or custom workflow.
6. Any trusted capacity checks or other protected registration rules are enforced through the appropriate Backend behavior.
7. Once submission succeeds, the Form presents confirmation and the opening Page updates availability or registration information if configured.

The selected event is shared context, not edit data. The Form is creating a registration, not editing an existing one.

Administration — Edit Form with Record Data

1. An authorized administrator views registrations in a Data Table Widget.
2. The administrator selects Edit on a particular registration.
3. The selected registration's edit data is supplied to the Registration Form.
4. The Form opens in Edit mode with the supported fields initialized from that record.
5. The administrator changes the allowed values and submits.
6. The record is updated only if the configured operation succeeds and the user has the required permissions.
7. The Data Table refreshes after success so the administrator can see the updated values.

Both workflows may share some field layout concepts. Their starting data and submission outcomes differ, so they must be tested independently.

Choosing the Right Opening Pattern

Scenario	Recommended Pattern
Add a record from a list Page	Data Table New action or Page Button opening a Table-Backed Form.
Add a related record using information from the current Page	Open a Table-Backed Form in new-record mode and pass shared context such as the selected parent item.
Edit a selected record	Data Table Edit action opening a Table-Backed Form with selected record context.
Submit a request from a marketing or portal Page	Button opening a Custom Form.
Ask for extra information during a workflow	Page Flow opens a Custom Form and passes context.
Collect approval notes for a selected item	Row action or Button opens a Custom Form with selected item context.

Choose the pattern that matches how the user starts the task and what the Form needs in order to complete it.

Previewing and Testing

Test modal Forms from the Page or Widget that opens them.

Check these cases:

Case	What to Verify
Button open	The Button opens the intended Form.
Data Table New	The Form opens in new-record mode and creates the intended record.
Data Table Edit	The Form opens with the selected record and updates the correct record.
Shared context	Values passed from the opening Page are available where expected in new, edit, and custom workflows.
Edit data	Edit workflows load and update the intended record, separate from any additional shared context.
Success	The modal and opening Page respond correctly after completion.
Error	The Form reports failure without implying completion.
Close or cancel	Leaving the modal does not submit the Form.
Refresh	Data Tables or summaries update only when appropriate.
Permissions	Users can open and complete only the workflows they are allowed to use.
Responsive layout	The modal remains usable on desktop, tablet, and mobile widths.

Testing the Form by itself is not enough. A Form can be designed correctly and still fail if the opening Page does not pass the required context or respond properly to the result.

Security and Authorization

Modal opening, shared context, and visible Form fields are part of the browser-side user experience. They do not grant permission to read or change records.

For protected workflows:

• Apply the appropriate Page Settings access restrictions for Pages intended only for authorized Project Users.
• Enforce Database access rules for supported direct data operations.
• Use Cloud Flow or other trusted Backend capabilities for centrally enforced business rules, private credentials, or sensitive operations.
• Validate record identities, relationships, and permissions in the trusted operation rather than relying only on record IDs or context passed from the browser.
• Do not treat a hidden Button or unavailable menu item as authorization.

A selected record or user value passed into a Form is information to process, not proof of identity or permission.

Responsive Modal Experience

The Form layout should remain usable within the modal at desktop, tablet, and mobile widths. The opening Page also needs to remain understandable when the modal closes.

Keep headings concise, avoid excessively wide field arrangements, and check that the primary submit and cancel or close controls remain reachable. Test long labels, error messages, and keyboard or touch interaction where relevant. See Form Layout and Fields for the Form's detailed layout guidance.

Troubleshooting

Symptom	What to Check
The modal does not open	Confirm the selected Button, Widget action, or Page Flow interaction references the intended Form and uses a supported opening behavior.
A New Form shows unexpected existing values	Review Form initialization, defaults, and whether the opening workflow mistakenly supplied edit data.
An Edit Form opens blank or updates the wrong record	Verify the selected record and edit data, including the record identity used by the update workflow.
A related value is missing in a New Form	Confirm shared context is passed by the opening Page and read by the Form; do not assume it appears in current Form data.
A Form works from one Page but not another	Compare the shared context and result-handling configurations of the two opening workflows.
The table still shows old data after success	Check that the opening Page's refresh or update action runs after successful Form completion.
The opening Page shows success after cancellation	Ensure the workflow distinguishes close/cancel from successful submission.
The modal remains locked after an error	Review the Form's custom submission and unlock/retry handling, where configured.
The workflow succeeds for one user but not another	Review Page access, Database permissions, and Backend authorization for the intended Project User or User Group.

When debugging, start from the actual Page action that opens the Form and follow the interaction through initialization, submission, and result handling. Testing the Form layout by itself will not reveal every context or opening-Page problem.

Good Practices

• Use clear opening actions. Button and row-action labels should describe the task.
• Pass only needed context. Give the Form what it needs, and validate protected values through trusted capabilities.
• Keep edit data and shared context distinct. Edit data is for the record being edited; shared context can support any modal Form workflow.
• Test New and Edit workflows separately. They may use the same Form, but they initialize and submit differently.
• Refresh after successful record changes. Keep the surrounding interface in sync with completed operations.
• Handle close and cancel deliberately. Do not confuse leaving the modal with submitting the Form.
• Separate responsibilities. Let the opening Page coordinate the modal and let the Form handle its own input behavior.
• Test from the real starting point. Preview the Button, Data Table action, or Page Flow event that opens the Form.

Technical Reference

For exact modal-opening blocks and API details, see the Programming Guide:

• Show Popup Form block
• Data Table Attach Form block
• Close Popup block
• $io.ui.showFormModal
• $io.ui.closeModal

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

Common Mistakes

Avoid these patterns:

• Assuming that placing a Button on a Page automatically opens or submits a Form.
• Opening an Edit Form without passing the selected record context.
• Forgetting that New Forms can also require shared context from the opening Page.
• Treating shared context as the same thing as edit data.
• Showing a success message on the opening Page before the Form operation succeeds.
• Forgetting to refresh a Data Table after a successful create or update.
• Treating close or cancel as a successful submission.
• Passing broad or sensitive context values that the Form does not need.
• Relying on browser-side context as the only permission check.
• Testing the Form layout but not the full modal workflow.

Modal Forms work best when the opening action, context, Form behavior, result handling, and Page refresh all line up as one complete user interaction.

Related Topics

• Forms
• Form Layout and Fields
• Table-Backed Forms
• Custom Forms
• Form Page Flow
• Buttons and Actions
• Data Table Widget
• Page Flow for Forms and Widgets