WordPress.org

Class Reference/WP List Table

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.

This class may be used by developers through extending the class and overriding its methods.

Usage

This class is meant to be used as a kind of framework, and 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 and 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.

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 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() method.
$_args: Stores various information about the current table (as an array). This generally isn't manipulated directly.
$_pagination_args: Stores information needed for 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 '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

column_default($item, $column_name): This method is not included in the base class but can be defined in your extended class. 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).
column_$custom($item, $column_name): Custom columns must be provided by the developer and can be used to handle each type column individually. If a method named column_movie_title() were provided, it would be used to render any column that had the slug "movie_title". Like column_default(), this accepts two arguments - a single $item array and the $column_name (as a slug).

Examples

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

Attention when using the WP_List_Table class in a Meta Box:

If you don't set $this->_column_headers in your own class, during defining prepare_items(), (like shown in the code block) then the complete <thead> and <tfoot> disappears.

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

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

But: Then your column headers array is empty - even when you set it up with get_columns(); from you child/extending class.

Work-around: Using the $GLOBALS['wp_filter']["manage_{$GLOBALS['screen']->id}_screen_columns"]; filter to get them back in.

Oh, yeah and the get_column_headers() function that applies that filter is hidden in /core_root/wp-admin/includes/template.php like some other related stuff. For whatever reason.

Draw-back: No 2nd meta box may contain an extension for the WP_List_Table class then, as this would break the columns of one of the meta boxes as there's only one filter to setup the screen columns per screen.

Attention when you're defining your array with get_sortable_columns(): Always add your array values like this: array( 'Column_Name', true ).

Reason: I simply don't get behind it. It's WordPress...

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.