How to setup Custom List Tables

Custom List Tables let you manage a MySQL table inside WordPress as if it were a native list table. With a few lines of code you get a sortable, filterable, exportable and editable interface to any database table, including the WordPress core tables, right inside the admin. A table that you expose this way is called a Data Source.

This article shows the quickest way to register your first one. For advanced setups such as permissions, joins between tables, and custom columns and field types, we keep a set of runnable examples in the Custom List Tables Cookbook on GitHub.

Requirements

Admin Columns Pro 7.1 or higher.
A MySQL table. This can be a WordPress core table or a custom table created by a plugin or your own application.
Basic PHP knowledge to add a snippet (in your theme's functions.php , a custom plugin, or a code-snippets plugin).

Registering your first Data Source

Data Sources are registered on the acp/data-sources/register action. The example below takes the wp_posts table, which every WordPress install has, and exposes it as a list table under its own admin menu item called Posts Overview.

snippet: acp/data-sources/register

Note: The examples use the default wp_ table prefix. If your install uses a different prefix, adjust the table name accordingly. We also leave out most use statements for brevity.

That is all you need. After adding the snippet you get two things:

A settings screen where you can configure which columns are visible and how they behave.
A working WordPress List Table for the wp_posts table, with sorting, filtering, inline editing and export.

How it works

The Facade\Entry::from() call is a shortcut (a "facade") that covers the most common case. Behind the scenes, it does three things for you:

Creates a Resolver, which reads the table structure.
Creates a DataSourceId, a unique identifier for the Data Source.
Creates an Entry, which maps the Data Source to a menu, capabilities and a group.

When you need more control over which columns are shown, how they behave, or how tables relate, you can use the underlying API directly instead of the facade. The cookbook shows both approaches.

Going further

A single registration call gets you a long way, but Data Sources can do much more. The cookbook has runnable recipes for:

Permissions. Control which roles and users can read, edit and delete a Data Source through the WordPress capability system. By default only Administrators have access, and core tables like wp_users can be protected from accidental edits or deletes.
Joining tables. Combine Data Sources on table, column or attribute level (for key/value structures like wp_postmeta ), with support for 1:1 and 1:M relations.
Columns and field types. Configure text, numbers, booleans, date/time, email, URLs, images, colors, dropdowns, and references to WordPress posts, users and media.

The Cookbook

The Custom List Tables Cookbook is a small companion plugin with a set of annotated, runnable examples. Copy it into wp-content/plugins/ and activate it, and a Cookbook item appears in the WordPress admin sidebar, with each enabled example as a submenu. Every folder under examples/ is self-contained and has its own readme.md . The examples are meant to be read in order, since each one builds on the previous. To enable or disable an example, comment out its require line in bootstrap.php .

The examples cover, in order:

01 Simple Users: the minimum, registering a table with no configuration.
02 Readable Labels: human-readable column labels plus a couple of typed columns.
03 Defined Columns: declare columns explicitly and filter which columns are exposed.
04 Table Relation: join tables via has_one Table and Attribute relations.
05 WooCommerce Orders: build a custom Orders screen combining four WooCommerce tables.

For class and helper documentation, grouped by registration, tables, columns and relations, see the cookbook's API reference.

For a guided, narrative walkthrough of the same concepts with screenshots, see the blog article Custom List Tables: Turn a Database Table into a WordPress List Table.

Frequently asked questions

What kind of data is supported?

At the moment, Data Sources work exclusively with MySQL tables, including WordPress core tables and custom tables created by plugins or applications.

Can I register the same table more than once?

Yes, as long as each Data Source has a unique id. This lets you expose the same underlying table in different ways, for example with different columns, relations or permissions.

Are core tables like wp_users or wp_posts treated differently?

Not by default, but a special capabilities factory can prevent any edit or delete actions on core tables, so you can't accidentally remove yourself as a user, for example.