3 * Base class for displaying a list of items in an ajaxified HTML table.
9 * @subpackage List_Table
14 * The current list of items
23 * Various information about the current table
32 * Various information needed for displaying the pagination
38 private $_pagination_args = array();
59 * Cached pagination output
70 * The child class should call this constructor from its own constructor to override
76 * @param array|string $args {
77 * Array or string of arguments.
79 * @type string $plural Plural value used for labels and the objects being listed.
80 * This affects things such as CSS class-names and nonces used
81 * in the list table, e.g. 'posts'. Default empty.
82 * @type string $singular Singular label for an object being listed, e.g. 'post'.
84 * @type bool $ajax Whether the list table supports AJAX. This includes loading
85 * and sorting data, for example. If true, the class will call
86 * the {@see _js_vars()} method in the footer to provide variables
87 * to any scripts handling AJAX events. Default false.
88 * @type string $screen String containing the hook name used to determine the current
89 * screen. If left null, the current screen will be automatically set.
93 public function __construct( $args = array() ) {
94 $args = wp_parse_args( $args, array(
101 $this->screen = convert_to_screen( $args['screen'] );
103 add_filter( "manage_{$this->screen->id}_columns", array( $this, 'get_columns' ), 0 );
105 if ( !$args['plural'] )
106 $args['plural'] = $this->screen->base;
108 $args['plural'] = sanitize_key( $args['plural'] );
109 $args['singular'] = sanitize_key( $args['singular'] );
111 $this->_args = $args;
113 if ( $args['ajax'] ) {
114 // wp_enqueue_script( 'list-table' );
115 add_action( 'admin_footer', array( $this, '_js_vars' ) );
120 * Make private properties readable for backwards compatibility.
125 * @param string $name Property to get.
126 * @return mixed Property.
128 public function __get( $name ) {
133 * Make private properties settable for backwards compatibility.
138 * @param string $name Property to set.
139 * @param mixed $value Property value.
140 * @return mixed Newly-set property.
142 public function __set( $name, $value ) {
143 return $this->$name = $value;
147 * Make private properties checkable for backwards compatibility.
152 * @param string $name Property to check if set.
153 * @return bool Whether the property is set.
155 public function __isset( $name ) {
156 return isset( $this->$name );
160 * Make private properties un-settable for backwards compatibility.
165 * @param string $name Property to unset.
167 public function __unset( $name ) {
168 unset( $this->$name );
172 * Make private/protected methods readable for backwards compatibility.
177 * @param callable $name Method to call.
178 * @param array $arguments Arguments to pass when calling.
179 * @return mixed|bool Return value of the callback, false otherwise.
181 public function __call( $name, $arguments ) {
182 return call_user_func_array( array( $this, $name ), $arguments );
186 * Checks the current user's permissions
193 public function ajax_user_can() {
194 die( 'function WP_List_Table::ajax_user_can() must be over-ridden in a sub-class.' );
198 * Prepares the list of items for displaying.
199 * @uses WP_List_Table::set_pagination_args()
205 public function prepare_items() {
206 die( 'function WP_List_Table::prepare_items() must be over-ridden in a sub-class.' );
210 * An internal method that sets all the necessary pagination arguments
212 * @param array $args An associative array with information about the pagination
215 protected function set_pagination_args( $args ) {
216 $args = wp_parse_args( $args, array(
222 if ( !$args['total_pages'] && $args['per_page'] > 0 )
223 $args['total_pages'] = ceil( $args['total_items'] / $args['per_page'] );
225 // Redirect if page number is invalid and headers are not already sent.
226 if ( ! headers_sent() && ( ! defined( 'DOING_AJAX' ) || ! DOING_AJAX ) && $args['total_pages'] > 0 && $this->get_pagenum() > $args['total_pages'] ) {
227 wp_redirect( add_query_arg( 'paged', $args['total_pages'] ) );
231 $this->_pagination_args = $args;
235 * Access the pagination args
243 public function get_pagination_arg( $key ) {
244 if ( 'page' == $key )
245 return $this->get_pagenum();
247 if ( isset( $this->_pagination_args[$key] ) )
248 return $this->_pagination_args[$key];
252 * Whether the table has items to display or not
259 public function has_items() {
260 return !empty( $this->items );
264 * Message to be displayed when there are no items
269 public function no_items() {
270 _e( 'No items found.' );
274 * Display the search box.
279 * @param string $text The search button text
280 * @param string $input_id The search input id
282 public function search_box( $text, $input_id ) {
283 if ( empty( $_REQUEST['s'] ) && !$this->has_items() )
286 $input_id = $input_id . '-search-input';
288 if ( ! empty( $_REQUEST['orderby'] ) )
289 echo '<input type="hidden" name="orderby" value="' . esc_attr( $_REQUEST['orderby'] ) . '" />';
290 if ( ! empty( $_REQUEST['order'] ) )
291 echo '<input type="hidden" name="order" value="' . esc_attr( $_REQUEST['order'] ) . '" />';
292 if ( ! empty( $_REQUEST['post_mime_type'] ) )
293 echo '<input type="hidden" name="post_mime_type" value="' . esc_attr( $_REQUEST['post_mime_type'] ) . '" />';
294 if ( ! empty( $_REQUEST['detached'] ) )
295 echo '<input type="hidden" name="detached" value="' . esc_attr( $_REQUEST['detached'] ) . '" />';
297 <p class="search-box">
298 <label class="screen-reader-text" for="<?php echo $input_id ?>"><?php echo $text; ?>:</label>
299 <input type="search" id="<?php echo $input_id ?>" name="s" value="<?php _admin_search_query(); ?>" />
300 <?php submit_button( $text, 'button', false, false, array('id' => 'search-submit') ); ?>
306 * Get an associative array ( id => link ) with the list
307 * of views available on this table.
314 protected function get_views() {
319 * Display the list of views available on this table.
324 public function views() {
325 $views = $this->get_views();
327 * Filter the list of available list table views.
329 * The dynamic portion of the hook name, $this->screen->id, refers
330 * to the ID of the current screen, usually a string.
334 * @param array $views An array of available list table views.
336 $views = apply_filters( "views_{$this->screen->id}", $views );
338 if ( empty( $views ) )
341 echo "<ul class='subsubsub'>\n";
342 foreach ( $views as $class => $view ) {
343 $views[ $class ] = "\t<li class='$class'>$view";
345 echo implode( " |</li>\n", $views ) . "</li>\n";
350 * Get an associative array ( option_name => option_title ) with the list
351 * of bulk actions available on this table.
358 protected function get_bulk_actions() {
363 * Display the bulk actions dropdown.
368 * @param string $which The location of the bulk actions: 'top' or 'bottom'.
369 * This is designated as optional for backwards-compatibility.
371 protected function bulk_actions( $which = '' ) {
372 if ( is_null( $this->_actions ) ) {
373 $no_new_actions = $this->_actions = $this->get_bulk_actions();
375 * Filter the list table Bulk Actions drop-down.
377 * The dynamic portion of the hook name, $this->screen->id, refers
378 * to the ID of the current screen, usually a string.
380 * This filter can currently only be used to remove bulk actions.
384 * @param array $actions An array of the available bulk actions.
386 $this->_actions = apply_filters( "bulk_actions-{$this->screen->id}", $this->_actions );
387 $this->_actions = array_intersect_assoc( $this->_actions, $no_new_actions );
393 if ( empty( $this->_actions ) )
396 echo "<label for='bulk-action-selector-" . esc_attr( $which ) . "' class='screen-reader-text'>" . __( 'Select bulk action' ) . "</label>";
397 echo "<select name='action$two' id='bulk-action-selector-" . esc_attr( $which ) . "'>\n";
398 echo "<option value='-1' selected='selected'>" . __( 'Bulk Actions' ) . "</option>\n";
400 foreach ( $this->_actions as $name => $title ) {
401 $class = 'edit' == $name ? ' class="hide-if-no-js"' : '';
403 echo "\t<option value='$name'$class>$title</option>\n";
408 submit_button( __( 'Apply' ), 'action', false, false, array( 'id' => "doaction$two" ) );
413 * Get the current action selected from the bulk actions dropdown.
418 * @return string|bool The action name or False if no action was selected
420 public function current_action() {
421 if ( isset( $_REQUEST['filter_action'] ) && ! empty( $_REQUEST['filter_action'] ) )
424 if ( isset( $_REQUEST['action'] ) && -1 != $_REQUEST['action'] )
425 return $_REQUEST['action'];
427 if ( isset( $_REQUEST['action2'] ) && -1 != $_REQUEST['action2'] )
428 return $_REQUEST['action2'];
434 * Generate row actions div
439 * @param array $actions The list of actions
440 * @param bool $always_visible Whether the actions should be always visible
443 protected function row_actions( $actions, $always_visible = false ) {
444 $action_count = count( $actions );
447 if ( !$action_count )
450 $out = '<div class="' . ( $always_visible ? 'row-actions visible' : 'row-actions' ) . '">';
451 foreach ( $actions as $action => $link ) {
453 ( $i == $action_count ) ? $sep = '' : $sep = ' | ';
454 $out .= "<span class='$action'>$link$sep</span>";
462 * Display a monthly dropdown for filtering items
467 protected function months_dropdown( $post_type ) {
468 global $wpdb, $wp_locale;
470 $months = $wpdb->get_results( $wpdb->prepare( "
471 SELECT DISTINCT YEAR( post_date ) AS year, MONTH( post_date ) AS month
474 ORDER BY post_date DESC
478 * Filter the 'Months' drop-down results.
482 * @param object $months The months drop-down query results.
483 * @param string $post_type The post type.
485 $months = apply_filters( 'months_dropdown_results', $months, $post_type );
487 $month_count = count( $months );
489 if ( !$month_count || ( 1 == $month_count && 0 == $months[0]->month ) )
492 $m = isset( $_GET['m'] ) ? (int) $_GET['m'] : 0;
494 <label for="filter-by-date" class="screen-reader-text"><?php _e( 'Filter by date' ); ?></label>
495 <select name="m" id="filter-by-date">
496 <option<?php selected( $m, 0 ); ?> value="0"><?php _e( 'All dates' ); ?></option>
498 foreach ( $months as $arc_row ) {
499 if ( 0 == $arc_row->year )
502 $month = zeroise( $arc_row->month, 2 );
503 $year = $arc_row->year;
505 printf( "<option %s value='%s'>%s</option>\n",
506 selected( $m, $year . $month, false ),
507 esc_attr( $arc_row->year . $month ),
508 /* translators: 1: month name, 2: 4-digit year */
509 sprintf( __( '%1$s %2$d' ), $wp_locale->get_month( $month ), $year )
518 * Display a view switcher
523 protected function view_switcher( $current_mode ) {
525 'list' => __( 'List View' ),
526 'excerpt' => __( 'Excerpt View' )
530 <input type="hidden" name="mode" value="<?php echo esc_attr( $current_mode ); ?>" />
531 <div class="view-switch">
533 foreach ( $modes as $mode => $title ) {
534 $classes = array( 'view-' . $mode );
535 if ( $current_mode == $mode )
536 $classes[] = 'current';
538 "<a href='%s' class='%s' id='view-switch-$mode'><span class='screen-reader-text'>%s</span></a>\n",
539 esc_url( add_query_arg( 'mode', $mode ) ),
540 implode( ' ', $classes ),
550 * Display a comment count bubble
555 * @param int $post_id The post ID.
556 * @param int $pending_comments Number of pending comments.
558 protected function comments_bubble( $post_id, $pending_comments ) {
559 $pending_phrase = sprintf( __( '%s pending' ), number_format( $pending_comments ) );
561 if ( $pending_comments )
564 echo "<a href='" . esc_url( add_query_arg( 'p', $post_id, admin_url( 'edit-comments.php' ) ) ) . "' title='" . esc_attr( $pending_phrase ) . "' class='post-com-count'><span class='comment-count'>" . number_format_i18n( get_comments_number() ) . "</span></a>";
566 if ( $pending_comments )
571 * Get the current page number
578 public function get_pagenum() {
579 $pagenum = isset( $_REQUEST['paged'] ) ? absint( $_REQUEST['paged'] ) : 0;
581 if( isset( $this->_pagination_args['total_pages'] ) && $pagenum > $this->_pagination_args['total_pages'] )
582 $pagenum = $this->_pagination_args['total_pages'];
584 return max( 1, $pagenum );
588 * Get number of items to display on a single page
595 protected function get_items_per_page( $option, $default = 20 ) {
596 $per_page = (int) get_user_option( $option );
597 if ( empty( $per_page ) || $per_page < 1 )
598 $per_page = $default;
601 * Filter the number of items to be displayed on each page of the list table.
603 * The dynamic hook name, $option, refers to the per page option depending
604 * on the type of list table in use. Possible values may include:
605 * 'edit_comments_per_page', 'sites_network_per_page', 'site_themes_network_per_page',
606 * 'themes_netework_per_page', 'users_network_per_page', 'edit_{$post_type}', etc.
610 * @param int $per_page Number of items to be displayed. Default 20.
612 return (int) apply_filters( $option, $per_page );
616 * Display the pagination.
621 protected function pagination( $which ) {
622 if ( empty( $this->_pagination_args ) ) {
626 $total_items = $this->_pagination_args['total_items'];
627 $total_pages = $this->_pagination_args['total_pages'];
628 $infinite_scroll = false;
629 if ( isset( $this->_pagination_args['infinite_scroll'] ) ) {
630 $infinite_scroll = $this->_pagination_args['infinite_scroll'];
633 $output = '<span class="displaying-num">' . sprintf( _n( '1 item', '%s items', $total_items ), number_format_i18n( $total_items ) ) . '</span>';
635 $current = $this->get_pagenum();
637 $current_url = set_url_scheme( 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] );
639 $current_url = remove_query_arg( array( 'hotkeys_highlight_last', 'hotkeys_highlight_first' ), $current_url );
641 $page_links = array();
643 $disable_first = $disable_last = '';
644 if ( $current == 1 ) {
645 $disable_first = ' disabled';
647 if ( $current == $total_pages ) {
648 $disable_last = ' disabled';
650 $page_links[] = sprintf( "<a class='%s' title='%s' href='%s'>%s</a>",
651 'first-page' . $disable_first,
652 esc_attr__( 'Go to the first page' ),
653 esc_url( remove_query_arg( 'paged', $current_url ) ),
657 $page_links[] = sprintf( "<a class='%s' title='%s' href='%s'>%s</a>",
658 'prev-page' . $disable_first,
659 esc_attr__( 'Go to the previous page' ),
660 esc_url( add_query_arg( 'paged', max( 1, $current-1 ), $current_url ) ),
664 if ( 'bottom' == $which ) {
665 $html_current_page = $current;
667 $html_current_page = sprintf( "%s<input class='current-page' id='current-page-selector' title='%s' type='text' name='paged' value='%s' size='%d' />",
668 '<label for="current-page-selector" class="screen-reader-text">' . __( 'Select Page' ) . '</label>',
669 esc_attr__( 'Current page' ),
671 strlen( $total_pages )
674 $html_total_pages = sprintf( "<span class='total-pages'>%s</span>", number_format_i18n( $total_pages ) );
675 $page_links[] = '<span class="paging-input">' . sprintf( _x( '%1$s of %2$s', 'paging' ), $html_current_page, $html_total_pages ) . '</span>';
677 $page_links[] = sprintf( "<a class='%s' title='%s' href='%s'>%s</a>",
678 'next-page' . $disable_last,
679 esc_attr__( 'Go to the next page' ),
680 esc_url( add_query_arg( 'paged', min( $total_pages, $current+1 ), $current_url ) ),
684 $page_links[] = sprintf( "<a class='%s' title='%s' href='%s'>%s</a>",
685 'last-page' . $disable_last,
686 esc_attr__( 'Go to the last page' ),
687 esc_url( add_query_arg( 'paged', $total_pages, $current_url ) ),
691 $pagination_links_class = 'pagination-links';
692 if ( ! empty( $infinite_scroll ) ) {
693 $pagination_links_class = ' hide-if-js';
695 $output .= "\n<span class='$pagination_links_class'>" . join( "\n", $page_links ) . '</span>';
697 if ( $total_pages ) {
698 $page_class = $total_pages < 2 ? ' one-page' : '';
700 $page_class = ' no-pages';
702 $this->_pagination = "<div class='tablenav-pages{$page_class}'>$output</div>";
704 echo $this->_pagination;
708 * Get a list of columns. The format is:
709 * 'internal-name' => 'Title'
717 public function get_columns() {
718 die( 'function WP_List_Table::get_columns() must be over-ridden in a sub-class.' );
722 * Get a list of sortable columns. The format is:
723 * 'internal-name' => 'orderby'
725 * 'internal-name' => array( 'orderby', true )
727 * The second format will make the initial sorting order be descending
734 protected function get_sortable_columns() {
739 * Get a list of all, hidden and sortable columns, with filter applied
746 protected function get_column_info() {
747 if ( isset( $this->_column_headers ) )
748 return $this->_column_headers;
750 $columns = get_column_headers( $this->screen );
751 $hidden = get_hidden_columns( $this->screen );
753 $sortable_columns = $this->get_sortable_columns();
755 * Filter the list table sortable columns for a specific screen.
757 * The dynamic portion of the hook name, $this->screen->id, refers
758 * to the ID of the current screen, usually a string.
762 * @param array $sortable_columns An array of sortable columns.
764 $_sortable = apply_filters( "manage_{$this->screen->id}_sortable_columns", $sortable_columns );
767 foreach ( $_sortable as $id => $data ) {
768 if ( empty( $data ) )
771 $data = (array) $data;
772 if ( !isset( $data[1] ) )
775 $sortable[$id] = $data;
778 $this->_column_headers = array( $columns, $hidden, $sortable );
780 return $this->_column_headers;
784 * Return number of visible columns
791 public function get_column_count() {
792 list ( $columns, $hidden ) = $this->get_column_info();
793 $hidden = array_intersect( array_keys( $columns ), array_filter( $hidden ) );
794 return count( $columns ) - count( $hidden );
798 * Print column headers, accounting for hidden and sortable columns.
803 * @param bool $with_id Whether to set the id attribute or not
805 public function print_column_headers( $with_id = true ) {
806 list( $columns, $hidden, $sortable ) = $this->get_column_info();
808 $current_url = set_url_scheme( 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] );
809 $current_url = remove_query_arg( 'paged', $current_url );
811 if ( isset( $_GET['orderby'] ) )
812 $current_orderby = $_GET['orderby'];
814 $current_orderby = '';
816 if ( isset( $_GET['order'] ) && 'desc' == $_GET['order'] )
817 $current_order = 'desc';
819 $current_order = 'asc';
821 if ( ! empty( $columns['cb'] ) ) {
822 static $cb_counter = 1;
823 $columns['cb'] = '<label class="screen-reader-text" for="cb-select-all-' . $cb_counter . '">' . __( 'Select All' ) . '</label>'
824 . '<input id="cb-select-all-' . $cb_counter . '" type="checkbox" />';
828 foreach ( $columns as $column_key => $column_display_name ) {
829 $class = array( 'manage-column', "column-$column_key" );
832 if ( in_array( $column_key, $hidden ) )
833 $style = 'display:none;';
835 $style = ' style="' . $style . '"';
837 if ( 'cb' == $column_key )
838 $class[] = 'check-column';
839 elseif ( in_array( $column_key, array( 'posts', 'comments', 'links' ) ) )
842 if ( isset( $sortable[$column_key] ) ) {
843 list( $orderby, $desc_first ) = $sortable[$column_key];
845 if ( $current_orderby == $orderby ) {
846 $order = 'asc' == $current_order ? 'desc' : 'asc';
848 $class[] = $current_order;
850 $order = $desc_first ? 'desc' : 'asc';
851 $class[] = 'sortable';
852 $class[] = $desc_first ? 'asc' : 'desc';
855 $column_display_name = '<a href="' . esc_url( add_query_arg( compact( 'orderby', 'order' ), $current_url ) ) . '"><span>' . $column_display_name . '</span><span class="sorting-indicator"></span></a>';
858 $id = $with_id ? "id='$column_key'" : '';
860 if ( !empty( $class ) )
861 $class = "class='" . join( ' ', $class ) . "'";
863 echo "<th scope='col' $id $class $style>$column_display_name</th>";
873 public function display() {
874 $singular = $this->_args['singular'];
876 $this->display_tablenav( 'top' );
879 <table class="wp-list-table <?php echo implode( ' ', $this->get_table_classes() ); ?>">
882 <?php $this->print_column_headers(); ?>
888 <?php $this->print_column_headers( false ); ?>
892 <tbody id="the-list"<?php
894 echo " data-wp-lists='list:$singular'";
896 <?php $this->display_rows_or_placeholder(); ?>
900 $this->display_tablenav( 'bottom' );
904 * Get a list of CSS classes for the <table> tag
911 protected function get_table_classes() {
912 return array( 'widefat', 'fixed', $this->_args['plural'] );
916 * Generate the table navigation above or below the table
921 protected function display_tablenav( $which ) {
922 if ( 'top' == $which )
923 wp_nonce_field( 'bulk-' . $this->_args['plural'] );
925 <div class="tablenav <?php echo esc_attr( $which ); ?>">
927 <div class="alignleft actions bulkactions">
928 <?php $this->bulk_actions( $which ); ?>
931 $this->extra_tablenav( $which );
932 $this->pagination( $which );
941 * Extra controls to be displayed between bulk actions and pagination
946 protected function extra_tablenav( $which ) {}
949 * Generate the <tbody> part of the table
954 public function display_rows_or_placeholder() {
955 if ( $this->has_items() ) {
956 $this->display_rows();
958 echo '<tr class="no-items"><td class="colspanchange" colspan="' . $this->get_column_count() . '">';
965 * Generate the table rows
970 public function display_rows() {
971 foreach ( $this->items as $item )
972 $this->single_row( $item );
976 * Generates content for a single row of the table
981 * @param object $item The current item
983 public function single_row( $item ) {
984 static $row_class = '';
985 $row_class = ( $row_class == '' ? ' class="alternate"' : '' );
987 echo '<tr' . $row_class . '>';
988 $this->single_row_columns( $item );
993 * Generates the columns for a single row of the table
998 * @param object $item The current item
1000 protected function single_row_columns( $item ) {
1001 list( $columns, $hidden ) = $this->get_column_info();
1003 foreach ( $columns as $column_name => $column_display_name ) {
1004 $class = "class='$column_name column-$column_name'";
1007 if ( in_array( $column_name, $hidden ) )
1008 $style = ' style="display:none;"';
1010 $attributes = "$class$style";
1012 if ( 'cb' == $column_name ) {
1013 echo '<th scope="row" class="check-column">';
1014 echo $this->column_cb( $item );
1017 elseif ( method_exists( $this, 'column_' . $column_name ) ) {
1018 echo "<td $attributes>";
1019 echo call_user_func( array( $this, 'column_' . $column_name ), $item );
1023 echo "<td $attributes>";
1024 echo $this->column_default( $item, $column_name );
1031 * Handle an incoming ajax request (called from admin-ajax.php)
1036 public function ajax_response() {
1037 $this->prepare_items();
1040 if ( ! empty( $_REQUEST['no_placeholder'] ) ) {
1041 $this->display_rows();
1043 $this->display_rows_or_placeholder();
1046 $rows = ob_get_clean();
1048 $response = array( 'rows' => $rows );
1050 if ( isset( $this->_pagination_args['total_items'] ) ) {
1051 $response['total_items_i18n'] = sprintf(
1052 _n( '1 item', '%s items', $this->_pagination_args['total_items'] ),
1053 number_format_i18n( $this->_pagination_args['total_items'] )
1056 if ( isset( $this->_pagination_args['total_pages'] ) ) {
1057 $response['total_pages'] = $this->_pagination_args['total_pages'];
1058 $response['total_pages_i18n'] = number_format_i18n( $this->_pagination_args['total_pages'] );
1061 die( json_encode( $response ) );
1065 * Send required variables to JavaScript land
1069 public function _js_vars() {
1071 'class' => get_class( $this ),
1073 'id' => $this->screen->id,
1074 'base' => $this->screen->base,
1078 printf( "<script type='text/javascript'>list_args = %s;</script>\n", json_encode( $args ) );