Data Table Widget

The Data Table Widget displays records from a Project Database table in a ready-made, interactive table interface. Use it when application users need to view or search records, download data, or perform record-oriented actions such as creating, editing, refreshing, or deleting records.

A Data Table Widget is different from a basic Table Page Element. A basic Table provides a visual structure whose content is arranged in the Page Editor. A Data Table Widget is configured to display Project records and can work with Page Flow to support data-driven interactions and workflows.

For a manually maintained comparison table, see Tables and Cards. For custom repeated layouts, such as product cards or search-result tiles, see Data Design.

Use a Data Table Widget when you need:

A standard record list backed by a Project Database table.
Configurable columns based on fields in that table.
Search, refresh, download, and pagination controls.
New, Edit, Delete, or other record-oriented actions.
New or Edit actions that open Forms as modals.
Page Flow that responds to a selected row or coordinates custom actions.
A record list whose source is provided through a Custom Query.

Typical examples include customer directories, order lists, registration records, inventory lists, administrative screens, and records associated with a particular user or account.

Requirement	Recommended Approach
Display a fixed feature comparison or manually maintained table	Basic Table
Display Project records in a conventional table interface	Data Table Widget
Provide built-in record-oriented controls and actions	Data Table Widget
Display records as custom cards, tiles, or visually designed rows	Data Design
Present a small number of manually arranged summary panels	Cards

The Data Table Widget is usually the simplest starting point for a standard record list. Use Data Design when the layout of each record needs more customization than a conventional table provides.

Before You Begin

A Data Table Widget displays data from a selected Project table. Before configuring it, identify:

The Project table containing the records to display.
The fields that application users need to see.
The intended users and the data they are authorized to access.
The required actions, such as viewing, creating, editing, or deleting records.
Any Forms that should open for New or Edit operations.
Whether Page Flow is needed for custom queries, modal interactions, or additional record actions.

You do not need to build a custom Page Flow just to place a Data Table Widget on a Page and display records through its ordinary table configuration. Add Page Flow when the table's data or interactions require application-specific behavior.

Database table definitions and access rules are managed separately under Database. The Widget determines how records are presented and how supported user interactions are initiated; it does not replace the Project's data-access configuration.

A typical setup workflow is:

Open the Page or other supported editing context in the Page Editor.
Select the layout area where the record list should appear.
Open the Element Library and add a Data Table Widget.
Select the widget and open Element Settings from the Selected Element Toolbar.
Choose the Table whose records the widget should display.
Decide whether to show the table's fields by default or enable Select Columns to Display.
Configure the visible columns, their order, widths, and responsive visibility as needed.
Choose whether to show column headings and the built-in toolbar.
Enable Custom Query only if Page Flow should provide the record source.
Configure any required Forms, row actions, and Page Flow behavior.
Save and Preview the Page using representative records and supported screen sizes.

For example, an administrative Orders Page might contain:

text

Orders Page
  Heading (Orders)
  Data Table Widget (Orders List)
    Project Table: Orders
    Display Columns: Order Number, Customer, Date, Status, Total
    Toolbar: Visible

The structure above illustrates the Page and Widget configuration. It is not a Page Flow block specification.

Once configured, the Widget supplies the table-style presentation. The underlying Project table, access rules, and optional application workflows determine which records users can retrieve and what they can do with them.

Data Table Settings

The following settings are available in the Data Table Widget's Element Settings:

Setting	Purpose
Table	Selects the Project Database table whose records the Widget displays.
Select Columns to Display	Allows specific table fields to be selected, ordered, and configured as display columns.
Custom Query	Allows Page Flow to supply or control the records displayed by the Widget.
Hide Column Headings	Hides the header row containing column labels.
Hide Toolbar	Hides the built-in toolbar containing search, refresh, download, pagination, and New controls.

Table

Table identifies the Project table associated with the Data Table Widget.

Select the table containing the records you want users to view or work with. For example:

Page	Example Project Table
Customers	`Customers`
Orders	`Orders`
Event Registrations	`Registrations`
Inventory	`Inventory`

