envato free trialCreative Assets & Unlimited Downloads on Envato Elements Get 7 Days Free

The WP_List_Table Function: What it Is and How to Use It Within a Typical WordPress Installation

on WordPress

For the past several major releases of WordPress, the columns of data within the WordPress Dashboard have been sortable either in ascending or descending order. This applies to virtually every column located within the Dashboard, including those that advertise categories, post titles, publishing dates, or page creation dates. It can also alphabetize things like categories, tags, and even pages or posts. This is a long-requested function, and it’s great that it finally has been included with the shipping version of the Dashboard. While a great additional feature, however, it does come with quite a few complexities for developers. That’s because the function used to create sortable columns within the WordPress Dashboard is considered “private” and it cannot be extended to other plugins or areas within the WordPress installation, either within or outside the Dashboard interface itself.

To solve this problem, WordPress has actually created dual functions that allow columns to be created and made sortable. Its own private function is known as the _get_list_table() function, and this is what is used throughout the category, post, page, and tag pages in the Dashboard. This borderline proprietary function for sortable columns is then paired with the _wp_list_table() function; that function is the one that developers are encouraged to utilize when listing plugin data for use by administrators. It’s somewhat complicated, but most developers will get the hang of this disparity relatively quickly when creating their plugins or themes, and creating columns of data that should be sorted by the end user. Those developers looking to list data in a table, and make the columns within that table sortable, need to understand what this function is and how to best employ it for maximum utility and usability.

First Things First: What is the WP_List_Table Function Within WordPress?

The WP_List_Table function is a relatively recent addition to the WordPress Dashboard and its list of developer functions, and it directly replaces an earlier function for creating sortable columns throughout both the Dashboard and WordPress themes. One of the main differences between the WP_List_Table function and its predecessor is that the new function can now be fully integrated with an AJAX sorting implementation, like those supported by the popular jQuery JavaScript library for advanced interfaces. This makes it possible to perform advanced sorting functions and other administrative tasks without a forced page refresh that can cause some serious usability headaches for developers, authors, and website users alike.

WordPress actually makes a distinction between the WP_List_Table and a whole series of other WordPress functions, calling the WP_List_Table function a “framework” rather than a pure, straightforward function. And that’s because, in addition to incorporating AJAX manipulation, this new way to create sortable columns is composed as an extensive array that can be intricately customized and extended by the developer him or herself.

It’s also worth noting that the developers behind the WordPress software itself have thoroughly committed to supporting the WP_List_Table function/framework well into the future. Unlike the short-lived sortable columns feature that preceded it, the WP_List_Table is assured to be “hooked” into future WordPress releases. That means any columns created with today’s implementation of the WP_List_Table framework will be forward-compatible, even if WordPress changes some basic things about how this new framework functions and what it is actually capable of within the Dashboard. It’s the kind of confidence that should inspire use of the new WP_List_Table framework among a larger group of developers, and that’s the primary good of the WordPress development team. Sortable columns and AJAX implementations are highly usable, more so than any other technology currently used in legacy areas of the Dashboard. It contributes to an overall easier way to use advanced functions, making the software more appealing to entry-level users. This, in turn, increases the appeal of WordPress and helps it continue as the most popular content management platform currently on the market.

Finally, developers should understand that the WP_List_Table is considered an extension of the get_list_table() function, rather than a replacement of it for developer users. Though developers cannot modify that function, it is still an integral part to producing listed data and allowing it to be sorted. Therefore, WP_List_Table should be considered an extension of WordPress’ main functionality, not a substitute for the built-in column hooks.

This is best seen in the way a new WP_List_Table class is initiated within themes or plugin files that produce their own WordPress Dashboard control panel pages. The opening lines of any new sortable column actually begin with language that clearly identifies them as an extension of an existing class, rather than as an entirely new class or set of data itself. Here’s how that looks in a typical plugin or theme functions file:

class Custom_List_Table extends WP_List_Table {}
$custom_sortable_table = new Custom_List_Table();

After this simple extension has been properly declared within the plugin or theme functions file, the new column can be created by using a pretty straightforward array. That array will name the column of data, and it will set important parameters that pertain to its functions. This is where things like sortability, AJAX implementations, and other advanced features come into play. These things are produced in a standard PHP array, which is what causes WP_List_Table to be identified more as a framework than as a pure WordPress administrative function.

Methods, Extended Properties, and Properties: How to Turn an Extension into a Sortable Table

