Using Database from Pages

Pages and Forms can use Project Database tables to display records, collect input, and support data-driven workflows. ioLoop provides ready-made frontend components for common requirements, as well as Client APIs for Creators who prefer to implement the experience directly in JavaScript.

Use this guide to choose an appropriate frontend implementation, understand how data operations fit into the Page lifecycle, and determine when a workflow needs trusted Cloud Flow processing.

For exact Page Flow block inputs and Client API signatures, use the Programming Guide.

How Frontend Database Access Works

Frontend Database operations run in the context of the user accessing the Page and are subject to the Project's applicable Database access rules.

The same Database tables can support different user experiences:

• A public Page displays published event information.
• A registration Form collects attendee details.
• An administrative Data Table displays permitted registrations.
• Data Design renders product or event records as visual cards.
• Page Flow retrieves records and updates content after an interaction.
• A custom JavaScript application creates its own record lists, Forms, and controls using the ioLoop Client APIs.

A Page does not need Cloud Flow for every Database operation. If the Client API supports the operation and the current user is permitted to perform it, the frontend can use the Database directly. Use Cloud Flow when the operation requires trusted business rules, additional authorization, private credentials, or other protected server-side processing.

Choosing a Frontend Approach

Approach	Best For	How It Uses Database
Table-Backed Form	Creating or editing records through a ready-made modal Form.	Collects values for fields in a selected Project table.
Data Table Widget	Standard record listings with configured columns and record actions.	Retrieves and displays table data, with supported paging, searching, and actions.
Data Design	Custom repeated layouts such as cards, tiles, profiles, or search results.	Uses records supplied through Page Flow to populate a reusable visual design.
Page Flow	Browser-side events, queries, data operations, and updates to Page content.	Uses visual blocks and supported Client APIs to coordinate permitted operations.
Custom frontend JavaScript	Fully custom Pages, tables, SPA-style interfaces, Forms, and record interactions.	Calls ioLoop Client APIs directly and manages its own interface behavior.
Cloud Flow	Protected operations that should not be trusted to the browser.	Performs server-side processing and returns an appropriate result to the frontend.

These approaches can be combined. For example, a Page may use a Data Table Widget for record browsing, a Table-Backed Form for editing, and Page Flow to refresh the table after a successful save.

One Client API Foundation

ioLoop's built-in Forms, Widgets, and Page Flow blocks use the same ioLoop Client APIs that custom frontend JavaScript can call directly.

A custom implementation can achieve the same functional outcomes as the corresponding built-in component. The difference is whether ioLoop supplies the visual structure and interaction lifecycle or the Creator implements them directly.

For example, an Add Customer workflow can use:

• A Table-Backed Form opened from a Data Table Widget.
• A Page Flow with supported Database operations and modal actions.
• A completely custom modal written in HTML, CSS, and JavaScript that calls the same Client APIs.

All three can create permitted Database records. A custom modal must manage its own field state, validation, submission feedback, and interaction lifecycle, but it does not lose access to the underlying Client API functionality.

For broader guidance, see Standards-Based Frontend.

Before Connecting a Page to Database

A reliable data-backed Page starts with its Database design and permissions.

1. Identify the table. Choose the Project table that owns the records the interface needs.
2. Review its fields. Confirm Field IDs, types, sub-types, User Input settings, and any Form or workflow validation rules.
3. Configure Table Access. Decide which users may View, Add, Modify, or Delete records. API documentation refers to these operations as Read, Create, Update, and Delete.
4. Prepare named queries where useful. Reuse configured retrieval patterns instead of repeating filtering and sorting logic.
5. Choose the interface. Decide whether a Form, Data Table Widget, Data Design, Page Flow, or custom JavaScript is the most suitable implementation.
6. Plan the result handling. Define loading, empty, success, and failure states.
7. Test using development records. Preview the full user workflow, including permitted and denied operations.

The Page's layout and available actions should reflect the intended permissions, but visible controls do not replace the table's access rules.

Using Table-Backed Forms

Use a Table-Backed Form when users should create or edit a record in one selected Project table.

Typical uses include adding a customer, editing an order, updating a registration, or managing contact details.

A common workflow is:

