Die WordPress-Einstellungs-API, Teil 6: Menüseiten

() translation by (you can also view the original English article)

In Teil 3 dieser Serie haben wir die verschiedenen Menüfunktionen untersucht, die die WordPress-API bietet. Wenn Sie mitgemacht haben, wissen Sie, dass wir bereits eine Einstellungsseite für unser Thema mithilfe der Funktion add_theme_page eingerichtet haben. Das Einführen von Menüs und Untermenüs ist zwar nicht explizit Teil der Einstellungs-API, spielt jedoch eine Rolle beim Erstellen benutzerdefinierter Funktionen, Plugins und / oder Themen.

In diesem Artikel werden wir ein neues Menü in das WordPress-Dashboard einführen, das unsere Themenoptionen an anderer Stelle als nur unter den Optionen "Darstellung" verfügbar macht.

Bevor wir beginnen: In diesem Artikel wird davon ausgegangen, dass Sie mit der Einstellungs-API und den Designoptionen vertraut sind. Wenn Sie ein Anfänger oder sogar ein fortgeschrittener WordPress-Entwickler sind, empfehle ich dringend, den Rest der Serie nachzuholen, bevor Sie in diesen Beitrag eintauchen.

Ein Blick auf die API

Da wir uns bereits alle Menüfunktionen angesehen haben, müssen wir nicht alle Funktionen von WordPress erneut aufbereiten. Stattdessen schauen wir uns die an, die wir verwenden werden, und arbeiten dann ein praktisches Beispiel aus, wie wir sie in unserer eigenen Arbeit verwenden können.

Bevor wir uns die einzelnen Funktionen ansehen, wollen wir detailliert beschreiben, was wir in der nächsten Phase dieser Serie erreichen wollen:

Stellen Sie ein Menü der obersten Ebene für unsere Themenoptionen vor
Fügen Sie ein Untermenüelement hinzu, das mit der Registerkarte "Anzeigeoptionen" verknüpft ist
Fügen Sie ein Untermenüelement hinzu, das mit der Registerkarte "Soziale Optionen" verknüpft ist

Relativ einfach, oder? Dazu nutzen wir die folgenden zwei Funktionen:

add_menu_page, die zum Einführen von Menüelementen der obersten Ebene verwendet wird
add_submenu_page, mit der Untermenüelemente in Menüs der obersten Ebene eingeführt werden.

Wir werden uns die Parameter und die Verwendung der einzelnen Funktionen ansehen, während wir sie in unser Thema implementieren.

Beachten Sie, dass der Rest dieses Artikels auf dieser Version der WordPress-Einstellungssandbox aufbaut. Wenn Sie dem Repository folgen, stellen Sie sicher, dass Sie es auschecken.

Das Top-Level-Menü

Als erstes möchten wir ein Menü der obersten Ebene einführen. Dieses Menü wird direkt unter dem Menü "Einstellungen" im WordPress-Dashboard angezeigt und dient zwei Zwecken. Das Menü sollte:

Stellen Sie die Optionen des Themas dem WordPress-Dashboard zur Verfügung
Zeigen Sie eine Standardoptionsseite für die Themenoptionen an

Die Funktion akzeptiert die folgenden sieben Argumente, die ersten fünf sind erforderlich, die letzten beiden nicht:

page_title ist der Text, der in der Titelleiste des Browsers gerendert wird
menu_title ist der Text, der für den Menüpunkt angezeigt wird
capability bezieht sich auf die Rolle, die der Benutzer haben muss, um auf dieses Menü zugreifen zu können
menu_slug ist ein eindeutiger Wert, der dieses Menü identifiziert. So registrieren sich auch Untermenüs in diesem Menü.
function_name, der aufgerufen wird, wenn auf das Menü geklickt wird, um die Optionsseite anzuzeigen.
icon_url ist der Pfad zu dem Symbol, das Sie neben Ihrem Menüpunkt anzeigen möchten.
position ist, wo das Menü in Bezug auf die anderen Menüs im WordPress-Dashboard hinzugefügt werden sollte.

In unserer Arbeit konzentrieren wir uns nur auf die ersten fünf Parameter. Ich diskutiere die Menüpositionierung am Ende dieses Artikels.

