WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP List Table

This class's access is marked as private. That means it is not intended for use by plugin and theme developers as it is subject to change without warning in any future WordPress release. If you would still like to make use of the class, you should make a copy to use and distribute with your own project, or else use it at your own risk.

Role of WP_List_Table

This class is used to generate the List Tables that populate WordPress' various admin screens. It has an advantage over previous implementations in that it can be dynamically altered with AJAX and may be hooked in future WordPress releases.

Developer Usage & Private Status

On March 27, 2012, Andrew Nacin warned developers that this class was created for private core use only as it may be subject to change in any future WordPress release.

Nevertheless, the WP_List_Table class has become widely used by plugins and WordPress developers as it provides a reliable, consistent, and semantic way to create custom list tables in WordPress. To date, no major changes have occurred in this class or are scheduled to occur, so testing your plugin with beta/RC phases of WordPress development should be more than enough to avoid any major issues.

If you are at all uncomfortable with this risk, a common (and safe) workaround is to make a copy the WP_List_Table class ( /wp-admin/includes/class-wp-list-table.php ) to use and distribute in your plugins, instead of using the original core class. This way, if the core class should ever change, your plugins will continue to work as-is.

Developers should use this class at their own risk.

Usage

This class is meant to be used as a kind of framework, since any data queries need to loaded, sorted, and filtered manually. Nevertheless, it is potentially a very powerful tool for developers as it creates WordPress-standard list tables, which makes it very easy to implement advanced features like pagination, actions, bulk actions, and filtering.

To use the WP_List_Table, you first create a new class that extends the original. Your new class must be instantiated, and the prepare_items() and display() methods called explicitly on the instance. See the method descriptions below for more details.

In the WordPress Core

The WordPress core loads and returns its classes dynamically by using the _get_list_table() function, which automatically loads the appropriate extended class and instantiates it. This is a private function, however, and should not be used by developers.

Developer Usage

Since this class is marked as private, developers should use this only at their own risk as this class is subject to change in future WordPress releases. Any developers using this class are strongly encouraged to test their plugins with all WordPress beta/RC releases to maintain compatibility.

Since developers cannot use the _get_list_table() function directly, the class needs to be extended and instantiated manually, like so...

class Example_List_Table extends WP_List_Table {}
$example_lt = new Example_List_Table();

The above example won't be able to output anything meaningful, however, as several methods MUST be specified (as well as your data) in order for WP_List_Table to render a useful table.

Methods and Properties

Properties

The following properties are built into the base WP_List_Table class.

$items
This is used to store the raw data you want to display. Generally you will set this property directly in the prepare_items() method.
$_args
Stores various information about the current table (as an array). This generally isn't manipulated directly.
$_pagination_args
Stores information needed for handling table pagination (as an array). This generally isn't manipulated directly.
$screen
This can be used to store the current screen, when it's necessary to keep it consistent with the entire instance.
$_actions
Stores cached bulk actions. This generally isn't manipulated directly.
$_pagination
Stores cached pagination output. This generally isn't manipulated directly.

Extended Properties

These properties are not built-in, but are expected by several class methods. You must define them manually in your extended class.

$_column_headers
In core, this property is assigned automatically. Developers must manually define it in their prepare_items() or __construct() methods.
This property requires a 3-value array :
  • The first value is an array containing column slugs and titles (see the get_columns() method).
  • The second value is an array containing the values of fields to be hidden.
  • The third value is an array of columns that should allow sorting (see the get_sortable_columns() method).

Methods

__construct( $args=array() )
Constructor. This sets default arguments and filters. Developers should override this, calling the parent constructor to provide values for singular and plural labels, as well as whether the class supports AJAX.
ajax_user_can()
Can be overridden to provide some permissions functionality to your table.
prepare_items()
Developers should use this class to query and filter data, handle sorting, and pagination, and any other data-manipulation required prior to rendering. This method should be called explicitly after instantiating your class, and before rendering.
set_pagination_args( $args )
This method should be called internally (usually from prepare_items()) to set basic pagination arguments. Available arguments include:
  • total_items - the total number of items to be displayed. Usually as simple as count($data)
  • per_page - the number of items to show per page
  • total_pages - the total number of pages. Can be left blank or calculated manually, like so: ceil($total_items/$per_page)