1. A user selects New, Edit, or another action on the opening Page.
2. The configured Form opens as a modal.
3. For Edit, the opening workflow provides the record to be updated. Both New and Edit workflows may also receive shared context.
4. The Form collects and validates the necessary table field values.
5. The permitted create or update operation completes.
6. The Form reports success or failure.
7. The opening Page refreshes its record list or updates other visible content when appropriate.

A table-backed Form provides ready-made field and submission behavior. Page Flow may be added for defaults, additional validation, shared context, and related UI updates, but it is not required for every simple record operation.

For details, see Table-Backed Forms, Opening Forms as Modals, and Form Page Flow.

Using Data Table Widgets

Use the Data Table Widget when the main task is browsing or managing records in a conventional table interface.

Typical applications include administrative lists, customer records, order management, registration review, and support-ticket queues.

A Data Table Widget can provide:

• Configurable columns drawn from Project table fields.
• Built-in search, refresh, download, and paging controls where configured.
• New, Edit, Delete, and custom record-oriented actions where supported.
• Integration with modal Forms and Page Flow.
• A Custom Query option for workflows that supply the record source through Page Flow.

A Page Flow can attach appropriate Forms to table actions, work with the selected row, and refresh the table after a successful change.

Configure only the columns and actions the user needs. Hiding a column does not prevent its value from being accessed if the underlying record has already been returned to the browser. Apply appropriate permissions and retrieve only the authorized data.

For widget configuration, see Data Table Widget.

Using Data Design

Use Data Design when records need a custom repeated appearance rather than a standard table layout.

Examples include product cards, event listings, member profiles, dashboards, and search-result tiles.

The typical pattern is:

1. Create a reusable design for one item.
2. Configure placeholders for values such as title, image, price, status, or destination URL.
3. Retrieve permitted records through Page Flow.
4. Supply the placeholder values for each record.
5. Render the instances into a target area on the Page.
6. Handle loading, empty results, refreshes, and item-specific interactions.

Data Design defines the presentation structure; Page Flow coordinates retrieval and rendering. The data may come from a table read, named query, or other supported source.

For details, see Data Design and Rendering Data Design.

Page Flow Database Operations

Page Flow handles browser-side coordination between Project data and the Page interface.

Common uses include:

• Loading records when a Page opens.
• Retrieving records after the user selects a filter.
• Using a named query with runtime inputs.
• Creating, updating, or deleting records when the current user is permitted to do so.
• Populating Data Design or other Page Elements.
• Refreshing a Data Table or summary after a successful change.
• Handling empty results and failed operations.

Reading and Updating Records

Use the appropriate supported Database blocks for the intended operation. A direct read and a named query are not identical: a named query provides a reusable retrieval definition created in the Database editor.

Supported read operations can load records into datasets used by Page Flow. When paging through query results, use the corresponding dataset and supported next/previous operations.

For operations that complete asynchronously, perform dependent work only after success or completion is established. An operation starting does not mean its records or saved changes are already available.

Named Queries

A named query can define Search Criteria, Field Selection, Data Joins, and Sorting Order. It can also accept runtime inputs, such as a selected event ID, customer ID, or status.

For example, a RegistrationsByEvent query can return records for the event selected on the Page. The Page supplies the input value rather than creating a separate query for each event.

A query defines which records to retrieve; it does not grant the caller permission to access them. Table Access and any required record-specific authorization still apply.

See Queries and Page Flow Data and Cloud Flow.

Using Database from Custom JavaScript

Custom frontend code can access the same supported ioLoop Client APIs used by built-in Forms, Widgets, and Page Flow blocks.

A Creator can build a complete data-driven interface using HTML, CSS, JavaScript, and Client APIs for record retrieval, creation, updates, deletion, paging, and supported file operations.

Example: Reading Records with a Named Query

Suppose a Project defines a RegistrationsByEvent query for the Registrations table with one input: the event ID.

const selectedEventId = 'event-123';

const result = await $io.db.readQuery(
  'Registrations',
  'registrationsList',
  25,
  'RegistrationsByEvent',
  [selectedEventId],
  {}
);

if (result.status) {
  const records = result.data;
  // Render the returned records in your custom interface.
} else {
  // Show a useful error message based on result.err.
}

