Skip to content
This repository was archived by the owner on Nov 18, 2026. It is now read-only.
arraypressPublic archive

About

Declarative admin list tables for BerlinDB-backed data — columns, views, filters, row and bulk actions, without writing a WP_List_Table.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

This library has moved. It is now part of sugarcommerce/tables (namespace SugarCommerce\Tables, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.

Register Tables

A WordPress list table for your own data — the screen, the menu, the search, the sorting and the paging — from a description of the columns.

What it does

WP_List_Table is a class you extend, and extending it means implementing half a dozen methods before anything appears: the columns, the rows, the sortable list, the bulk actions, the pagination, the search, plus the menu page around it. It is a day's work for a table of orders, and the next table is the same day again.

This takes the description instead. You supply a callback that returns rows and one that counts them; everything from the menu to the "no items found" message follows.

Features

  • Get a working list-table screen from a callback and a list of columns
  • Search, sort and paginate without implementing any of the three
  • Add status views along the top, with counts beside each
  • Add filters, bulk actions and row actions to the same table
  • Read rows, counts and related rows from a BerlinDB table by naming its query class
  • Offer each row its next status, and say what moved by name
  • Format a column as a price, a date, a status badge or a country, by naming the type
  • Draw a person, or one thing with its picture, the same way on every list
  • Let each person choose relative or exact dates, and skip columns nobody is looking at
  • Make a cell a switch that saves itself -- a star, or a line of words
  • Let rows be dragged into an order somebody chooses
  • Light the rows that are new since each person last looked, and count them on the menu
  • Hang the screen off any menu — top level, a post type, Tools, Settings
  • Get core's own list-screen heading, with the add button beside it

Installation

composer require arraypress/wp-register-tables

Quick start

register_admin_table( 'my_orders', [
	'page_title' => __( 'Orders', 'my-plugin' ),
	'menu_title' => __( 'Orders', 'my-plugin' ),
	'menu_slug'  => 'my-orders',
	'capability' => 'manage_options',
	'icon'       => 'dashicons-cart',

	'labels'     => [
		'singular' => __( 'order', 'my-plugin' ),
		'plural'   => __( 'orders', 'my-plugin' ),
	],

	'callbacks'  => [
		'get_items'  => '\MyPlugin\get_orders',
		'get_counts' => '\MyPlugin\get_order_counts',
	],

	'columns'    => [
		'id'      => [ 'label' => __( 'Order', 'my-plugin' ), 'sortable' => true ],
		'total'   => [ 'label' => __( 'Total', 'my-plugin' ), 'type' => 'price' ],
		'status'  => [ 'label' => __( 'Status', 'my-plugin' ), 'type' => 'status' ],
		'created' => [ 'label' => __( 'Date', 'my-plugin' ), 'type' => 'date' ],
	],
] );

get_items is handed the query — search, sort, page, filters, already resolved — and returns rows. That is the only part that knows about your data.

A title with states

A structured column's states go inside the title's <strong>, so they sit on the same line as the name, the way core shows "— Draft" on the Posts list. (Core's stylesheet makes that <strong> a block, so anything placed after it, after included, starts a new line.) Return escaped markup, or an empty string for none:

'title' => [
	'label'  => __( 'Product', 'my-plugin' ),
	'title'  => static fn( object $row ): string => $row->title,
	'link'   => 'edit_flyout',
	'states' => static fn( object $row ): string => 'draft' === $row->status
		? ' &mdash; <span class="post-state">' . esc_html__( 'Draft', 'my-plugin' ) . '</span>'
		: '',
],

Opening a row in a panel

With wp-register-flyouts installed, a title can open the row's panel and a row action can be its Edit link. flyouts names the table's panels by their full id; a row action's flyout is true for the edit panel or a panel's own id:

'flyouts'     => [ 'edit' => 'shop_edit_order' ],
'columns'     => [
	'title' => [ 'label' => __( 'Order', 'my-plugin' ), 'title' => 'my_plugin_order_title', 'link' => 'edit_flyout' ],
],
'row_actions' => [
	'edit'    => [ 'label' => __( 'Edit', 'my-plugin' ), 'flyout' => true ],
	'refunds' => [ 'label' => __( 'Refunds', 'my-plugin' ), 'flyout' => 'shop_order_refunds' ],
],

The link is made by the flyout library's Registry class, never its global get_flyout_link(), so a copy bundled with Strauss reaches its own prefixed flyouts and not another plugin's. Without the flyout library (or without the capability the panel asks) the title is drawn unlinked and the action is left out. The add_button and the empty list's button work the same way, and a sync button goes through wp-inline-sync's class.

A figure under a column

A column's footer puts a figure for the whole view -- every page of it, as searched, filtered and narrowed to a status -- in that column's cell of the footer row, where core repeats the heading. It is handed the same query arguments get_items is, less the page and the order, and how many rows the view has; it returns escaped markup, and a <small> in it is a quieter second line:

'total' => [
	'label'  => __( 'Total', 'my-plugin' ),
	'footer' => static fn( array $args, int $count ): string => '<strong>'
		. esc_html( my_plugin_sum_orders( $args ) )
		. '</strong> <small>' . esc_html( sprintf( __( 'for all %d orders', 'my-plugin' ), $count ) ) . '</small>',
],

It is asked once a request, and not at all while the view is empty. Where the cell is not on screen -- the column switched off in Screen Options, or a phone, where core shows only the primary column -- the figure is shown in the bottom navigation instead, after the column's name.

A filter with too many choices to list

A dropdown of every product stops being usable at a few hundred. A filter of 'type' => 'search' is the field kit's searchable select instead, asking a field-kit search source over REST as somebody types -- the same source a settings field names, registered once with Sources::shared()->register():

'filters' => [
	'product_id' => [
		'type'           => 'search',
		'label'          => __( 'All Products', 'my-plugin' ),
		'source'         => 'my_products',
		// The kit's ajax-field contract: ( '', [ $value ], $args ) => [ [ 'id', 'text' ] ].
		'label_callback' => [ My_Search::class, 'products' ],
		'chip'           => __( 'Product: %s', 'my-plugin' ),
		'clears'         => [ 'price_id' ],
	],
	// No source: not drawn, but carried and shown as a chip while it is set.
	'price_id'   => [ 'type' => 'search', 'chip' => __( 'Price: %s', 'my-plugin' ) ],
],

The value reaches get_items under its key like any filter's. While one is on, a chip above the table names it and its cross takes that one filter off; the status links keep it, and get_counts is handed its query arguments so their counts are counted within it.

What the list says after an action

After a row action, a bulk action, Bulk Edit, Quick Edit or Delete, the list says what happened and to what -- "Elena Okafor was blocked.", "3 orders marked as complete." -- in the consumer's words, named by the table's own title (or an item_name callback). The sentence is kept on the server for whoever did it and only a token goes in the redirect, which lands back on the view the action was taken from: status, search, filters, sort and page.

'bulk_actions' => [
	'block' => [
		'label'    => __( 'Block', 'my-plugin' ),
		'messages' => [
			'one'  => __( '%s was blocked.', 'my-plugin' ),      // the name
			'some' => __( '%s were blocked.', 'my-plugin' ),     // up to three names
			'many' => __( '%s customers blocked.', 'my-plugin' ), // the count
		],
	],
],
// Bulk Edit, Quick Edit and Delete are worded in the table's own `messages`,
// as `edit`, `quick_edit` and `delete`; a callable gets the whole outcome.
'messages' => [ 'quick_edit' => static fn( array $outcome ): string => '...' ],

A handler that could not change a row says so, and the notice says which and why: ArrayPress\RegisterTables\Outcome::fail( $id, 'Order #98 is refunded' );.

Rows from a BerlinDB table

Sources\BerlinDB::callbacks() turns the table's request into BerlinDB query arguments, so a list declares where its rows are and gets rows, the pager's count, the counts beside the status links, the row Quick Edit redraws, Delete, and the update a status move writes through:

use ArrayPress\RegisterTables\Sources\BerlinDB;

'callbacks' => BerlinDB::callbacks( [
	'query'      => \MyPlugin\Database\Queries\Order::class,
	'statuses'   => [ 'complete', 'pending', 'refunded' ], // counted for the views
	'filters'    => [ 'country', 'gateway' ],              // passed through as columns
	'filter_ids' => [ 'customer' => 'customer_id' ],        // an id: 0 or junk matches nothing
	'scope'      => static fn(): array => [ 'is_test' => my_plugin_is_test_mode() ? 1 : 0 ],
	'prime'      => [ 'customer_id' => \MyPlugin\Database\Queries\Customer::class ],
] ),
  • number and offset are read, as the library sends them -- not per_page and paged -- and search, not the request's s. A page is at most 999 rows.
  • Only declared filters reach the query. scope is applied last, so nothing in the address steps outside it (a test mode, an owner).
  • Asked with count, get_items answers how many match, which is how the pager counts a searched or filtered view; get_counts is counted within the scope and within any search filter that is on.
  • A country's name finds its rows. When country is one of the filters, "germany", "Germ" and "de" all find the DE rows as well as rows whose words match ('country_search' => false to turn it off, or a callable ( string $term ): string[] for a site's own names). search_also widens a search other ways -- [ 'customer_id__in' => fn( $term ) => my_plugin_customer_ids( $term ) ] -- and search_limit caps each half (default: every id, so the pager never lies).
  • prime fetches what a page's rows point at in one query per column: a BerlinDB Query class (its object cache answers the cells afterwards), or a callable given the ids. also is handed the page's rows.

Any of get, count, one, delete and update can be given as a callable instead of coming from query -- how a plugin keeps the filters its own wrapper functions apply. BerlinDB::query_args( $args, $options ) is public, for a list that builds its own query around the same reading.

Moving a row's status

transitions are keyed by the status a row is in: each row offers its next move -- a draft is published, an archived thing restored -- and never the status it already has. A bulk action with a status sets it on every ticked row. Both write through callbacks.set_status ( $id, $status ), or, failing that, callbacks.update ( $id, [ 'status' => ... ] ), which the BerlinDB source provides. Only a false is a failure.

'transitions'  => [
	'active'   => [ 'disabled' => __( 'Block', 'my-plugin' ) ],
	'disabled' => [ 'active' => __( 'Unblock', 'my-plugin' ) ],
],
'bulk_actions' => [
	'block' => [ 'label' => __( 'Block', 'my-plugin' ), 'status' => 'disabled' ],
],
// The word for a status inside a sentence; default the view's label.
'status_label' => static fn( string $status ): string => my_plugin_status_label( $status ),

The list then says "Elena Okafor is now blocked." or "12 customers are now blocked.", and of a ticked row already there, "1 could not be changed: Kira Ito is already blocked." A table's own messages or callback on an action is left alone. For a handler of your own, Transitions::already( $table_id, $row, $status ) says "already" the same way, and Transitions::edited_messages( $table_id ) words a Quick Edit or Bulk Edit that set a status (as the table's messages quick_edit and edit).

