Кількість елементів на сторінці для 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);
}

всі функції типу: add_menu_page(), add_options_page() реєструють сторінку та повертають її унікальний ключ, який використовується у хуку. Ми підключаємось саме до цього хуку.

На цьому етапі ми маємо з’явитися налаштування у вкладці «Налаштування екрана».

Крок 2: збереження доданої опції

Поле введення налаштування готове, але користі від нього 0 тому що налаштування не можна зберегти. Потрібно, щоб при натисканні на кнопку «Застосувати» щось кудись збереглося. Для цього використовуємо спеціальний фільтр 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 пропускає збереження цієї настройки. Якщо вказати щось крім false, це «щось» буде записано в опцію.

Важливим моментом є те, що викликати 'set_screen_option_'.'my_page_per_page'потрібно до події 'admin_menu'. Тобто. НЕ МОЖНА викликати його там де реєструємо меню, або на самій сторінці адмінки, або під час завантаження цієї сторінки – викликати потрібно раніше! Навіщо так зробили, я не зрозумів – це незручно, але це так.

// Збереження опції екрана 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);
}

// Збереження опції екрана 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 або скільки було встановлено...

Якщо комусь цей пост стане в нагоді, напишіть дурницю в коментарі, хоч знати буду що не тільки для себе писав