Um zu beginnen, müssen wir die Funktion add_menu_page aufrufen. Gemäß dem WordPress-Codex können Verwaltungsmenüs über den Hook admin_menu hinzugefügt werden. Zu Beginn dieser Serie haben wir eine Funktion geschrieben, die unsere Themenoptionen zum Menü "Darstellung" hinzufügt. Insbesondere haben wir sandbox_example_theme_menu geschrieben:

function sandbox_example_theme_menu() {

	add_theme_page(
		'Sandbox Theme', 			// The title to be displayed in the browser window for this page.
		'Sandbox Theme',			// The text to be displayed for this menu item
		'administrator',			// Which type of users can see this menu item
		'sandbox_theme_options',	// The unique ID - that is, the slug - for this menu item
		'sandbox_theme_display'		// The name of the function to call when rendering this menu's page
	);

} // end sandbox_example_theme_menu
add_action( 'admin_menu', 'sandbox_example_theme_menu' );

Beachten Sie im obigen Code, dass diese Funktion auch beim Hook admin_menu registriert wurde. Sie sollten sich immer bemühen, Ihre Funktionen logisch konsistent zu halten. Da wir bereits eine Funktion haben, die ein Menü registriert, das mit dem entsprechenden Hook registriert ist, und ähnliche Funktionen einführen, werden wir dieser Funktion unsere neuen Menüfunktionen hinzufügen.

Fügen Sie den folgenden Aufruf zu add_menu_page direkt unter dem obigen Aufruf hinzu:

add_menu_page(
	'Sandbox Theme',		// The value used to populate the browser's title bar when the menu page is active
	'Sandbox Theme',		// The text of the menu in the administrator's sidebar
	'administrator',		// What roles are able to access the menu
	'sandbox_theme_menu',	// The ID used to bind submenu items to this menu 
	'sandbox_theme_display'	// The callback function used to render this menu
);

Wie Sie sehen können, registrieren wir ein Menü, in dem "Sandbox-Thema" sowohl in der Titelleiste des Browsers als auch im Menüelement angezeigt wird. Wir stellen das Menü nur Administratoren zur Verfügung und haben dem Menü die eindeutige ID "sandbox_theme_parent_menu" zugewiesen. Wir werden diesen Parameter im nächsten Abschnitt wiederverwenden.

Es gibt eine wichtige Sache, die wir klären müssen: Beachten Sie, dass wir 'sandbox_theme_display' als die Funktion übergeben haben, die aufgerufen werden soll, wenn auf diesen Menüpunkt geklickt wird. Denken Sie daran, dass wir diese Funktion in Teil 3 eingeführt haben (und in Teil 5 verfeinert haben). Insbesondere ist es für das Rendern unserer Seite mit Themenoptionen mit Registerkarten verantwortlich.

Indem wir diesen vorhandenen Funktionsnamen an die Funktion add_menu_page übergeben, nutzen wir den bereits geschriebenen Code und rendern eine Standardoptionsseite für den Menüpunkt.

An diesem Punkt können wir mit dem Hinzufügen von Untermenüs beginnen. Bevor Sie fortfahren, stellen Sie jedoch sicher, dass Ihre Funktion genau so aussieht:

function sandbox_example_theme_menu() {

	add_theme_page(
		'Sandbox Theme',
		'Sandbox Theme',
		'administrator',
		'sandbox_theme_options',
		'sandbox_theme_display'
	);
	
	add_menu_page(
		'Sandbox Theme',
		'Sandbox Theme',
		'administrator',
		'sandbox_theme_menu',
		'sandbox_theme_display'
	);

} // end sandbox_example_theme_menu

Fügen Sie die Untermenüs hinzu

Untermenüs sind Menüs sehr ähnlich, außer dass sie zu einem vorhandenen Menü "gehören". Die API zum Registrieren von Untermenüs ist ebenfalls relativ ähnlich. Die Funktion akzeptiert sechs Argumente, wobei die ersten fünf erforderlich sind und das letzte optional ist:

parent_slug bezieht sich auf die eindeutige ID des übergeordneten Menüelements. In unserem Fall "sandbox_theme_menu".
page_title ist der Text, der in der Symbolleiste des Browsers gerendert werden soll, wenn dieses Untermenüelement aktiv ist
menu_title ist der Text für diesen tatsächlichen Untermenüpunkt im Dashboard
capability ist die Rolle, die ein Benutzer haben muss, um auf diesen Menüpunkt zuzugreifen
menu_slug ist die eindeutige ID für diesen bestimmten Menüpunkt
function_name, der aufgerufen wird, wenn auf das Menü geklickt wird, um die Optionsseite anzuzeigen