A switch in a cell

A column's toggle makes each cell a button that saves itself over REST and redraws in place: a star (a glyph, as WooCommerce marks a featured product) or a line of words under something else ("✓ Subscribed" / "Not subscribed"). Pressed, it turns over at once; if the save is refused it turns back and says so beside itself. aria-pressed says whether it is on, the new state is read out, and focus never leaves it. Somebody without the capability sees the state and no button.

'columns' => [
	'featured' => [
		'label'  => ArrayPress\RegisterTables\Toggle::heading( __( 'Featured', 'my-plugin' ) ),
		'width'  => '4em',
		'toggle' => [
			'style'        => 'star',
			'on'           => __( 'Featured', 'my-plugin' ),
			'off'          => __( 'Not featured', 'my-plugin' ),
			'turn_on'      => __( 'Mark as Featured', 'my-plugin' ),
			'turn_off'     => __( 'Remove from Featured', 'my-plugin' ),
			// The button's name, with the row's: twenty buttons called
			// "Mark as Featured" cannot be told apart by ear.
			'turn_on_row'  => __( 'Mark “%s” as Featured', 'my-plugin' ),
			'turn_off_row' => __( 'Remove “%s” from Featured', 'my-plugin' ),
			// Any icon in either form (see Icons); this pair is a star's default.
			'icons'        => [ 'on' => 'heroicons-solid:star', 'off' => 'heroicons-outline:star' ],
			'done_on'      => __( '“%s” marked as featured.', 'my-plugin' ),
			'done_off'     => __( '“%s” removed from featured.', 'my-plugin' ),
			// Your own route: the id fills {id}, the body is { key: true|false } plus `data`.
			'rest'         => [ 'path' => 'my-plugin/v1/products/{id}', 'method' => 'PATCH', 'key' => 'is_featured' ],
			'capability'   => 'edit_products',
		],
	],
	'consent'  => [
		'label'  => __( 'Email', 'my-plugin' ),
		'toggle' => [
			'field'       => 'marketing_consent',         // the row's property; the column key by default
			'on'          => __( 'Subscribed', 'my-plugin' ),
			'off'         => __( 'Not subscribed', 'my-plugin' ),
			'name'        => __( 'Subscribed to Marketing', 'my-plugin' ), // a fixed name instead
			'turn_on'     => __( 'Mark as Subscribed', 'my-plugin' ),
			'turn_off'    => __( 'Mark as Not Subscribed', 'my-plugin' ),
			// Said before the first "on" ever (per browser), which then waits for a second press.
			'confirm_on'  => __( 'Only do this if they agreed to hear from you.', 'my-plugin' ),
			'press_again' => __( 'Press again to mark them as subscribed.', 'my-plugin' ),
			'since'       => static fn( $row ): string => sprintf( __( 'Since %s', 'my-plugin' ), my_plugin_day( $row->date_consent ) ),
			'say_why'     => true,                         // show the server's message, not `failed`
			// Or no `rest`: the library's own route checks the capability and calls this.
			'save'        => static fn( int $id, bool $on ): bool => my_plugin_set_consent( $id, $on ),
		],
	],
],