get_pagination_arg( $key )
Gets a single pagination argument by its key.
has_items()
Returns a boolean indicating whether the items property is empty.
no_items()
Returns the message to be displayed when there are no items.
search_box( $text, $input_id )
This renders a search box. To use this, you will still need to manually wrap your list table (including search box) in a form.
get_views()
Returns an associative array listing all the views that can be used with this table.
views()
Renders out the <ul> element that contains the view names.
get_bulk_actions()
Override this method to return an associative array ( action_slug => action_title ) containing all the bulk actions available for the table.
bulk_actions()
When called, this renders out the bulk-actions drop-down. To use this, you will still need to manually wrap your list table (including search box) in a form.
current_action()
This returns the current action selected in the bulk actions dropdown.
row_actions( $actions, $always_visible = false )
Call this method (usually from one of your column methods) to insert a row actions div. The $actions parameter should be an associative array, where the key is the name of the action and the value is a link.
months_dropdown( $post_type )
Call this to render a date dropdown, for filtering items by month.
view_switcher( $current_mode )
Call this to render post-type view switcher buttons (List View and Excerpt View)
comments_bubble( $post_id, $pending_comments )
Call this to render comment-count bubble.
get_pagenum()
Returns the currently selected page number.
get_items_per_page( $option, $default = 20 )
Fetches the number of items to be displayed on the page, as set by users.
pagination( $which )
Creates the pagination HTML and assigns it to the _pagination property. Generally, you don't need to call this directly as it's handled for you on display().
get_columns()
This method should be overridden to return an associative array of columns. The associative array should follow the format 'slug' => array( 'Title', true ). Typically, you will use this in the prepare_items() method to build part of the _column_headers property.
get_columns()
This method should be overridden to return an associative array of columns. The associative array should follow the format 'slug'=>'Title' and is frequently used to provide part of the _column_headers property.
get_sortable_columns()
This method should be overridden to return an associative array of columns that you want to make sortable. The associative array should follow the format 'column_slug'=>array('sortby',true), where the second property states whether the field is presorted. This is frequently used to provide part of the _column_headers property.
get_column_info()
This is used by WordPress to build and fetch the _column_headers property. Generally, this should not be used by developers. Instead, assign the _column_headers property directly from your prepare_items() method.
get_column_count()
This simply returns the number of visible columns.
print_column_headers( $with_id = true )
This method renders out the column headers. Generally, you don't need to call this directly as it's handled for you in the display() method.
display()
Call this method to render the completed list table to the page.
get_table_classes()
Returns a list of css classes to be attached to the table element. Override to customize table classes.
display_tablenav( $which )
This generates the table navigation above or below the table. Generally, you don't need to call this explicitly as it is handled in the display() method.
extra_tablenav( $which )
This can be overridden to display additional controls between the rendered bulk actions and pagination controls.
display_rows_or_placeholder()
This generates the tbody part of the table. Generally, you don't need to call this explicitly as it is handled in the display() method.
display_rows()
This loops through the items property and renders them to the page as table rows. Generally, you don't need to call this explicitly as it is handled automatically on display().
single_row( $item )
This echos a single item (from the items property) to the page. Generally, you don't need to call this explicitly as it is handled automatically on display().
single_row_columns( $item )
This renders out all the columns for a single item row. It is important to understand that this method assumes the existence of some custom column methods (eg column_mycolumn()) and/or a column_default() method. Neither of these are provided by the base class and should be defined in your extended class. Generally, you don't need to call this explicitly as it is handled automatically on display().
ajax_response()
Handles incoming Ajax requests.
_js_vars()
Outputs key Javascript variables that were dynamically created by the class.

Extended Methods

These methods are not included in the base class but can, and should, be defined in your extended class!

column_default( $item, $column_name )
This is method that is used to render a column when no other specific method exists for that column. When WP_List_Tables attempts to render your columns (within single_row_columns()), it first checks for a column-specific method. If none exists, it defaults to this method instead. This method accepts two arguments, a single $item array and the $column_name (as a slug).
NOTICE: As of WordPress 3.5.1, in core $item is passed an Object, not an array.
column_$custom( $item )
Custom columns must be provided by the developer and can be used to handle each type column individually. For example: if a method named column_movie_title() were provided, it would be used to render any column that had the slug "movie_title". This function accepts one argument - a single $item array.
NOTICE: As of WordPress 3.5.1, in core $item is passed an Object, not an array.

Examples

For a detailed, functional example, download the Custom List Table Example plugin.

Using within Meta Boxes

Attention when using the WP_List_Table class within a Meta Box:

If you don't set $this->_column_headers in your own class within prepare_items() (like shown in the code block below), then the complete <thead> and <tfoot> will disappear!

$this->_column_headers = array( 
	 $this->get_columns(),		// columns
	 array(),			// hidden
	 $this->get_sortable_columns(),	// sortable
);

Why This Happens

If you don't set $this->_column_headers; manually in the extending class, then the sortable columns are set up by the parent class and the $this->get_columns(); function.

Unfortunately, when this happens your column headers array is empty - even if you set it up with get_columns(); from your child class.

The Fix

Use the $GLOBALS['wp_filter']["manage_{$GLOBALS['screen']->id}_screen_columns"]; filter to get them back!

Sidenote: The get_column_headers() function that applies this filter is located in /core_root/wp-admin/includes/template.php

'There is one major drawback:' If you do this, no other meta box may contain an extension for the WP_List_Table class, as this would break the columns of the additional meta boxes since only one filter exists to setup the screen columns per screen.

Version

WP_List_Table was implemented in WordPress 3.1.

Source File

WP_List_Table() is located in /wp-admin/includes/class-wp-list-table.php.

Related

See also index of Class Reference and index of Function Reference.