Die Funktion ist unkompliziert. Wir müssen zwei Menüpunkte einführen - einen für "Anzeigeoptionen" und einen für "Soziale Optionen".

Anzeigeoptionen

Lassen Sie uns zunächst ein Untermenüelement für Anzeigeoptionen einführen. Fügen Sie den folgenden Codeblock direkt unter dem oben definierten Aufruf add_menu_page hinzu:

add_submenu_page(
	'sandbox_theme_menu',				// The ID of the top-level menu page to which this submenu item belongs
	'Display Options',					// The value used to populate the browser's title bar when the menu page is active
	'Display Options',					// The label of this submenu item displayed in the menu
	'administrator',					// What roles are able to access this submenu item
	'sandbox_theme_display_options',	// The ID used to represent this submenu item
	'sandbox_theme_display'				// The callback function used to render the options for this submenu item
);

Jeder der oben genannten Parameter sollte klar sein, mit Ausnahme des Funktionsnamens, den wir als letztes Argument übergeben haben. Beachten Sie, dass es sich um denselben Funktionsnamen handelt, den wir im Aufruf von add_menu_page angegeben haben. Aber das macht doch Sinn, oder? Schließlich ist die "Anzeigeoptionen" die Standardregisterkarte, die angezeigt wird, wenn die Themenoptionen ausgewählt werden. Daher ist es sinnvoll, dass sie gerendert wird, wenn das Menü der obersten Ebene ausgewählt wird und wenn der Menüpunkt "Anzeigeoptionen" ausgewählt wird .

An dieser Stelle gibt es eine wichtige Funktion von WordPress, die hervorgehoben werden muss: Beachten Sie, dass WordPress nach dem Hinzufügen Ihres ersten Untermenüelements tatsächlich zwei Untermenüelemente zum Menü der obersten Ebene rendert - ein Element, das die Funktion der obersten Ebene dupliziert Menü und ein Element, das dem soeben definierten Untermenüelement entspricht. Ich spreche das an, weil ich meiner Erfahrung nach gesehen habe, wie Entwickler verwirrt waren, wie (und warum) dies geschieht. Das kurze daran ist, dass WordPress dies tut - es ist nichts falsch mit Ihrem Code.

Soziale Optionen

Das Hinzufügen eines Menüelements für die sozialen Optionen entspricht fast genau dem Hinzufügen eines Menüelements für die Anzeigeoptionen. Natürlich möchten wir nur die Werte für die Titelleiste, den Menüpunkt und die Seite ändern, die angezeigt wird, wenn das Menü ausgewählt wird. Lassen Sie uns zunächst den Aufruf der Funktion add_submenu_page einrichten. Es sollte so aussehen:

add_submenu_page(
	'sandbox_theme',
	'Social Options',
	'Social Options',
	'administrator',
	'sandbox_theme_social_options',
	'sandbox_theme_display'
);

Speichern Sie Ihren Code, aktualisieren Sie Ihr Dashboard, und Sie sollten den Menüpunkt "Soziale Optionen" sehen, der jetzt im Menü "Sandbox-Thema" verfügbar ist. Beachten Sie jedoch, dass durch Klicken auf das neue Untermenüelement nur die "Anzeigeoptionen" angezeigt werden. Da wir das "sandbox_theme_display" als Funktionsnamen übergeben haben, sollten wir das erwarten, oder? Jetzt stehen wir also vor einer kleinen Herausforderung: Wie wählen wir die Registerkarte "Soziale Optionen" aus, wenn wir auf den Untermenüpunkt klicken?

Refactoring unserer Tab-Funktionalität

Es gibt verschiedene Möglichkeiten, um das neue Untermenüelement an die richtige Registerkarte auf der Seite mit den Themenoptionen zu binden:

Wir können eine neue Funktion definieren, die die sozialen Optionen wiedergibt. Dies würde erfordern, dass wir zusätzliche Arbeit leisten, um eine neue Funktion einzuführen, Tabbing-Funktionen einzurichten, damit die Erfahrung der vorhandenen Seite nicht beeinträchtigt wird, und ein wenig Code zu duplizieren.
Wir können die vorhandene Funktion sandbox_theme_display umgestalten, um einen optionalen Parameter zu akzeptieren, und dann eine anonyme Funktion im Aufruf add_submenu_page verwenden, um einen Parameter an diesen zu übergeben.