A toggle that belongs inside another cell -- the line under an address -- is declared under the table's toggles by a key of its own, and drawn from that column's callback:

'toggles' => [ 'consent' => [ /* as above */ ] ],
'columns' => [
	'email' => [
		'label'    => __( 'Email', 'my-plugin' ),
		'callback' => static fn( $row ): string => esc_html( $row->email )
			. ArrayPress\RegisterTables\Toggle::render( 'my_customers', 'consent', $row ),
	],
],

With rest, the answer is read back for the state (rest.state, the key by default) and, if rest.since names a date field, the tooltip's since_label ("Since %s"). With save, the route is arraypress-tables/v1/{table_id}/toggle/{id}; save answers true, false, a WP_Error, or [ 'on' => bool, 'since' => string ]. Register the table by init, so the route exists on the REST request. failed (default "Not saved. Try again.") is what a refused save says.

A star is heroicons-solid:star when on and heroicons-outline:star when off; a line has heroicons-outline:check before "on" and nothing before "off" (an icons state of '' draws none). Toggle::heading( $word, $icon ) heads the column with heroicons-solid:star unless given another icon -- Toggle::heading( __( 'Loved', 'my-plugin' ), 'heroicons-outline:heart' ).

Rows in an order somebody chooses

reorder gives one column a drag handle and up and down buttons, and saves the order the rows end up in. The handle drags with a mouse or a finger and answers the arrow keys; below core's 782px breakpoint, where a row cannot be dragged along a folded column, the buttons take over. Each move posts the page's ids, top to bottom, and says where the row went.