The WP_List_Table framework is labeled as such because of how customizable it is after it has been initialized. These customizations are actually made by using a series of arguments within an array, and WordPress groups these things into methods, extended properties, and properties, that customize how data is displayed and which functions can be performed upon that data by administrators and other Dashboard users. For those who are new to the WP_List_Table function and framework, as almost every WordPress user is, here is a brief overview of how each method, extended method, and property, works to create an advanced column of data.

Properties: The Basics of Sorting and Presentation

The “properties” group of PHP array arguments is generally the most basic, with each line of code determining something essential about the data displayed. Indeed, this group of array arguments actually contains the $items tag that displays the sortable data itself. Here are the properties available for use with WP_List_Table:

  • $items – Typically used in the “prepare()” part of the array, this variable displays the data that will be listed and sorted in the sortable column or table at large.
  • $_args – This variable is used for storing information about the table itself, and is typically not manipulated by the developer.
  • $_pagination_args – This variable, typically left unmodified, handles pagination of data and the caching of paginated data in the Dashboard.
  • $screen – Used to store information about the current screen.
  • $_actions – Another cache-based variable, this one stores information about cached actions in the Dashboard.
  • $_pagination – This cache-based variable stores information about paginated output and caches it. This is typically left unmodified by the developer.

Extended Properties: A More Advanced Way to Utilize WP_List_Table

There is just a single extended property available for use within the WP_List_Table framework, and it controls the header of each column within the table. That property is $_column_headers. It contains three arrays: One array to name the column, another to define hidden column properties, and a third array to either allow or prohibit the sorting of the column’s data.

Methods: Extensive, Detailed Modifications of Sortable Column Data using WP_List_Table

Finally, developers will have access to a series of modifications that the WordPress documentation refers to as “methods.” These things are far more minor modifications, and they control much more intricate pieces of functionality within the sortable columns and the table itself. To that end, there are well over twenty individual modifications that are defined as “methods” within the WordPress documentation. While it would be impossible and impractical to define each one of these extensive modifications here, they can be easily defined by utilizing the WordPress Codex documentation when creating a sortable table or column.

The most important thing to know about “methods” as they pertain to sortable columns is that they’re almost all entirely optional. They’re used only where their specific brand of modification or manipulation is required. If they’re not needed, then they are simply left out of the sortable column’s array entirely, and the data is presented without being modified by any “method” at all. This means that most “methods” manipulations within the array are used only by the most advanced WordPress developers and only within the most elaborate WordPress plugins or theme control panel pages.

Revisiting the Use of Column Variables Within the WP_List_Table Array

One of the most complex things to do when putting WP_List_Table to good use within a new WordPress plugin or theme control panel page is to create the actual columns that will contain sortable data for the end user. This is because columns require a three-pronged approach to creation; each of these approaches must be contained within the array that actually creates the column and, without all three of them, the column will either fail to display or it will display with a number of errors and irregularities.

To create a column properly when using WP_List_Table in a new plugin or control panel page, be sure to follow the format below. This will ensure that any column created works as intended and displays data in a proper way:

$this->_column_headers = array(
$this->get_columns(), // This initializes the columns themselves and acts as the parent array.
array('Plugin Data Column 1', true),// This is the first column of data.
array('Plugin Data Column 2', true),// This is the second column of data.
array('Plugin Data Column 3', true),// This is the third column of data.
array(), // This is an intentionally hidden column.
$this->get_sortable_columns(), // This array indicates that each of the three visible columns above should be sortable by the end user. );

The above array is the first way to begin creating a truly rich and advanced table full of sortable data, as it initializes the actual headings or “slugs” of the columns that will contain data pulled from the database. Below this opening array for columns, the WP_List_Table will be utilized to actually pull data in from the WordPress database using the “$items” variable discussed above. Each data “item” will be placed into an appropriate corresponding column. Those columns can then be sorted with a mouse click and, unless indicated otherwise through one of the “methods” tags, they will be sorted using a basic AJAX (jQuery) function rather than employing a page refresh.

Take Time to Learn WP_List Table — You’ll Need It

Developers who are considering bringing the WP_List_Table function to their WordPress plugin or control panel page should set aside a significant amount of time to learn about and internalize all of the functions and features contained with in this function/framework provided for their use. While it’s certainly not difficult to deploy a table of data with sortable columns once each property, extended property, and method has been learned, it will require a significant investment of time to actually learn what each of these things does and where it’s applicable.

Developers should also set aside a great deal of time for testing their sortable columns that employ the WP_List_Table framework, especially because one wrong property or so-called “method” can cause entire columns to display errors or disappear from the WordPress Dashboard entirely. A thorough mastery of the WP_List_Table framework is a long-term investment in WordPress and its most advanced functions, and this will be rewarding for virtually every developer who endeavors to take it on.