This example uses the documented $io.db.readQuery Client API. Replace the example names and values with the actual table, dataset, query identifier, and parameters configured in your Project.

For direct API calls, queryInput is an array of values in the parameter order defined by the query. The Query editor labels these positional values Input-1, Input-2, and so on; it does not assign custom input names or store fixed literal operands. This differs from the configured input object used by the Page Flow Data Read block. Use the input format required by the calling interface.

The returned result includes a success status and either data or error information. Check the result before rendering records. A successful read with an empty array is different from a failed read.

The Client API reference documents the available $io.db functions, parameters, outputs, and dataset operations. Use it for implementation details rather than assuming API signatures from visual block settings.

Custom Forms and Record Operations

A custom modal can use Client APIs to implement the same permitted create and edit behavior as an ioLoop Form. The Creator implements the interface, field state, validation, submission controls, and outcome handling directly.

This is a supported alternative, not a lower-capability path. It remains subject to the same Database access rules and Backend security requirements.

Direct Database Operations vs. Cloud Flow

Use direct frontend Database access when the Client API supports the operation and the user's configured access is sufficient.

Use Cloud Flow when the application needs server-side trust or processing that cannot safely depend on the browser.

Requirement	Recommended Approach
Read records permitted by the table's access rules	Page Flow or Client API.
Create or update an ordinary record under the permitted access model	Table-Backed Form, Page Flow, or Client API.
Display a filtered record list	Named query through a Widget, Page Flow, or Client API.
Enforce ownership of a particular record where table-level permissions are insufficient	Trusted Backend authorization, such as Cloud Flow.
Enforce a capacity limit, protected price, approval condition, or similar business rule	Cloud Flow.
Use private credentials or make protected external service calls	Cloud Flow or another appropriate Backend capability.
Perform trusted processing involving multiple related data changes	Cloud Flow.

For example, event registration capacity should be checked and enforced through trusted processing. Merely checking the displayed number of available seats in the browser is not sufficient, because the number may change or the browser's request may be modified.

The Backend operation must also be protected from bypass. If a capacity-controlled Registrations table permits unrestricted direct Create operations, a caller may be able to skip the intended Cloud Flow checks. Configure the table permissions and submission path to enforce the business rule, not merely the Page's Button behavior.

For details, see Calling Cloud Flow from Pages, Table Access, and Using Database from Cloud Flow.

Access Control and Data Exposure

Database-backed Pages must be designed around what each user is permitted to access.

Page Access, Table Access, and Record Authorization

These controls have different responsibilities:

Control	Purpose
Page Access	Determines who may open a Page.
Table Access	Controls permitted View, Add, Modify, and Delete operations for the configured users or groups.
Record-specific authorization	Determines whether a user may access or change a particular record when a general table permission is insufficient.
Cloud Flow	Provides trusted processing for operations requiring additional authorization or business rules.
Frontend UI	Displays appropriate actions and feedback but is not an authorization boundary.

A public Page does not automatically make every table public. Conversely, restricting a Page or hiding an element does not automatically protect the data operation behind it.

Retrieve Only Authorized Data

Do not retrieve broad sensitive datasets and then hide unauthorized records with browser-side filters. Data already returned to the browser should be considered exposed to that session, even if it is not visible in a particular Widget or element.

A query that accepts a customer ID or record ID does not prove the caller owns that record. Apply the necessary authorization before providing sensitive data.

File Fields Inherit Table Access

Files associated with Database file fields follow the access rules of their parent table. If the table is publicly readable, files associated with records in that table must be treated as publicly accessible.

For example, a publicly readable product catalog may safely contain public product images. A table holding confidential customer attachments should not have public Read access merely to support a public submission Page.

Where files require additional privacy or controlled distribution, use an appropriate restricted data model and trusted file-handling workflow. Hiding download links does not secure the files.

See File Fields for file access and lifecycle guidance.

Development Database During Preview

During Preview, built-in Database operations automatically use the Project's development database. This applies to built-in reads, creates, updates, and deletes through supported frontend components and Page Flow.

This means Creators can test data-backed Pages with development records without changing production records through those built-in operations. No additional environment selection is required for them.

The published application uses the production data environment where supported by the subscription plan. Development and production records can differ, so a workflow that works with sample data should also be verified after publishing.