register_admin_table( 'my_collections', [
	// ...
	'orderby'  => 'sort_order',
	'order'    => 'asc',
	'per_page' => 100, // a row is only dragged past rows on its own page
	'columns'  => [
		'name'       => [ 'label' => __( 'Collection', 'my-plugin' ), 'title' => 'my_plugin_name', 'link' => 'edit_flyout' ],
		'sort_order' => __( 'Position', 'my-plugin' ),
	],
	'reorder'  => [
		'column'   => 'sort_order',                         // where the handle goes
		'save'     => static fn( array $ids ): bool => my_plugin_reorder( $ids ),
		// Optional:
		'orderby'  => 'sort_order',                         // the sort that is this order; `column` by default
		'position' => static fn( $row ): int => my_plugin_place( $row ), // the place to show when sorted otherwise
		'filtered' => false,                                // allow moving within a status or filter
		'labels'   => [ 'moved' => __( '“%1$s” moved to position %2$s of %3$s.', 'my-plugin' ) ],
	],
] );

The controls are drawn only while the list shows that order: not sorted by another column (or by this one going down), not searched, and not narrowed by a status or filter unless filtered says so. The number is the row's place, first is 1. The save goes through admin-ajax with the table's own nonce and the table's edit capability (or capability); save gets the ids as integers and may return an array, which is handed back.

A person

