Show rows on your site

Last updated Oct 3, 20266 min read

A list prints rows of a data table on a page, as a table or as cards. There are two ways to add one, with the same output:

the shortcode [wpmcf_table_rows];
the block Data table list (category Widgets).

Pro Elementor also has a Data table list widget built on the same engine (see Page builders).

Step 1: make columns public

A list shows only the table's public columns, and filters and sorts by public columns only. Nothing is public by default:

Open the table, go to the Settings tab.
Tick the columns the site may show under Public columns (Password columns cannot be ticked).
Click Save settings.

Everything else stays in the admin: a visitor can never read a column that is not public, not even by guessing its name in a shortcode.

The shortcode

[wpmcf_table_rows table="cities" columns="name,country,population" orderby="population" order="desc" per_page="20"]

Attribute	Default	What it does
`table`	none (required)	The key of the data table.
`columns`	all public columns	Comma-separated column keys, in the order to show them. Unknown or non-public keys are ignored. If you list columns and none of them is public, nothing is shown.
`filter`	none	Which rows to show. See Filters.
`orderby`	`id`	A public column key, or `id` (oldest first). Any other value falls back to `id`.
`order`	`asc`	`asc` or `desc`.
`per_page`	`10`	Rows per page, from 1 to 50 (larger numbers become 50).
`limit`	`0`	The most rows the list ever shows, over all pages. `0` means no cap (the hard maximum is 10,000).
`layout`	`table`	`table` or `cards`.
`empty`	`Nothing to show yet.`	Text when no row matches.
`id`	the table key	The list's name in page links and its HTML anchor. Set it when you show the same table twice on one page.

Column labels in the heading come from the table's column labels (the key when a label is empty).

Filters

filter is a list of conditions written column:operator:value, separated by semicolons. All conditions must be true.

filter="price:gte:10;price:lt:25;country:eq:Norway"

Operator	Matches
`eq`	equal to the value (this is the default when the operator is left out)
`neq`	not equal
`gt`, `gte`, `lt`, `lte`	greater than, greater or equal, less than, less or equal (numbers compare as numbers)
`like`	the column contains the value
`not_like`	the column does not contain the value
`empty`	the column has no value (no third part needed: `site:empty`)
`not_empty`	the column has a value

Rules:

The column must be public. A condition on any other column, a misspelled operator or an unsupported one (such as in) is silently dropped, so the list may show more rows than you expected. If a filter seems to do nothing, check that the column is public.
At most ten conditions. The value may contain colons but not semicolons.
Select and Radio columns hold the choice value: filter by level:eq:a, not by the label.
True / false columns hold 1 or 0: active:eq:1.

Paging

When there are more rows than per_page the list ends with a navigation: Previous, Page 1 of 4 and Next. The page number travels in the address as ?wpmcf_rows_{id}=2 (where {id} is the list's id, or the table key) and the link ends in #wpmcf-rows-{id}, so the visitor stays at the list. A page number past the end shows the last page. Two lists on one page page independently when they have different id values.

Layouts

table (default): a table with a heading row; wrapped in a scrolling container, and on narrow screens each cell shows its column label.
cards: one card per row with the column label and the value as a definition list.

The CSS comes from a small stylesheet that is loaded only on pages that contain a list. Classes you can style: wpmcf-rows, wpmcf-rows--table, wpmcf-rows--cards, wpmcf-rows__scroll, wpmcf-rows__table, wpmcf-rows__cards, wpmcf-rows__card, wpmcf-rows__empty, wpmcf-rows__pages, wpmcf-rows__page-link, wpmcf-rows__page. The block adds the usual wp-block-wpmcf-table-rows wrapper.

The block

In the editor click + and search for Data table list (or "table", "rows", "list", "data").
Choose the table in Data table › Table. With no tables the panel says "No data tables available. Create one under WPM Fields › Data Tables."
Set the options:

Panel	Setting	Same as shortcode
Data table	Table	`table`
Data table	Columns (one checkbox per public column; all ticked means all)	`columns`
Data table	Filter (help: `column:operator:value; ...`)	`filter`
Display	Order by (ID or a public column), Order (Ascending, Descending)	`orderby`, `order`
Display	Rows per page, Maximum rows (help: "0 shows all rows.")	`per_page`, `limit`
Display	Layout (Table, Cards), Empty text	`layout`, `empty`

The block shows a live preview in the editor. Before a table is chosen it shows Data table list: "Choose a data table in the block settings." The block does not have an id setting, so two blocks for the same table on one page share their paging; use the shortcode with id for that case. The block supports wide and full alignment, margin and padding.

What the list prints

Values are printed safely, because rows can come from visitors (forms, connections):

Column type	Output
Text, Text area, Email, URL, Select, Radio, Button group, Color, Range, Number	Escaped text. A Select prints its label. A Number prints without trailing zeros (`10` for `10.000000`). A URL prints as text, not a link.
True / false	Yes, or empty when the value is empty.
Date, Date and time, Time	In your site's date and time format (`January 31, 2024`).
WYSIWYG editor	Cleaned HTML: scripts and shortcodes are removed.
Image, File	The usual image or file output of the field type.
Post object, Page link, Programmatic SEO page	The link, only when the post is published and public and not password-protected; otherwise empty.
Icon picker	The icon.

An empty value is an empty cell.

Caching

The finished HTML of each list page is cached (object cache, up to an hour) and refreshed the moment the table changes: adding, editing or deleting a row, an import, a sync or a change to the columns. You do not need to clear anything. With a page cache plugin in front, remember that the cached page also needs to be purged after you change rows; see your caching plugin.

What visitors and editors see when something is wrong

Situation	Visitors	Editors (anyone who can edit posts)
Table key missing or unknown	nothing	"Choose an existing data table for this list."
No public column to show	nothing	"This list has no column to show. Mark columns as public under Data Tables › Settings."
A site without data tables (free plugin, or a trial that ended)	nothing	"Data table lists need a plan that includes data tables."
An expired paid license	the list keeps printing as before	the list
Filter matches no row	the `empty` text	the `empty` text

Page builders

The Pro Elementor integration has a Data table list widget that prints the same list (controls: Data table, Columns, Filter, Order by column, Order, Rows per page, Most rows (0 = all), Layout, Text when empty, plus style options). It follows the same public-column rules. See Pro fields, admin columns and page builders.

Programmatic SEO

A table you list on a page can also be the source of generated pages: see Programmatic SEO. The same public-column rule does not apply to Programmatic SEO: a task reads every column of its source, because pages are built on the server.

Was this page helpful?

Still stuck? Contact support