WordPress - motywy, wtyczki, informacje, programowanie

Pomoc

Klasa WP_Screen – zakładki Pomoc i Opcje ekranu

Data publikacji 11 czerwca 2012
Komentarze Możliwość komentowania Klasa WP_Screen – zakładki Pomoc i Opcje ekranu została wyłączona
Kiedy tworzymy własną wtyczkę, zwykle będzie ona miała jakieś strony ustawień. Jeśli są skomplikowane, a sama strona jest wypełniona opcjami, lepiej nie zaśmiecać jej przesadną ilością opisów. Powinniśmy wykorzystać nowe możliwości, które pojawiły się w WordPressie 3.3. Nowa klasa WP_Screen umożliwia tworzenie zgrabnych ekranów pomocy oraz opcji ekranowych.

Od chwili pojawienia się WP_Screen, funkcja add_contextual_help() i filtry the contextual_help oraz  contextual_help_list filters są deprecated. Pozwalały one dodawać zakładki pomocy, ale bez wewnętrzynego podziału na zakładki. Nowa klasa dodaje nowe możliwości, ale tez wprowadza trochę porządku.

Zakładki Pomoc i Opcje ekranu pojawiają się w górnej części strony ustawień.

Opcje Ekranu, Pomoc

Po rozwinięciu pomocy widzimy 2 obszary. Obszar zakładek z tematami po lewej stronie, oraz sidebar po prawej.

Panel Pomocy

* Nie, oczywiście admin na WPinternals nie nazywa się „admin”, tak jak to widać na tym obrazku. 🙂 O tym, że nie powinno się stosować nazwy domyślnej pisaliśmy w naszych poradach na temat bezpieczeństwa

Tworzenie zakładki Pomoc

Dodawanie strony ustawień do panelu admina przebiega tak jak zawsze. Możemy użyć dowolnej funkcji add_*_page, ja użyję add_menu_page. Tym razem musimy zachować wynik funkcji.

add_action( 'admin_menu', 'evp_add_menu' );
function evp_add_menu() {
	$test_page = add_menu_page(
		'Example Plugin WP_Screen',
		'WP_Screen Example',
		'activate_plugins',
		'wp_screen_example',
		'evp_render_test_page'
	);

$test_page zawiera „hook_suffix” – wygenerowany identyfikator strony. Po sklejeniu z prefixem „load-” otrzymamy pełną nazwę haka i będziemy mogli przechwycić ładowanie strony w funkcji evp_add_help().

	if ( $test_page )
		add_action( "load-{$test_page}", 'evp_add_help' );
}

Najpierw musimy uzyskać obiekt WP_Screen dla tej strony.

function evp_add_help() {
	/* @var $screen WP_Screen */
	$screen = get_current_screen();

Teraz dodamy zakładki z tematami pomocy. Treść do zakładek można podać bezpośrednio w parametrze content

	$screen->add_help_tab( array(
		'id'      => 'evp-help-1', // id musi być unikalny dla strony
		'title'   => 'Tytuł 1',
		'content' => '<p>Treść 1.</p>'
	) );

Można też w parametrze callback podać funkcję, która zostanie wywołana kiedy będzie Tworzona zakładka, a jej rola jest dostarczenie treści. Funkcja przyjmuje 2 argumenty: obiekt WP_Screen oraz zdefiniowaną wcześniej zakładkę do której funkcja ma wygenerować treść (w poniższym przykładzie anonimowa funkcja ignoruje parametry).

	$screen->add_help_tab( array(
		'id'      => 'evp-help-2', // id musi być unikalny dla strony
		'title'   => 'Tytuł 2',
		'callback' => create_function( '', 'echo "<p>Treść 2.</p>";' )
	) );

Dodamy jeszcze sidebar. Kiedy użytkownik przełącza się pomiędzy zakładkami pomocy, sidebar zawsze pozostaje niezmienny. Jest bardzo dobrym miejscem do umieszczenia np. linków do strony autora, do rozszerzonej pomocy na jego stronie, ewentualnie do jakichś innych zasobów, które mogą się przydać użytkownikowi.

	$screen->set_help_sidebar( '<p>To jest treść dla sidebara.</p>' );

Pomoc jest gotowa. Do dyspozycji mamy jeszcze funkcje remove_help_tabs() i remove_help_tab($id), które usuwają wszystkie zakładki pomocy lub wskazane przez nas.

Opcje ekranu

WP_Screen umożliwia dodanie 2 opcji: per_page i layout_columns. Inne nie zostaną wyświetlone na ekranie.

	$screen->add_option( 'per_page', array(
		'label'   => 'Entries per page',
		'default' => 20,
		'option'  => 'edit_per_page'
	) );

	$screen->add_option( 'layout_columns', array(
		'default' => 3,
		'max'     => 5
	) );
}