These are illustrative table names; use the tables defined in your Project.

The Table setting is required. Without a selected table, the Widget cannot be configured to display the intended records.

Choosing a table does not grant the current user permission to read or modify its records. Review the applicable Database access configuration for the published application.

Select Columns to Display

Enable Select Columns to Display when you want to control which fields appear, their order, and their column-specific display settings.

This is useful when a Project table contains more fields than users need in the current interface.

For example, a Customers table might contain internal identifiers, contact details, account metadata, and audit fields, while the Customer List Page only needs to show Name, Email, Status, and Created Date.

See Selecting and Configuring Columns for the available column options.

Custom Query

Enable Custom Query when the Widget's record source should be supplied through Page Flow instead of relying only on the selected Project table's default data display.

This is useful for views involving application context, filters, selected records, or other data-retrieval logic.

A Custom Query is not required for every Data Table Widget. If the selected Project table and ordinary Widget behavior meet the requirement, keep the setup simple.

See Using Custom Queries for implementation patterns and considerations.

Hide Column Headings

Hide Column Headings removes the visible header row that identifies the columns.

Leave the headings visible for most record lists. They make it easier to understand fields such as Date, Amount, Status, or Owner.

Hiding headings can be appropriate in a compact or tightly designed display where the meaning of each column is already clear. Preview the result with real records to ensure that users can still interpret the data.

Hide Toolbar removes the Widget's built-in toolbar from the visible interface.

Use it when the Page should present the table without the standard controls or when the surrounding Page and Page Flow provide a more specialized interaction.

Hiding the toolbar is a presentation decision. Do not treat it as a data-access restriction or as a substitute for authorization checks on the underlying operations.

Selecting and Configuring Columns

By default, the Data Table Widget can display fields from the selected Project table. Enable Select Columns to Display to configure a specific list of display columns.

Each selected column provides these options:

Column Option	Purpose
Data Field	Selects the field from the Project table to display.
Column Width %	Sets an optional percentage-based width for the column. Leave blank for automatic sizing.
Hide on Desktop	Hides the column on desktop-sized screens.
Hide on Tablet	Hides the column on tablet-sized screens.
Hide on Mobile	Hides the column on mobile-sized screens.

Columns can be edited, removed, and reordered. The order in the configuration list determines their display order.

Choosing Display Fields

Start with the information users need to perform their task.

For example, an Orders list could use:

Display Order	Data Field	Why It Is Useful
1	Order Number	Identifies the record.
2	Customer	Identifies who placed the order.
3	Order Date	Provides time context.
4	Status	Shows the current state.
5	Total	Displays the order amount.

Additional fields can remain in the underlying Project table without being displayed as columns.

A display column is not a separate Database field. It represents an existing field through the Widget's table presentation.

Column Width %

Use Column Width % when a field needs more or less horizontal space relative to the table layout.

For example, a Customer Name or Description field may need more room than a short Status value.

Leave the width blank when automatic sizing produces an acceptable result. When assigning widths, preview the table with long values and at different viewport widths; percentages alone do not guarantee that every field will fit without wrapping or overflow.

Responsive Column Visibility

Use Hide on Desktop, Hide on Tablet, and Hide on Mobile to tailor the visible columns to each supported screen size.

For example:

Field	Desktop	Tablet	Mobile
Order Number	Show	Show	Show
Customer	Show	Show	Show
Order Date	Show	Show	Hide
Status	Show	Show	Show
Total	Show	Show	Hide

This is an example of a configuration choice, not an automatic responsive layout applied by ioLoop.

On narrow screens, retain the fields users need to identify and act on each record. Hide lower-priority columns where appropriate, then test the result in Preview.

Column visibility controls presentation, not authorization. A hidden column must not be used as the mechanism for protecting confidential information. Configure access to sensitive data through the appropriate Database and Backend controls.

When Hide Toolbar is disabled, the Data Table Widget provides built-in controls for common record-list tasks.