A column of 'type' => 'person' draws someone the way every WordPress list does: their picture, their name as the link, and their address as a quieter line under it, each cut short with an ellipsis and whole in its tooltip. The address is text, not a mailto. With no name the address stands in for it, once; with nothing to open, the cell is text; with nobody, a dash.

'customer' => [
	'label'      => __( 'Customer', 'my-plugin' ),
	'type'       => 'person',
	// Who the row's person is: name, email, id, and `after` -- escaped
	// markup that ends the name's line (tags, a link to their other rows).
	// Null is nobody. Left out, the row's own name, email and id.
	'person'     => static fn( object $order ): ?array => [
		'name'  => $order->customer_name,
		'email' => $order->email,
		'id'    => (int) $order->customer_id,
		'after' => my_plugin_customer_tags( $order ),
	],
	// The table's 'view_flyout' or 'edit_flyout', a panel's full id, a URL,
	// or a closure returning one.
	'link'       => 'view_flyout',
	// ( $email, $name, $size, $args ) => escaped markup; false for none.
	// Left out, core's get_avatar(). $args carries the float to keep.
	'avatar'     => static fn( string $email, string $name, int $size, array $args ): string => my_plugin_monogram( $email, $name, $size, $args ),
	'email_line' => true, // false when the address has a column of its own
],

The cell lays itself out with inline styles, so it is the same inside a panel's table on a screen that never loaded this library's stylesheet. It is ArrayPress\RegisterTables\Cells\Person::cell( $parts ) for a cell drawn by hand, and arraypress_table_person_cell_{table_id} filters it in a table. A link given the class arraypress-reveal at the end of the name's line is shown, like a row action, only while the row is pointed at or focused.

One thing a row names, with its picture

A column of 'type' => 'item' is what an order's Items cell is: a small picture, the name on one line with its tooltip, "+ 2 others" beside it, and quieter lines beneath. Its item callable returns the parts:

'items' => [
	'label' => __( 'Items', 'my-plugin' ),
	'type'  => 'item',
	'item'  => static fn( object $order ): array => [
		'title'   => $order->first_item_name,        // text
		'link'    => '',                             // escaped markup in place of the title
		'tooltip' => implode( ', ', $order->names ), // text; the title when left out
		'more'    => count( $order->names ) - 1,     // "+ 2 others"; or your own text
		'picture' => ArrayPress\RegisterTables\Cells\Item::picture( (int) $order->image_id, 'box', 24 ),
		'lines'   => [ esc_html( $order->downloads_line ) ], // escaped markup, a line each
	],
],

Item::picture( $image_id, $kind, $size ) is the attachment, or a drawn placeholder tile -- an inline data URI, never a request -- when there is none or it has gone: box for a thing, stack for a group of things, or [ 'placeholder' => $svg ] for a glyph of your own in a forty-unit square. Under forty pixels it is a square that says nothing aloud, for beside a name. Item::cell( $parts ) draws one by hand; arraypress_table_item_cell_{table_id} filters it in a table.

Relative or exact dates

A date column says "2 weeks ago", with the exact moment on hover. Give the table a date_preference and Screen Options gains "Dates: Relative / Exact", a choice kept for each person: Exact says "13 Oct 2026, 3:20 pm" with how long ago on hover. The same words at any age -- "2 years ago" never turns into a date half way down a column -- and "in 3 weeks" for one to come.

register_admin_table( 'my_orders', [
	// true: a preference of this table's own (`my_orders_dates`).
	// A string: a user meta key every list naming it shares, so the choice
	// made on one list holds on all of them.
	'date_preference' => 'my_plugin_list_dates',
	'columns'         => [
		'date_created' => __( 'Date', 'my-plugin' ),
		'date_expires' => [ 'label' => __( 'Expires', 'my-plugin' ), 'type' => 'date', 'none' => __( 'Never', 'my-plugin' ) ],
	],
] );

BerlinDB's zero date is no date, and says the column's none or a dash. A column's format replaces the exact reading's date format. It is saved by core's own Apply, in the same form and under the nonce core already checked. For a cell drawn by hand:

use ArrayPress\RegisterTables\ListDate;

ListDate::cell( $row->date_renews, ListDate::mode( 'my_plugin_list_dates' ), [ 'none' => __( 'Never', 'my-plugin' ) ] );