Letztendlich liegt jede dieser Optionen bei Ihnen. Ich würde jedoch lieber meine vorhandene Funktion umgestalten, als Code zu duplizieren, also werde ich das im weiteren Verlauf dieses Artikels tun.

Beginnen wir zunächst mit der Überarbeitung unserer Funktion sandbox_theme_display. Lassen Sie es ein optionales Argument akzeptieren, das verwendet wird, um anzugeben, welche Registerkarte wir auswählen möchten. Suchen Sie die folgende Signatur in Ihrer Datei functions.php:

1	function sandbox_theme_display() {
2	/* Consolidated for this part of the article. */
3	} // end sandbox_theme_display

Aktualisieren Sie die Signatur so, dass sie ein einzelnes Argument akzeptiert und auf null setzt, wenn es nicht definiert ist:

1	function sandbox_theme_display( $active_tab = null ) {
2	/* Consolidated for this part of the article. */
3	} // end sandbox_theme_display

Wenn Sie PHP noch nicht kennen, können Sie sich auf dieser Seite über Standardargumente informieren.

Denken Sie aus dem letzten Artikel daran, dass unsere Anzeigefunktion tatsächlich nach einem einzustellenden Abfragezeichenfolgenwert sucht. Wir möchten diese Funktionalität weiterhin beibehalten, müssen jedoch berücksichtigen, dass der Parameter möglicherweise auch an die Funktion übergeben wird. Um dieses Refactoring durchzuführen, suchen Sie zuerst die folgende Codezeile in der Funktion sandbox_theme_display:

1	$active_tab = isset( $_GET[ 'tab' ] ) ? $_GET[ 'tab' ] : 'display_options';

Beachten Sie, dass diese bestimmte Codezeile nur die Parameter der Abfragezeichenfolge betrifft. Um den neuen optionalen Parameter zu berücksichtigen, müssen wir eine Logik einführen, die zuerst prüft, ob der Parameter für die Abfragezeichenfolge aktiviert ist. Wenn nicht, wird geprüft, ob das Argument der Funktion so eingestellt ist, dass die sozialen Optionen angezeigt werden, und wenn nicht, dann Standardmäßig werden die Anzeigeoptionen verwendet. Ersetzen Sie die obige Codezeile durch die folgende Bedingung:

if( isset( $_GET[ 'tab' ] ) ) {
	$active_tab = $_GET[ 'tab' ];
} else if( $active_tab == 'social_options' ) {
	$active_tab = 'social_options';
} else {
	$active_tab = 'display_options';
} // end if/else

Die endgültige Version der Funktion sollte folgendermaßen aussehen:

function sandbox_theme_display( $active_tab = '' ) {
?>
	<!-- Create a header in the default WordPress 'wrap' container -->
	<div class="wrap">
	
		<div id="icon-themes" class="icon32"></div>
		<h2>Sandbox Theme Options</h2>
		<?php settings_errors(); ?>
		
		<?php if( isset( $_GET[ 'tab' ] ) ) {
			$active_tab = $_GET[ 'tab' ];
		} else if( $active_tab == 'social_options' ) {
			$active_tab = 'social_options';
		} else {
			$active_tab = 'display_options';
		} // end if/else ?>
		
		<h2 class="nav-tab-wrapper">
			<a href="?page=sandbox_theme_options&tab=display_options" class="nav-tab <?php echo $active_tab == 'display_options' ? 'nav-tab-active' : ''; ?>">Display Options</a>
			<a href="?page=sandbox_theme_options&tab=social_options" class="nav-tab <?php echo $active_tab == 'social_options' ? 'nav-tab-active' : ''; ?>">Social Options</a>
		</h2>
		
		<form method="post" action="options.php">
			<?php
			
				if( $active_tab == 'display_options' ) {
					settings_fields( 'sandbox_theme_display_options' );
					do_settings_sections( 'sandbox_theme_display_options' );
				} else {
					settings_fields( 'sandbox_theme_social_options' );
					do_settings_sections( 'sandbox_theme_social_options' );
				} // end if/else
				
				submit_button();
			
			?>
		</form>
		
	</div><!-- /.wrap -->
<?php
} // end sandbox_theme_display