Control	Behavior
Refresh	Reloads the table's data.
Search	Filters displayed rows by matching text fields.
Download	Exports displayed table data as a CSV file.
Previous	Moves to the previous page when pagination is in use.
Next	Moves to the next page when pagination is in use.
New	Initiates a new-record workflow.

The controls provide standard interaction points. Some resulting workflows, especially New, depend on the Forms and Page Flow behavior configured for the Page.

Search

Use Search when users need to narrow the visible record list using matching text.

For example, a customer list can help users find a record by searching for text in the displayed information, subject to the Widget's supported search behavior.

Search is a user-interface convenience. It must not be relied on to restrict users to authorized records.

Refresh

Use Refresh when users need to reload a list after records may have changed.

Common situations include completing a Form, updating a record through another part of the application, or returning to a list after an operation.

If Page Flow supplies the records through Custom Query, make sure the refresh workflow uses the intended current data source and filter context.

Download

Download provides a CSV export of the data displayed through the Widget.

Before relying on exports for an application workflow, verify the exported columns and rows under the actual search, column visibility, and pagination configuration. Do not assume that export is limited to the current page or includes every filtered record without testing the resulting CSV.

If the table includes sensitive fields, ensure that permissions governing the data and its export are appropriate for the intended users.

Pagination

Previous and Next let users navigate through table pages when pagination is active.

Pagination is especially useful when a Project table contains more records than should be presented on one screen.

When records come from a Custom Query, Page Flow can provide an optional page size. Coordinate changes to filters, page navigation, and refreshing so that the Widget displays the expected slice of records.

New

New initiates the new-record interaction. A common implementation is to open a Form as a modal and refresh the list after a successful submission.

Configure the required Form and Page Flow coordination rather than assuming that the presence of the New control automatically defines the entire record-creation workflow.

Record and Row Actions

Selecting a row can expose an action menu for the associated record.

Standard actions include:

Action	Purpose
New	Starts a new-record workflow.
Edit	Starts a workflow to update the selected record.
Refresh	Reloads table data.
Delete	Deletes the selected record after confirmation.

Page Flow can customize which standard actions are available and can add custom actions that use the selected row as context.

The existence of an action does not mean every user should be permitted to perform it. Configure the available actions appropriately and enforce the corresponding data permissions.

Configuring Row Actions

A typical implementation workflow is:

Decide which standard actions the Page should offer.
Configure any Forms needed for creating or editing records.
Use Page Flow where the Widget needs action visibility, modal coordination, or custom behavior.
For actions on an existing record, ensure the workflow uses the intended selected-row context.
For changes to records, handle the success or failure of the operation appropriately.
Refresh the table when users need to see the resulting data.
Preview the action with records the current user can and cannot modify, as applicable.

New and Edit

New creates an interaction for adding a record. Edit works with the record represented by the selected row.

Both commonly use a Form opened as a modal. Keep the Form fields and validation appropriate for the operation.

For example, an Edit Customer Form may allow users to update contact details while leaving an internal customer identifier unchanged.

Delete

Delete is a destructive action that requires confirmation.

When designing a deletion workflow:

Make it clear which record is being removed.
Confirm that the operation is allowed for the current user.
Handle failures without implying that deletion succeeded.
Refresh the table after a successful deletion.

Do not rely only on hiding the Delete action in the interface. Protect the underlying operation using the appropriate Database permissions or trusted Backend processing.

Custom Row Actions

Use a custom row action when the required operation is not one of the standard actions.

Examples include:

Opening the selected record's details Page.
Starting an approval workflow.
Displaying related records.
Changing a record's status through an authorized operation.
Initiating a Project-specific workflow based on the selected record.

A custom action can receive the selected row as context through the supported Page Flow integration. The Page Flow then coordinates the additional interaction or operation.

For example, an Orders table could have a View Details action that opens the Order Details Page for the selected order. If the operation requires sensitive authorization or protected business logic, coordinate with trusted Backend processing rather than enforcing those rules only in the browser.

Using Forms as Modals

A common use of the Data Table Widget is to open a Form when users create or edit a record.

A Form is a separate Page/Form item with its own configuration and Page Flow. The Page containing the Data Table Widget acts as the host Page and can coordinate the modal interaction.

