Skip to content

Data Table

The Data Table shows the records from a data source as rows and columns. It is the widget you reach for when visitors need to scan, sort or page through a list: orders for a customer, invoices for a month, tickets by status. You pick the fields to show, choose how each column is formatted, and the table does the rest.

See also Custom Table, Data List and Pagination.

Using it

  1. Add a data source to the page, for example a query named orders.
  2. Drop a Data Table onto the page and set its Data source to {$data.orders}.
  3. Click Generate columns. The table creates one column per field in the data.
  4. Open Column settings to rename, reorder, format or remove columns.
  5. Turn on Sorting so visitors can click a header to sort.

That gives you a working table. The sections below cover the finer settings.

Examples

// Pointing the table at its records
{$data.orders}

// A computed cell, where $record is the current row
{$record.amount} + {$record.vat}

Options

Option Values Default Description
Data source An expression, e.g. {$data.items} None The records to show. Without one, the table shows a placeholder
Transformation Steps None Select, compute, filter, sort or group the rows before the table shows them. The data source itself is not changed
Column settings Per-column settings None Opens the column editor. See Column settings
Generate columns Button None Creates one column for each field in the data. Existing columns are replaced after you confirm
Empty text Any text or template No data to show The message shown when there are no rows
Sorting Enable, Default sort field, Default sort direction Off, none, ascending Lets visitors sort by clicking a column header. The default field and direction set the order the table opens with
Selection Enable, Mode (Single · Multiple), Selection path, Key fields Off Remembers the row a visitor clicks so other widgets can react to it. See Page and Portal State
Pagination Enable, plus page, page size and page count parameters Off Splits the rows into pages. Pair it with a Pagination widget
Formatting Number, Percent, Date, Currency n;0;6, p;0;2, d, currency;;2 Default formats for the whole table. A column uses them when its Format type is one of these four. See text formats
Plain header On · Off Off Draws the header row as plain cells, without the themed header background
Lock column widths On · Off On Keeps column widths steady when the data changes
Enable scrolling On · Off On Scrolls inside the table's own box instead of making the page longer
Enable caching On · Off Off Reuses row data between redraws. Can make large tables faster
Enable buffering and Buffer size On · Off, plus a number Off Draws rows only as they scroll into view. Use it for very large sets
Per-part theme styles Theme values From theme Styling for each part of the table
Custom Style CSS Empty Extra styling for this table only
Box Style Sizing and spacing None The box around the table

Column settings

Each column has its own settings in the column editor.

Option Values Description
Field A record field Which field the column shows. Its name is also the default header text
Content type Value, Text template, HTML template, Elements, Renderer function, Row number How the cell is produced. Value shows the field and takes an optional Value expression. Elements places portal widgets inside the cell, once per row
Format type Number, Percent, Date, Currency, Custom How the value is formatted
Custom format A format string Used when Format type is Custom. See text formats
Sortable On · Off Whether clicking the header sorts the rows
Resizable On · Off Whether visitors can drag the column wider
Fixed On · Off Whether the column stays in place while the table scrolls sideways
Width (px), Col span, Row span Numbers The column width and how many columns or rows a cell spans
Aggregate Distinct, Count, Sum, Min, Max, Average, with a field, value or alias Adds a total to a footer or caption row. Average can take a Weight field
Select header On · Off Puts the selection control in the header row

Tips

A few details that help when a table does not behave as expected.

  • Inside any cell expression or template, $record is the current row.
  • Transformation only changes the rows this table shows. Other widgets reading the same data source are unaffected.
  • With pagination on and no page size chosen yet, the table shows 10 rows per page.
  • Enable buffering lives under Advanced options. Turn it on when a table has thousands of rows.
  • When you need merged cells, mixed HTML or a layout built by hand, use Custom Table instead.