Wir sind noch nicht ganz fertig. Obwohl wir die notwendige Arbeit geleistet haben, um die sozialen Optionen anzuzeigen, wenn der richtige Parameter übergeben wurde, haben wir die Funktion nicht tatsächlich mit einem Parameter aufgerufen. Dazu müssen wir die Funktion add_submenu_page von oben umgestalten. Derzeit sieht der Funktionsaufruf folgendermaßen aus:

add_submenu_page(
	'sandbox_theme',
	'Social Options',
	'Social Options',
	'administrator',
	'sandbox_theme_social_options',
	'sandbox_theme_display'
);

Wir müssen den letzten Parameter aktualisieren, damit er die Anzeigefunktion aufruft und den richtigen Wert zum Rendern der sozialen Optionen übergibt. Dazu erstellen wir eine anonyme Funktion:

add_submenu_page(
	'sandbox_theme_menu',
	'Social Options',
	'Social Options',
	'administrator',
	'sandbox_theme_social_options',
	create_function( null, 'sandbox_theme_display( "social_options" );' )
);

Wenn Sie PHP noch nicht kennen, lesen Sie unbedingt die Funktion create_function und die anonymen Funktionen. Obwohl sie nicht in den Geltungsbereich dieses Artikels fallen, können sie im richtigen Kontext leistungsstark (und nützlich!) Sein.

Die endgültige Version der Funktion sandbox_example_theme_menu sollte wie folgt lauten:

function sandbox_example_theme_menu() {

	add_theme_page(
		'Sandbox Theme', 					// The title to be displayed in the browser window for this page.
		'Sandbox Theme',					// The text to be displayed for this menu item
		'administrator',					// Which type of users can see this menu item
		'sandbox_theme_options',			// The unique ID - that is, the slug - for this menu item
		'sandbox_theme_display'				// The name of the function to call when rendering this menu's page
	);
	
	add_menu_page(
		'Sandbox Theme',					// The value used to populate the browser's title bar when the menu page is active
		'Sandbox Theme',					// The text of the menu in the administrator's sidebar
		'administrator',					// What roles are able to access the menu
		'sandbox_theme_menu',				// The ID used to bind submenu items to this menu 
		'sandbox_theme_display'				// The callback function used to render this menu
	);
	
	add_submenu_page(
		'sandbox_theme_menu',				// The ID of the top-level menu page to which this submenu item belongs
		'Display Options',					// The value used to populate the browser's title bar when the menu page is active
		'Display Options',					// The label of this submenu item displayed in the menu
		'administrator',					// What roles are able to access this submenu item
		'sandbox_theme_display_options',	// The ID used to represent this submenu item
		'sandbox_theme_display'				// The callback function used to render the options for this submenu item
	);
	
	add_submenu_page(
		'sandbox_theme_menu',
		'Social Options',
		'Social Options',
		'administrator',
		'sandbox_theme_social_options',
		create_function( null, 'sandbox_theme_display( "social_options" );' )
	);

} // end sandbox_example_theme_menu
add_action( 'admin_menu', 'sandbox_example_theme_menu' );

Abschluss

Zu diesem Zeitpunkt verfügt unser Thema nun über einen eigenen Menüpunkt der obersten Ebene, auf den alle Einstellungsregisterkarten über Untermenüelemente zugreifen können. Obwohl dies nützlich ist, halte ich es für wichtig zu beachten, dass es einige gemischte Meinungen zur Einführung von Menüs in das WordPress-Dashboard gibt. Obwohl sie Ihre Arbeit bekannter und zugänglicher machen können, können sie auch vorhandene WordPress-Menüs oder andere Arbeiten von Drittanbietern beeinträchtigen, insbesondere wenn Sie versuchen, Ihre Menüs mithilfe des Positionsparameters irgendwo zu platzieren. Obwohl es bei der Einführung von Menüs kein absolutes Richtig oder Falsch gibt, sollten Sie sorgfältig überlegen, wo Sie Ihre Menüs verfügbar machen. Wenn ein vorhandenes WordPress-Menü sinnvoll ist, registrieren Sie Ihre Arbeit als Untermenü.

Im nächsten Beitrag werden wir uns die verschiedenen Eingabeelemente ansehen, mit denen wir Optionen in unser WordPress-Theme einführen können, sowie die Validierung und Bereinigung der Daten vor der Serialisierung.