Example: New Customer

A typical New workflow is:

The user selects New in the Customers Data Table.
The configured interaction opens a New Customer Form as a modal.
The user enters and submits the required information.
The Form processes the submission through its configured workflow.
The host Page responds to a successful result.
The Data Table refreshes to display the new record.

If validation or saving fails, the workflow should present the problem rather than report a successful update.

Example: Edit Order

A typical Edit workflow is:

The user locates an order in the Data Table.
The user opens the row action menu and selects Edit.
The configured Edit Form opens with the intended order context.
The user changes supported fields and submits the Form.
After successful processing, the modal closes or returns a completion result according to the configured workflow.
The host Page refreshes the Data Table as needed.

The exact Form and Page Flow configuration depends on whether the Form is Table-Backed or Custom and how the Project handles the data operation.

For implementation guidance, see Opening Forms as Modals and Page Flow for Forms and Widgets.

Using Custom Queries

Enable Custom Query when Page Flow should supply or control the set of records displayed in the Widget.

This gives the Page more control over the record list than the ordinary selected-Table display.

When a Custom Query Is Useful

Requirement	Example
Show context-specific records	Orders associated with the customer currently being viewed.
Apply a user-selected filter	Registrations for a selected event.
Display records relevant to a signed-in user	Records associated with that user, subject to enforced access rules.
Depend on another Page interaction	Change the record list after a selection elsewhere on the Page.
Display a restricted or shaped result set	Show records returned by a Project-specific data operation.

Direct Table Display vs. Custom Query

Direct table display uses the selected Project table through the Widget's regular data configuration. It is appropriate when the application can show that table's records without needing Page Flow to determine the record source.

Custom Query makes Page Flow responsible for providing the intended records and, where applicable, an optional page size.

Conceptually:

text

Direct Table Display
  Project Table
    -> Data Table Widget

Custom Query
  Page context or user selection
    -> Page Flow data operation
      -> Records supplied to Data Table Widget

This diagram describes the relationship between components; it is not executable query code or a specification of particular Page Flow blocks.

Configuring a Custom-Query Table

A typical sequence is:

Add and configure the Data Table Widget, including its selected Table and display columns.
Enable Custom Query.
Open Page Flow for the host Page.
Configure the supported data operation that retrieves the desired record set.
Supply the retrieved records to the Data Table Widget through the supported Page Flow interaction.
Provide an optional page size if the workflow requires one.
Coordinate the query with relevant startup actions, selection changes, refreshes, or pagination behavior.
Preview the table with matching records, no results, and error conditions.

Avoid treating a custom query as an authorization rule merely because it uses the signed-in user or a selected filter. Sensitive access restrictions must be enforced through the appropriate Database rules or trusted Backend operations.

Page Flow provides browser-side logic that can coordinate the Data Table Widget with other elements and application capabilities.

The Data Table Widget has dedicated Page Flow blocks for common runtime controls. In most cases, use those blocks instead of calling lower-level widget commands directly.

Supported patterns include:

Page Flow Pattern	Example Use
Show or hide standard row actions	Expose an Edit action only when it is appropriate for the current interface state.
Attach Forms to New or Edit actions	Open a modal for entering or updating a record.
Add a custom row action	Open details or initiate a Project-specific workflow.
Use selected-row context	Act on the record chosen by the user.
Move to the next or previous table page	Coordinate pagination with other Page controls.
Refresh the table	Reload data after a successful operation.
Set the filtered record source	Update the table in response to a filter or selection.

Use Page Flow when the Data Table is part of a larger workflow rather than only a record list.

Data Table Page Flow Controls

Common Data Table Page Flow controls include:

Control	Use It To
Data Table Refresh	Reload the table's displayed data after a change or workflow step.
Data Table Load Next Page	Move the table to the next page of records.
Data Table Load Prev Page	Move the table to the previous page of records.
Data Table Custom Query	Provide the table's record source and optional page size from Page Flow.
Data Table Action Menu Customize	Show or hide standard row actions such as New, Edit, Refresh, and Delete.
Data Table Add Action	Add a Project-specific custom row action.
Data Table Attach Form	Open a Form as a modal for New, Edit, or both action types.
Data Table: Data	Use the selected row data inside a custom row action.
Data Table: Table Name	Refer to the table associated with the current Data Table action context.

