Количество элементов на странице для таблиц WP_List_Table
Перед тем как начать, хочу отметить, что эта заметка будет полезна только тем, кто уже знаком с классом WP_List_Table.
WP_List_Table позволяет создавать таблицы в админке WordPress. Это удобно и мне это очень нравится, но требует определённых знаний. Позже я напишу подробнее о WP_List_Table. В этой заметке я покажу, как добавить настраиваемую пагинацию (разделение на страницы) к таблице, созданной с помощью WP_List_Table. Все пользователи WordPress видели такую настройку во вкладке "Параметры экрана" в верхней части страницы (рядом с вкладкой "Справка") — поле, где можно указать, сколько записей отображать на странице.
Вы можете добавить другие параметры в эту вкладку настроек экрана. Не думаю, что стоит объяснять, как удобно иметь всё на одной странице: это интуитивно и не мешает, так как скрыто под вкладкой. Однако в этой заметке я конкретно расскажу о пагинации — она выделена в отдельный параметр и добавляется очень легко.
Шаг 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 );
}Все функции, такие как add_menu_page(), add_options_page(), регистрируют страницу и возвращают её уникальный ключ, который используется в хуке. Мы подключаемся к этому хуку.
На этом этапе настройка должна появиться во вкладке "Параметры экрана".
Шаг 2: Сохраняем добавленный параметр
Поле ввода для настройки готово, но оно бесполезно, так как настройка не может быть сохранена. Нужно сохранять настройку при нажатии кнопки "Применить". Для этого используем специальный фильтр set_screen_option_(option).
// Сохраняем опцию 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 пропускает сохранение этой настройки. Если указано что-то другое, то это будет записано в опцию.
Важно помнить, что вызов 'set_screen_option_'.'my_page_per_page' должен происходить до события 'admin_menu'. То есть нельзя вызывать его там, где вы регистрируете меню или на самой админ-странице — его нужно вызвать раньше! Не знаю, почему это так — это неудобно, но такова реальность.
Перед версией 5.4.2 нужно было делать по другому принципу, но в новой версии добавили новый хук set_screen_option_(option) по соображениям безопасности, который сломал работу старого хука.
Для этого используем специальный фильтр set-screen-option.
// Сохраняем опцию per_page. Нужно вызывать до события 'admin_menu'
add_filter( 'set-screen-option', function( $status, $option, $value ){
return ( $option == 'my_page_per_page' ) ? (int) $value : $status;
}, 10, 3 );Здесь мы проверяем имя опции и, если это наша опция, возвращаем значение вместо false, предварительно конвертируя его в число: (int) $value.
Шаг 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 );
}
// Сохраняем опцию 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 или тому, что было установлено...Таким образом, вы научились добавлять, сохранять и получать опцию количества элементов на странице для таблиц WP_List_Table. Теперь вы можете настраивать админку WordPress под свои потребности!