- \n
- When to Use the WordPress Admin Table<\/a><\/li>\n<\/ul>\n<\/li>\n
- Anatomy of the WP_List_Table Class<\/a><\/li>\n
- The Custom List Table Plugin for User Meta Operations<\/a><\/li>\n
- Inheriting the WP_List_Table Class<\/a><\/li>\n
- Rendering a List Table<\/a>\n
- \n
- Adding the Plugin Menu Page<\/a><\/li>\n
- Verifying the Barebone List Table Setup<\/a><\/li>\n<\/ul>\n<\/li>\n
- Overriding Methods of the WP_List_Table Class<\/a>\n
- \n
- WP_List_Table::get_columns()<\/a><\/li>\n
- WP_List_Table::prepare_items()<\/a><\/li>\n
- WP_List_Table::column_default()<\/a><\/li>\n
- WP_List_Table::column_cb()<\/a><\/li>\n
- WP_List_Table::get_sortable_columns()<\/a><\/li>\n
- WP_List_Table::set_pagination_args()<\/a><\/li>\n
- WP_List_Table::search_box()<\/a><\/li>\n
- WP_List_Table::get_bulk_actions()<\/a><\/li>\n
- Adding Row Action Links to the List Table<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
The WordPress list tables are used almost everywhere in the dashboard. You’ll find them used to display posts, pages, users, comments, etc. as well as in many popular plugins. Over the years, they’ve become the de facto standard for displaying tabular information in WordPress.<\/p>\n
For this article, I’ve built a custom Admin Table with the help of a plugin that uses object-oriented constructs. The plugin can be downloaded from here<\/a> to follow along with the article. But before we get into that, let’s understand what Admin Tables really do.<\/p>\n
I’ll also be using the terms
Admin Tables<\/code> andList Tables<\/code> interchangeably for the rest of the article.<\/p>\nNote: This article is for intermediate-advanced WordPress developers. You will require a working knowledge of WordPress, PHP and the WordPress Plugin API<\/a> before going ahead. If you’re unsure or would like a refresher I recommend you read through the following:<\/em><\/p>\n
- \n
- WordPress Development for Beginners: Getting Started<\/a><\/li>\n
- WordPress Development for Beginners: Widgets and Menus<\/a><\/li>\n
- WordPress Development for Beginners: Building Plugins<\/a><\/li>\n
- Advanced WordPress Development: Introduction to Object-Oriented Programming<\/a><\/li>\n<\/ul>\n
WordPress Admin Tables \u2013 The Background<\/h2>\n
You’ve already interacted with an Admin Table while accessing pages like Posts and Users in the Dashboard. A WordPress Administration Table is implemented using the
WP_List_Table<\/a><\/code> class located at\/wp-admin\/includes\/class-wp-list-table.php<\/code>. It provides the necessary framework to display information in a tabular fashion as well as manipulate data intuitively. Here’s an overview of what a typical WordPress Admin Table entails:<\/p>\n\n![\"wordpress](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/09\/wordpress-admin-table.png\")
A WordPress Admin Table<\/figcaption><\/figure>\n<\/div>\n You’ll notice the familiar bulk actions, row actions with hover links, pagination and screen options, all of which have been an integral part of WordPress ever since.<\/p>\n
While
Screen Options<\/code> are not directly part ofWP_List_Table<\/code>, they work very closely with it. They allow control over the visibility of columns as well as the pagination by limiting the information displayed on the page.<\/p>\nWhen to Use the WordPress Admin Table<\/h3>\n
Just because the WordPress API provides a way to build native List Tables doesn’t mean one must use it. In my opinion, a big factor in deciding to use the WordPress provided Admin Tables should be User Experience<\/a>. With the
WP_List_Table<\/code> class, WordPress takes care of styling the table UI for you. The familiarity of working with Admin Tables (all over WordPress) and the native look-and-feel are elements that will certainly help users interact with your table data in a seamless manner.<\/p>\nAnatomy of the WP_List_Table Class<\/h2>\n
Since its inception in version 3.1.0 of WordPress, the WP_List_Table class has increasingly grown in popularity among developers. The WordPress Codex class reference for the WP_List_Table<\/a> provides comprehensive information about its methods, properties and usage.<\/p>\n
The infographic below outlines the building blocks of an Admin Table from the class reference.<\/p>\n
\n![\"anatomy-wp-list-table-class\"](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/10\/anatomy-wp-list-table-class-600.png\")
Building blocks of the WP_List_Table<\/figcaption><\/figure>\n<\/div>\n A more complex Admin Table would also feature additional drop-down filters and action links above the table such as those used to show “Published Posts” and “Drafts”.<\/p>\n
Now that we have a fair understanding of an Admin Table and the
WP_List_Table<\/code> class, let’s put this knowledge to use with the help of a custom plugin.<\/p>\nThe Custom List Table Plugin for User Meta Operations<\/h2>\n
Before I get into the implementation details of List Tables, I want to briefly touch upon the custom plugin that I’ve prepared for this article. You can download it from here<\/a> to follow along. I recommend that you have it opened in a suitable editor and install it on a local development WordPress setup only<\/strong>.<\/p>\n
The plugin is based on my own plugin template<\/a> which is a fork of the original WordPress Plugin Boilerplate<\/a> project. It’s similar to the original project in many aspects but also has support for namespaces and autoloading. This way, I don’t need to have unique prefixes for every class or function, and don’t end up with a lot of
include<\/code> andrequire<\/code> statements. However, the minimum required PHP version for my plugin is 5.6.0.<\/p>\nWe’ll mostly be working with files in the following directories of the plugin:<\/p>\n
- \n
inc\/core\/*<\/code> – for core functionality of the plugin<\/li>\ninc\/admin\/*<\/code> – for displaying the List Table in the admin area<\/li>\ninc\/libraries\/*<\/code> – libraries for the plugin<\/li>\n<\/ul>\nFeel free to structure the plugin based on your own coding and layout preferences. I prefer to use Boilerplate Starting Points<\/a> as they’re among the many best practices listed in the WordPress Plugin Handbook.<\/p>\n
Purpose<\/h3>\n
The custom plugin displays all registered WordPress users in its own Admin Table with control over screen options, pagination and row action links to perform operations on the user’s metadata. Each row action leads to a plugin page to carry out these operations.<\/p>\n
This use-case certainly isn’t the ideal one as I could simply have added the functionality to the default WordPress Users page using
user_row_actions<\/a><\/code>; however, it serves the purpose of implementing a List Table from scratch. So let’s get started.<\/p>\nInheriting the WP_List_Table Class<\/h2>\n
To create an Admin Table you will need to define a child class in your plugin that extends the core
WP_List_Table<\/code> class provided by WordPress. So, among the first things that you should do, is copy the fileclass-wp-list-table.php<\/code> under\/wp-admin\/includes\/<\/code> to your plugin. I strongly recommend this because the core class has been marked as private<\/a>, and so, any potential changes in the class or its methods by WordPress will not break your plugin.<\/p>\nIn my plugin, I’ve copied the file to
inc\/libraries<\/code> and added aNamespace<\/code> directive. If you’re not using Namespaces, you will need to prefix everything<\/a>.<\/p>\n\n![\"importing](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/10\/importing-wp-list-table-class.png\")
Copying the wp-list-table class file<\/figcaption><\/figure>\n<\/div>\n I then defined my own PHP child class
User_List_Table<\/code> ininc\/admin\/class-user-list-table.php<\/code> that extended the baseWP_List_Table<\/code> class under the folderinc\/libraries<\/code> of my plugin.<\/p>\n
- WordPress Development for Beginners: Widgets and Menus<\/a><\/li>\n
- WP_List_Table::prepare_items()<\/a><\/li>\n
- Verifying the Barebone List Table Setup<\/a><\/li>\n<\/ul>\n<\/li>\n
- Anatomy of the WP_List_Table Class<\/a><\/li>\n
![\"user-menu](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/10\/user-menu-list-table-page.png\")
![\"barebone-list-table-implementation\"](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/10\/barebone-list-table-display.png\")
![\"wp-list-table-get-columns](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/10\/wp-list-table-get-columns.png\")
![\"wp-list-table-display-column-data\"](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/10\/wp-list-table-display-column-data.png\")
![\"wp-list-table-sortable-columns\"](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/10\/wp-list-table-sortable-columns.png\")