These controls are Page Flow authoring tools. They call the Data Table runtime behavior internally.

Use direct $io.ui.widgetCommand(...) calls only for advanced JavaScript scenarios where the Page Flow blocks do not fit the implementation. For exact block inputs and the underlying API, see Technical Reference.

Example: Event Registrations

Consider an administrative Page for managing event registrations.

The Page contains:

text

Event Registrations Page
  Event Selector
  Heading (Registrations)
  Data Table Widget (Registration List)
    Project Table: Registrations
    Custom Query: Enabled
    Display Columns: Attendee, Email, Status, Registered On

The interaction might work as follows:

An administrator selects an event.
Page Flow retrieves the registration records associated with that event.
The result is supplied to the Data Table Widget.
The administrator reviews the records and uses an available row action.
An Edit action opens a registration Form as a modal.
When the update succeeds, the table refreshes using the relevant event context.

This illustrates a possible application design. The specific event selector, data operation, authorization, and Form behavior must be configured in the Project.

Data Access and Security

A Data Table Widget is a user-interface component. It does not replace access controls on Project data.

Several distinctions are important:

Mechanism	What It Controls
Page access	Who can open the Page under its configured access restrictions.
Database access rules	Which data operations and records are available through the permitted data interfaces.
Column visibility	Which fields appear in the Widget layout at a given screen size.
Toolbar or action visibility	Which controls are presented in the interface.
Custom Query	Which records Page Flow requests or supplies for display.
Cloud Flow	Trusted server-side processing when protected credentials, centrally enforced rules, or sensitive business logic are needed.

Hiding a column, action, or toolbar is not a security control. Similarly, a browser-side Custom Query must not be the sole mechanism for preventing unauthorized data access.

For sensitive applications:

Apply the appropriate Database access rules.
Use trusted Backend checks for operations requiring centrally enforced authorization or business rules.
Make sure New, Edit, Delete, custom actions, and data exports are appropriate for the current user.
Review whether the records returned to the browser contain fields that should not be exposed.
Test authorized and unauthorized scenarios, not only successful interactions.

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

Responsive Design and Usability

Data Tables can become difficult to use when many fields compete for horizontal space.

A practical approach is:

Select the fields that users need most often.
Put the most important columns first.
Use Column Width % only where a specific width helps.
Hide lower-priority columns for Tablet or Mobile when appropriate.
Keep record identification and important status information visible.
Preview long names, large numbers, dates, and other realistic values.
Test row-action menus and toolbar controls at smaller widths.

Desktop

Desktop layouts can often accommodate more fields, but unnecessary columns still make records harder to scan. Keep the table focused on the Page's main purpose.

Tablet

Consider hiding supplemental fields such as internal notes or secondary metadata while preserving identifiers and information needed to make decisions.

Mobile

Prioritize a small number of meaningful columns and make sure users can still reach required actions. If the task depends on many fields, consider a separate detail view or Form rather than compressing all information into a narrow row.

Responsive column settings control which columns are shown. Preview and test the complete interaction rather than assuming that hiding columns automatically produces the ideal mobile layout.

Previewing and Testing

After configuration, save the Page and use Preview to test both appearance and behavior.

Check the following:

Area	What to Verify
Data source	The intended Project table or Custom Query supplies the expected records.
Columns	Fields, order, widths, and headings match the intended presentation.
Responsive display	Important columns remain readable at desktop, tablet, and mobile widths.
Search	Search produces appropriate matches for representative text values.
Download	CSV output contains the expected records and fields for the actual table state.
Pagination	Previous and Next navigate correctly, especially with Custom Query.
New and Edit	The intended Form opens and processes the correct workflow.
Delete	Confirmation, permissions, and resulting refresh behavior work as expected.
Custom actions	The action uses the intended selected-row context.
Data changes	Refresh reflects successful changes in the Project data.
Access	Users can perform only operations allowed by the Project's access configuration.