arraypress_table_date_mode_{meta_key} can answer relative or exact for everybody.

A column that costs something to show

A column that asks another table -- what a customer last bought, where a key was last used -- is still worked out by core while it is switched off in Screen Options. Declare it 'deferred' => true and, while it is hidden, its cells hold a placeholder and its callback is never called; switched on, the list reloads once core has saved the choice, and the column is drawn.

'last_order' => [
	'label'    => __( 'Last Order', 'my-plugin' ),
	'hidden'   => true,
	'deferred' => true,
	'callback' => 'my_plugin_last_order_cell',
],

A column with something it can show for free sets 'deferred' => 'manual' and decides itself, with HiddenColumns::is_hidden( $table_id, $column ) and HiddenColumns::placeholder() -- which is also how a get_items skips priming what a hidden column would have asked for. arraypress_table_column_hidden_{table_id} can say a column is read off the page whether it is shown or not.

New since you last looked

A list can light the rows that have arrived since whoever is looking last opened it -- each person's own, so two people running one site never clear each other's -- and count them beside its menu item, the way Comments does. What is remembered is the id of the newest row there was at their last visit, in user meta named for the table ({table_id}_seen), so "new" is a question the primary key answers. And no older than a window of days (seven unless you say), which is what keeps a fortnight away, or a first visit, from lighting everything.

'seen' => [
	'label'      => __( 'New order', 'my-plugin' ), // read aloud on a new row
	'table'      => 'shop_orders',                   // without $wpdb->prefix; default: the table id
	'columns'    => [ 'id' => 'id', 'created' => 'date_created' ],
	'window'     => 7,                               // days, or a callable; 0 for no limit

	// Kept apart: a marker for each set, and only the set showing counts.
	'scopes'     => [ 'test' => [ 'is_test' => 1 ], 'live' => [ 'is_test' => 0 ] ],
	'scope'      => static fn(): string => my_plugin_is_test_mode() ? 'test' : 'live',

	// Never news, however lately they arrived.
	'except'     => [ 'status' => [ 'refunded', 'failed', 'cancelled' ] ],

	// Rows arriving or going, so a count kept for a minute is not believed.
	'changed'    => [ 'my_plugin_add_order', 'my_plugin_delete_order' ],

	// Rows somebody made by hand are not news to them. A callable is given
	// the action's arguments and answers with the row's id, nought for
	// "not by hand", or [ id, set ].
	'by_hand'    => [
		'my_plugin_order_completed' => static fn( $id, $session = null ) => null === $session ? (int) $id : 0,
	],

	'ready'      => 'my_plugin_tables_installed', // nothing is asked until true
	'menu_count' => [
		'text' => static fn( int $count, string $number ): string => sprintf(
			/* translators: %s: a number of orders. */
			_n( '%s new order', '%s new orders', $count, 'my-plugin' ),
			$number
		),
	],
],

A row is lit for the visit that sees it and plain on the next: the marker is read as the list is opened and moved once the rows are out, forwards only, so two tabs and the back button cannot bring seen rows back, and a row that arrives while the page is being built is still new next time. A row redrawn on its own after a Quick Edit comes back lit as it was.

Hearing about a row reads nothing, and is all that is hooked outside the list's own screen. Tables registered on admin screens only should also call ArrayPress\RegisterTables\Seen\Seen::register( 'shop_orders', [ 'seen' => [ ... ] ] ) on every request, so a row made in a webhook is heard. The count is one query (or a count callable, for rows that are not a table of their own, with newest beside it), kept in the object cache for a minute.

Seen::count( 'shop_orders' ) is the figure the bubble shows, for a dashboard or an app; Seen::mark_all( 'shop_orders' ) says somebody has seen everything; Seen::is_new( 'shop_orders', $row ) answers for one row. The bubble is menu_count: beside the list and beside its parent ('parent' => false for the list alone), "99+" past ninety-nine with the real number read aloud, and never on the list's own screen.

Lit rows

The ways a row can be lit, tried in order of priority; the first a row is in wins. A table with seen has new (green, 50) without saying so, and blocked (red, 10) and excused (amber, 20) when its seen names blocked rows and an excused callable. Add your own, or change those, in highlights:

'highlights' => [
	'class'  => 'my-plugin-row', // rows get `my-plugin-row-{state}`; default `arraypress-row`
	'states' => [
		'attention' => [
			'label'    => '',        // what it is read aloud as; empty when the row says why in words
			'color'    => '#dba617', // the bar
			'tint'     => true,      // and a tenth of it behind the row
			'priority' => 30,
			'forced'   => 'double',  // high-contrast mode: highlight, double, dashed or solid
			'when'     => static fn( object $row, string $table_id ): bool => 'disputed' === $row->status,
		],
	],
],

A lit row is a bar down its start edge -- the mark core gives a comment waiting to be approved -- as a real border in logical properties, so it is on the right in a right-to-left admin and kept by a high-contrast mode, where the states are told apart by line style. Its words are read aloud in the row's first cell, before the row actions ('announce' => false to place Highlights::label() yourself). Nothing moves. The stylesheet loads only on a list that lights rows, and takes the cream off a pending row there, since a tint means "wants attention". Highlights::for_list( $registry, 'orders' ) picks one list's states out of a registry shared by several, each naming its lists and, where it has a better word for one, labels.

Icons

Everything here that takes an icon takes it in either form the field kit's Icons::render() reads: a set:name value -- heroicons-outline:inbox, heroicons-solid:heart, any set the kit has -- drawn as inline SVG in the text's colour, or a Dashicons name, cart or dashicons-cart, drawn as the font's span exactly as before. Either way it carries the arraypress-icon class, which the stylesheets size it by.

Where Default
empty_state.icon -- the glyph over an empty list; '' for none heroicons-outline:inbox
A toggle's icons -- [ 'on' => …, 'off' => … ] star: heroicons-solid:star / heroicons-outline:star; line: heroicons-outline:check / none
Toggle::heading( $word, $icon ) heroicons-solid:star
'empty_state' => [
	'icon'        => 'heroicons-outline:shopping-cart', // or 'dashicons-cart'
	'heading'     => __( 'No orders yet.', 'my-plugin' ),
	'description' => __( 'Orders appear here as customers check out.', 'my-plugin' ),
],

The library's own glyphs are Heroicons too: a boolean column's yes (check-circle) and no (minus), and the reorder handle (bars-3) and its buttons (chevron-up, chevron-down). The top-level menu's icon is WordPress's own add_menu_page() argument -- a Dashicons class, an image URL or a data:image/svg+xml;base64, URI -- and is passed to it unchanged.

Hooks

Every hook is suffixed with the table's own id, so a filter written for one plugin's orders table never reaches another's. {table_id} below is whatever was passed to register_admin_table().

Filters

Hook Filters
arraypress_table_columns_{table_id} The columns, after the config is read
arraypress_table_hidden_columns_{table_id} Which columns start hidden
arraypress_table_sortable_columns_{table_id} Which columns can be sorted
arraypress_table_views_{table_id} The status links above the table
arraypress_table_row_actions_{table_id} The actions under a row
arraypress_table_bulk_actions_{table_id} The bulk actions dropdown
arraypress_table_query_args_{table_id} The arguments before items are fetched
arraypress_table_admin_notices_{table_id} The notices shown above the table
arraypress_table_quick_edit_fields_{table_id} The fields in the Quick Edit row
arraypress_table_bulk_edit_fields_{table_id} The fields in the Bulk Edit row
arraypress_table_person_cell_{table_id} A person cell, with its parts and the row
arraypress_table_item_cell_{table_id} An item cell, with its parts and the row
arraypress_table_column_hidden_{table_id} Whether a column counts as hidden, for not working it out
arraypress_table_date_mode_{meta_key} relative or exact, for everyone sharing a date preference
arraypress_table_seen_capability_{table_id} Who is told what is new on the list
arraypress_table_new_count_{table_id} How many rows are new to somebody
arraypress_table_highlights_{table_id} The ways a row can be lit
arraypress_table_row_highlight_{table_id} How one row is lit
arraypress_table_highlight_label_{table_id} What a lit row says aloud

Actions