Dodanie opcji ekranu nie spowoduje widocznych zmian na stronie. Odczytywanie, zapisywanie i wykorzystanie ich w pluginie musimy zaimplementować sami lub skorzystać z gotowych klas.

Z opcji ekranowych korzysta WP_List_Table czyli standardowa tabela w panelu admina, używana w wielu miejscach, np. do wyświetlania listy wpisów. Rozszerzając klasę WP_List_Table uzyskujemy możliwość ukrywania/pokazywania wybranych kolumn oraz decydowania o maksymalnej ilości wpisów na stronie. Z kolei z opcji layout_columns korzysta np. WordPressowy Kokpit.


Na koniec cała wtyczka

<?php
/*
Plugin Name: WP_Screen Example
Version: 1.0
*/

/*
* Podłączamy się pod ładowanie menu i dodajemy standardowo
* własną pozycję menu
*/
add_action( 'admin_menu', 'evp_add_menu' );
function evp_add_menu() {
	/* Tym razem zachowujemy wynik na później */
	$test_page = add_menu_page(
		'Example Plugin WP_Screen',
		'WP_Screen Example',
		'activate_plugins',
		'wp_screen_example',
		'evp_render_test_page'
	);
	/*
	 * Znamy już 'hook_suffix', jest to wygenerowany identyfikator strony
	 * (w tym przypadku jest to napis "toplevel_page_wp_screen_example"
	 * co nie ma absolutnie żadnego znaczenia).
	 * Możemy więc przechwycić ładowanie strony.
	 */
	if ( $test_page )
		add_action( "load-{$test_page}", 'evp_add_help' );
}

function evp_render_test_page() {
	// Treść strony z opcjami
}

function evp_add_help() {

	/* Poniższy komentarz czyni IDE szczęśliwszym i podpowiada,
	 * że $screen jest klasy WP_Screen */
	/* @var $screen WP_Screen */
	$screen = get_current_screen();

	/* Dodajemy treść bezpośrednio w 'content' */
	$screen->add_help_tab( array(
		'id'      => 'evp-help-1', // id musi być unikalny dla strony
		'title'   => 'Tytuł 1',
		'content' => '<p>Treść 1.</p>',
	) );

	/* lub w 'callback' wskazujemy funkcję, która wygeneruje treść */
	$screen->add_help_tab( array(
		'id'      => 'evp-help-2', // id musi być unikalny dla strony
		'title'   => 'Tytuł 2',
		'callback' => create_function( '', 'echo "<p>Treść 2.</p>";' ),
	) );

	$screen->set_help_sidebar( '<p>To jest treść dla sidebara.</p>' );

	$screen->add_option( 'per_page', array(
		'label'   => 'Entries per page',
		'default' => 20,
		'option'  => 'edit_per_page'
	) );

	$screen->add_option( 'layout_columns', array(
		'default' => 3,
		'max'     => 5
	) );
}

Powiadomimy Cię o nowych artykułach