Also test the table when no records match, when a data operation fails, and when fields contain unusually long values.

Previewing a Page is separate from publishing it. Save and test changes in development, then use Publish Project when the updated application is ready to be released.

Common Issues and Troubleshooting

Issue	What to Check
The Widget shows no records.	Verify the selected Table, available records, access permissions, and any Custom Query result.
A field is missing from the display.	Check Select Columns to Display, the selected Data Field, and screen-specific column visibility.
The table is crowded on Mobile.	Review column order, widths, and Hide on Mobile settings.
New or Edit does not open the expected Form.	Check the configured Form and the related Page Flow interaction.
A custom action uses the wrong record.	Check that the selected-row context is handled correctly.
The table does not reflect a recent change.	Refresh the data and verify the underlying operation completed successfully.
Search or pagination behaves unexpectedly.	Test the current data source, filters, query behavior, and page-navigation coordination.
CSV contents differ from expectations.	Review the current displayed fields and rows, and test export with search and pagination active.
An action is visible but fails.	Check the action configuration and the current user's permission to perform the operation.

When troubleshooting, distinguish a display configuration issue from a data source, Page Flow, or authorization issue. The visible table is only one part of the complete application workflow.

Choosing the Right Configuration

Need	Recommended Configuration
Display a straightforward record list	Select a Table and use the Widget's ordinary display behavior.
Show only important fields	Enable Select Columns to Display.
Simplify Mobile presentation	Configure Hide on Mobile for lower-priority columns.
Provide standard search, refresh, export, pagination, and New controls	Keep the toolbar visible.
Provide custom surrounding controls	Use Hide Toolbar where appropriate and configure the replacement interactions.
Display records based on another Page selection	Enable Custom Query and coordinate the data source through Page Flow.
Create or edit records from the list	Configure the relevant Form and Page Flow interaction.
Add a Project-specific record action	Configure a custom row action through supported Page Flow behavior.
Display records in a customized repeated visual layout	Use Data Design instead.

Good Practices

Show only relevant columns. Select fields that support the user's task rather than displaying every available Database field.
Name the Widget clearly. Use an identifiable element name such as Orders List or Customer Records for easier maintenance.
Keep useful controls accessible. Hide the toolbar only when its functions are unnecessary or provided elsewhere.
Use Forms for record editing. Keep New and Edit workflows focused and refresh the table after successful changes.
Use Custom Query when needed. Avoid extra Page Flow logic when ordinary table display is sufficient.
Preserve selected-row context. Custom actions should operate on the record the user actually selected.
Design for smaller screens. Choose column order and responsive visibility deliberately.
Protect the data source. Apply the appropriate access rules independently of the Widget's appearance.
Test with realistic data. Include large record sets, long field values, empty results, and records the user cannot modify.
Verify CSV output. Test downloads under the Page's actual column, search, and pagination configuration.

Technical Reference

For exact Data Table Page Flow block inputs and related API signatures, see the Programming Guide:

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:

Using a basic Table for a large, data-backed record list that needs Widget behavior.
Showing every Database field when only a few are useful to the application user.
Hiding important record identifiers on Mobile, making rows hard to recognize.
Enabling Custom Query without configuring Page Flow to supply the intended records.
Assuming that New or Edit automatically implements the complete Form workflow.
Using row actions without checking the selected record and its permissions.
Treating hidden columns or unavailable buttons as protection for sensitive data.
Assuming that CSV export always has a particular pagination scope without testing.
Refreshing the display before a save or delete operation has actually succeeded.
Replacing or renaming a Widget without reviewing Page Flow references that depend on it.
Forgetting to test empty results, failures, and responsive behavior.

The Data Table Widget is most useful when a standard record-list interface meets the Page's needs. Configure its data source and visible columns first, then add Forms and Page Flow only where the required interactions call for them.

Page Editor

Page Elements

Widgets

Data Design

Forms

Page Flow

Data Table Widget ​

When to Use a Data Table Widget ​