Количество элементов на странице для таблиц WP_List_Table

WP_List_Table позволяет без шума и пыли создавать таблицы в админке WordPress. Сделано удобно — мне нравится очень, но требует определенных знаний. О WP_List_Table я еще напишу. А в этой заметке я покажу как добавить к такой созданной таблице настраиваемую пагинацию. Все пользователи WP видели такую настройку, в верхней вкладке «Настройки экрана» (рядом со вкладкой «Помощь») — поле где можно указать сколько записей выводить на странице.

В эту вкладку настроек экрана, можно добавлять и другие опции. О плюсах и удобности таких настроек экрана думаю говорить не надо: все на одной странице, интуитивно понятно и не мешает, потому что скрыто под вкладкой. Но в этой заметке речь пойдет именно про пагинацию — это там выделено в отдельную опцию и добавляется очень просто.

Шаг 1: Добавление опции во вкладку «Настройки экрана» во время нужного события

Первое что нужно сделать, это «сказать» WordPress что мы хотим добавить опцию во вкладку «Настройки экрана».

Подключать эту опцию нужно в определенный момент: после того как экран (страница админ-панели) определился, но до того как начали собираться данные вкладки для вывода. Первое такое событие — current_screen (это после admin_init). Наиболее подходящее событие — load-(page_hook) — момент когда страница определена, но еще ничего не выведено на экран.

Добавляется опция с помощью функции add_screen_option():

// регистрируем страницу
$hook = add_menu_page( $pg_title, $menu_title, $cap, $slug, $function );

// подключаемся к событию, когда страница загружена, но еще ничего не выводится
add_action( "load-$hook", 'per_page_screen_option' );

// подключаем опцию
function per_page_screen_option() {
	$option = 'per_page'; // это специальное название, WordPress о нем знает и обрабатывает его автоматически
	$args = array(
		'label'   => 'Показывать на странице',
		'default' => 10,
		'option'  => 'my_page_per_page', // название опции, будет записано в метаполе юзера
	);

	add_screen_option( $option, $args );
}

Шаг 2: сохранение добавленной опции

Поле ввода настройки готово, но толку от него 0 потому что настройку нельзя сохранить. Надо-то, чтобы при нажатии на кнопку «Применить» что-то куда-то сохранилась. Для этого используем специальный фильтр set_screen_option_(option).

// Cохранение опции экрана per_page. Нужно вызывать до события 'admin_menu'
add_filter( 'set_screen_option_'.'my_page_per_page', function( $status, $option, $value ){
	return (int) $value;
}, 10, 3 );

В параметре $status обычно передается false и поэтому WordPress пропускает сохранение этой настройки. Если указать что-то кроме false, то это «что-то» будет записано в опцию.

Важным моментом является то, что вызывать 'set_screen_option_'.'my_page_per_page' нужно до события 'admin_menu'. Т.е. НЕЛЬЗЯ вызывать его там же где регистрируем меню, или на самой странице админки, или во время загрузки этой страницы — вызывать нужно раньше! Зачем так сделали я не понял - это неудобно, но это так.

// Cохранение опции экрана per_page. Нужно вызывать до события 'admin_menu'
add_filter( 'set-screen-option', function( $status, $option, $value ){
	return ( $option == 'my_page_per_page' ) ? (int) $value : $status;
}, 10, 3 );

Шаг 3: получение настройки опции

К этому моменту настройка добавлена и даже сохраняется. Теперь, во время создания таблиц с помощью WP_List_Table в методе prepare_items() вам нужна будет эта настройка, когда нужно указать сколько записей показывать на странице.

Настройка сохраняется в метаполе пользователя, с указанным названием, у нас оно: 'my_page_per_page'. Поэтому, чтобы получить настройку нужно получить метаполе, если его нет, то получить значение по умолчанию, делаем:

// обычно этот код используется внутри WP_List_Table::prepare_items()

// получим параметры настройки
$per_page_option = get_current_screen()->get_option('per_page');

// пробуем получить сохраненную настройку
$per_page = get_user_meta( get_current_user_id(), $per_page_option['option'], true );

// если сохраненной настройки нет, берем по умолчанию
if( ! $per_page )
	$per_page = $per_page_option['default'];

// $per_page будет равно 10 или сколько было установлено...

Подключение без использования события load-(page_hook)

Если событие load-(page_hook) не используется (хотя это и не совсем правильно), то переделывать структуру кода может быть лишней проблемой. В таких случаях можно подключить опцию экрана через событие current_screen, где-то на раннем этапе, например в admin_init или прям в коде плагина:

Следующий код регистрирует опцию per_page и добавляет возможность сохранения. Предполагается что ID экрана для которого регистрируется опция равен screen_id.

// подключаем опцию, где угодно. Нужно вызывать до события 'admin_menu'
add_action( 'current_screen', 'per_page_screen_option' );
function per_page_screen_option() {
	// убедимся что мы на нужном экране
	if( get_current_screen()->id != 'screen_id' )
		return;

	$option = 'per_page'; // это специальное название, WordPress о нем знает и обрабатывает его автоматически
	$args = array(
		'label'   => 'Показывать на странице',
		'default' => 10,
		'option'  => 'my_page_per_page', // название опции, будет записано в метаполе юзера
	);

	add_screen_option( $option, $args );
}

// Cохранение опции экрана per_page. Нужно вызывать до события 'admin_menu'
add_filter( 'set-screen-option', function( $status, $option, $value ){
	return ( $option == 'my_page_per_page' ) ? (int) $value : $status;
}, 10, 3 );

Получение опции работает также: на странице где она нужна, используем:

// получим параметры настройки
$per_page_option = get_current_screen()->get_option('per_page');

// пробуем получить сохраненную настройку
$per_page = get_user_meta( get_current_user_id(), $per_page_option['option'], true );

// если сохраненной настройки нет, берем по умолчанию
if( ! $per_page )
	$per_page = $per_page_option['default'];

// $per_page будет равно 10 или сколько было установлено...