Do not assume that external Integrations automatically switch into a test environment during Preview. Review the configured provider mode and any Cloud Flow or custom operations that may have external side effects.

For details, see Development and Production Data and Previewing.

Example: Event Registration Page

Consider a Project that lets visitors browse events, register for available events, and lets administrators manage registrations.

1. Define the data model

Create an Events table for event information and a Registrations table for attendee submissions. Define fields, table permissions, and named queries for the relevant Pages.

2. Display events

Use a Data Table Widget, Data Design, or custom JavaScript to retrieve and display the event information available to visitors.

3. Open registration input

Use an ioLoop Form or a custom modal interface to collect attendee information. The opening Page can supply the selected event as shared context.

4. Enforce capacity on the server

Submit the registration request to a protected Cloud Flow workflow. It validates the event, permissions, and capacity, then creates the registration only when allowed. Configure Database access so callers cannot bypass that rule through unrestricted direct writes.

5. Present the result

After the operation succeeds, close or update the modal and refresh the event or registration display as needed. If it fails, show an actionable message without claiming the registration was saved.

6. Preview and publish

Test against development records with different capacity and access conditions. Publish when ready, then verify the released application with appropriate production data.

The same workflow can be implemented with ioLoop's built-in frontend components or with custom JavaScript and the same Client APIs. The security and data rules remain the same.

Testing and Troubleshooting

Test the complete Page behavior with realistic development records and the intended user contexts.

Symptom	What to Check
No records appear	Table name, query configuration, query inputs, current data environment, and whether matching records exist.
Access denied	Current preview user, Table Access, Page Access, and any required record-specific authorization.
Query returns unexpected data	Search Criteria, Field Selection, Data Joins, Sorting Order, and runtime inputs.
Data Table does not refresh	Whether the create or update completed successfully and a refresh was configured afterward.
Form opens with incorrect values	New versus Edit context, selected record, field bindings, and shared context.
Custom JavaScript receives an error	API parameters, status and err, required permissions, and asynchronous completion.
Data Design appears empty	Retrieved records, placeholder field names, target area, and rendering workflow.
Preview and published results differ	Development versus production records, access context, and external service configuration.
Files are unexpectedly accessible	Parent table Read access and any additional file-handling workflow.

A successful data read returning no records is not necessarily an error. Handle empty results, loading, invalid input, and failed operations as distinct interface states.

Good Practices

• Choose by experience, not by API access. Built-in components and custom code can achieve equivalent Client API results.
• Design permissions before exposing data. Apply Table Access and trusted record-specific authorization where needed.
• Use named queries for repeated retrieval patterns. Keep inputs and expected result fields clear.
• Keep frontend responses asynchronous-aware. Refresh or render data only after operations succeed.
• Retrieve only needed data. Field hiding and browser filtering do not secure records already returned.
• Use Cloud Flow when trust is required. Do not force every simple read through a server workflow, but do not rely on browser-side checks for protected rules.
• Test with realistic development data. Include empty results, denied operations, stale records, and failure paths.
• Verify after publishing. Production records and external connections may differ from Preview conditions.

Common Mistakes

Avoid these patterns:

• Assuming that custom JavaScript has fewer Database capabilities than Forms, Widgets, or Page Flow.
• Assuming every Database operation needs Cloud Flow.
• Treating hidden controls, query filters, or client-side validation as authorization.
• Permitting unrestricted direct writes that bypass a required Cloud Flow business rule.
• Passing a record ID from the browser and treating it as proof of ownership.
• Expecting a Form submission to refresh every Data Table automatically.
• Handling an asynchronous operation as though its result were already available.
• Confusing development records with production records.
• Storing confidential file attachments in a publicly readable table.

Database-backed Pages work best when data structure, access rules, user interaction, and trusted processing are designed together—whether the frontend is built visually or entirely with code.

Technical Reference

For exact functions, block inputs, parameters, return values, and dataset behavior, see:

• Page Flow Database Blocks
• $io.db Client API
• Page Flow Data and Cloud Flow

Related Topics

• Database
• Table Access
• Queries
• File Fields
• Table-Backed Forms
• Data Table Widget
• Data Design
• Standards-Based Frontend
• Calling Cloud Flow from Pages