Hook Fires
arraypress_after_render_table_header_{table_id} After the heading and notices, before the status links
arraypress_before_render_table_{table_id} Before the table is drawn
arraypress_after_render_table_{table_id} After the table is drawn
arraypress_table_single_action_{table_id} A row action with no handler of its own
arraypress_table_bulk_action_{table_id} A bulk action was applied
arraypress_table_item_deleted_{table_id} An item was deleted
arraypress_table_quick_edit_{table_id} One row was quick edited
arraypress_table_bulk_edit_{table_id} An edit was applied to a selection
arraypress_table_inline_edit_{table_id} Inside either inline editor, to print extra markup
arraypress_table_toggled_{table_id} A toggle cell saved through the library's route: ( $id, $column, $on )
arraypress_table_reordered_{table_id} Rows were put in a new order: ( $ids )

A bulk action also fires a second, narrower action naming the action itself, which is usually the one worth hooking:

add_action( 'arraypress_table_bulk_action_{table_id}_{action}', function ( array $ids ) {
	foreach ( $ids as $id ) {
		my_plugin_refund_order( (int) $id );
	}
} );

Both the table id and the action name are substituted, and the broader hook in the table above still fires alongside it.

Quick Edit and Bulk Edit

Core's two inline editors, on a table that is not a post type. Declaring either one is enough -- a table with only quick_edit gets the same fields in its bulk row, and the other way round.

register_admin_table( 'my_products', [
	// ...
	'quick_edit'   => [
		'status' => [
			'label'   => __( 'Status', 'my-plugin' ),
			'options' => [
				'active' => __( 'Active', 'my-plugin' ),
				'draft'  => __( 'Draft', 'my-plugin' ),
			],
		],
	],
	'bulk_actions' => [ 'edit' => __( 'Bulk edit', 'my-plugin' ) ],
	'callbacks'    => [
		'get_item' => 'my_plugin_get_product',
	],
] );

Neither editor writes anything. They validate what was submitted -- a select only accepts a value it actually offered -- and then fire an action, because only you know whether a status change also has to reach somewhere else:

add_action( 'arraypress_table_quick_edit_{table_id}', function ( int $id, array $values ) {
	my_plugin_update_product( $id, $values );
}, 10, 2 );

add_action( 'arraypress_table_bulk_edit_{table_id}', function ( array $ids, array $values ) {
	foreach ( $ids as $id ) {
		my_plugin_update_product( (int) $id, $values );
	}
}, 10, 2 );

A checklist

A field with 'type' => 'checklist' is core's category checklist: the scrolling list of boxes the Posts screen's Quick Edit and Bulk Edit show for categories, in the same middle column with the same classes, so core's stylesheet draws it. For anything a row can be in several of -- collections, tags, groups. options are what can be ticked; value says what a row is in, when that is not a property of the row (an array or a comma list either way).

'quick_edit' => [
	'collections' => [
		'type'    => 'checklist',
		'label'   => __( 'Collections', 'my-plugin' ),
		'options' => [ 3 => 'Drums', 5 => 'Loops' ],          // id => name
		'value'   => fn( $row ) => my_plugin_collection_ids( $row->id ),
	],
],

Quick Edit opens with the row's own boxes ticked and hands the save the ids now ticked, as strings -- [ '3', '5' ], or [] when every box was cleared. Bulk Edit behaves as core's does in WordPress 7.1: a box every selected row has opens ticked, one only some have opens half-ticked, and the save receives what to change rather than a list to set:

add_action( 'arraypress_table_bulk_edit_{table_id}', function ( array $ids, array $values ) {
	// [ 'add' => [ '3' ], 'remove' => [ '5' ] ] -- a half-ticked box left
	// alone is in neither, so each row keeps its own answer for it.
	$change = $values['collections'] ?? null;

	foreach ( $ids as $id ) {
		$now = array_diff( my_plugin_collection_ids( $id ), $change['remove'] );
		my_plugin_set_collections( $id, array_unique( array_merge( $now, $change['add'] ) ) );
	}
}, 10, 2 );

Unticking a box every selected row had takes it off all of them, as it does for a category. Either editor leaves the key out when the field was not posted at all, which is "leave it alone".

Two things are worth knowing. 'edit' in bulk_actions is what reveals the bulk row -- without it there is a bulk editor nothing opens. And Quick Edit redraws the saved row from callbacks.get_item; leave that out and the save happens but the row does not change, which reads exactly like a save that failed.

Requirements

  • PHP 8.3 or later
  • WordPress 7.1 or later

License

GPL-2.0-or-later

About

Declarative admin list tables for BerlinDB-backed data — columns, views, filters, row and bulk actions, without writing a WP_List_Table.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages