Die WordPress-Einstellungs-API, Teil 6 Menüseiten

In Teil 3 dieser Serie haben wir die verschiedenen Menüfunktionen der WordPress-API untersucht. Wenn Sie mitverfolgt haben, wissen Sie, dass wir bereits eine Einstellungsseite für unser Thema eingerichtet haben add_theme_page Funktion. Obwohl einführende Menüs und Untermenüs nicht explizit Teil der Einstellungs-API sind, spielen sie eine Rolle beim Erstellen benutzerdefinierter Funktionen, Plugins und / oder Designs.

In diesem Artikel werden wir ein neues Menü in das WordPress-Dashboard einführen, das unsere Designoptionen an anderer Stelle als nur unter den "Erscheinungsbild" -Optionen verfügbar macht.

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

Ein Blick auf die API

Da wir uns bereits mit den einzelnen Menüfunktionen befasst haben, müssen wir nicht alle Funktionen von WordPress erneut verwenden. Stattdessen schauen wir uns die an, die wir verwenden werden, und erarbeiten dann ein praktisches Beispiel, wie wir sie in unserer eigenen Arbeit einsetzen können.

Bevor wir uns die einzelnen Funktionen ansehen, lassen Sie uns im Detail erläutern, was wir in der nächsten Phase dieser Serie erreichen wollen:

Führen Sie ein Menü auf oberster Ebene für unsere Themenoptionen ein
Fügen Sie ein Untermenüelement hinzu, das mit der Registerkarte "Anzeigeoptionen" verknüpft wird
Fügen Sie ein Untermenüelement hinzu, das mit der Registerkarte "Soziale Optionen" verknüpft wird

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

add_menu_page die zur Einführung von Menüelementen auf oberster Ebene verwendet wird
add_submenu_page wird verwendet, um Untermenüs in Menüs der obersten Ebene einzuführen.

Wir werden einen Blick auf die Parameter und die Nutzung jeder Funktion werfen, während wir sie in unserem Thema implementieren.

Beachten Sie, dass der Rest dieses Artikels auf dieser Version der WordPress Settings Sandbox aufbaut. Wenn Sie das Repository mitverfolgen, stellen Sie sicher, dass Sie es auschecken.

Das Hauptmenü

Als erstes möchten wir ein Menü auf oberster Ebene einführen. Dieses Menü wird direkt unter dem "Einstellungen" -Menü im WordPress-Dashboard angezeigt und dient zwei Zwecken. Das Menü sollte:

Stellen Sie die Optionen des Themas dem WordPress-Dashboard zur Verfügung
Zeigt eine Standardoptionsseite für die Designoptionen an

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

Seitentitel ist der Text, der in der Titelleiste des Browsers dargestellt wird
menu_title ist der Text, der für den Menüpunkt angezeigt wird
Fähigkeit bezieht sich auf die Rolle, die der Benutzer haben muss, um auf dieses Menü zuzugreifen
menu_slug ist ein eindeutiger Wert, der dieses Menü kennzeichnet. So registrieren sich auch Untermenüs mit diesem Menü.
Funktionsname Dies wird aufgerufen, wenn auf das Menü geklickt wird, um die Optionsseite anzuzeigen.
icon_url ist der Pfad zu dem Symbol, das Sie neben Ihrem Menüelement anzeigen möchten.
Position Hier sollte das Menü in Bezug auf die anderen Menüs im WordPress Dashboard hinzugefügt werden.

In unserer Arbeit konzentrieren wir uns nur auf die ersten fünf Parameter. Ich bespreche die Menüpositionierung in diesem Artikel.

Um zu beginnen, müssen wir einen Anruf bei der add_menu_page Funktion. Gemäß dem WordPress-Codex können Verwaltungsmenüs mit dem hinzugefügt werden admin_menu Haken. Zuvor haben wir in dieser Serie eine Funktion geschrieben, die unsere Themenoptionen zum Menü "Aussehen" hinzufügt. Konkret haben wir geschrieben sandbox_example_theme_menu:

Funktion sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Der Titel, der für diese Seite im Browserfenster angezeigt werden soll. 'Sandbox Theme', // Der Text, der für diesen Menüpunkt 'administrator' angezeigt werden soll, // Welche Benutzer sehen diesen Menüeintrag 'sandbox_theme_options'. // Die eindeutige ID - d. h. der Slug - für diesen Menüpunkt 'sandbox_theme_display' // Name der Funktion, die beim Rendern der Menüseite aufgerufen werden soll;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Beachten Sie im obigen Code, dass diese Funktion beim registriert wurde admin_menu Haken auch. Sie sollten sich stets bemühen, Ihre Funktionen logisch konsistent zu halten. Da wir bereits über eine Funktion verfügen, die ein Menü registriert, das mit dem entsprechenden Hook registriert ist, und da wir ähnliche Funktionen einführen, werden wir dieser Funktion unsere neuen Menüfunktionen hinzufügen.

Fügen Sie den folgenden Anruf zu hinzu add_menu_page direkt unter dem oben genannten Aufruf:

add_menu_page ('Sandbox Theme', // Der Wert, der zum Auffüllen der Titelleiste des Browsers verwendet wird, wenn die Menüseite aktiv ist 'Sandbox Theme', // Der Text des Menüs in der Seitenleiste des Administrators 'administrator', // Welche Rollen sind in der Lage? Um auf das Menü 'sandbox_theme_menu' zuzugreifen, // die ID, mit der Untermenüelemente an dieses Menü gebunden werden 'sandbox_theme_display' // Die Rückruffunktion, die zum Rendern dieses Menüs verwendet wird);

Wie Sie sehen, registrieren wir ein Menü, das "Sandbox-Design" sowohl in der Titelleiste des Browsers als auch im Menüelement anzeigt. Wir stellen das Menü nur Administratoren zur Verfügung und haben dem Menü die eindeutige ID von "sandbox_theme_parent_menu". Wir werden diesen Parameter im nächsten Abschnitt erneut verwenden.

Es gibt eine wichtige Sache, die wir klären müssen: Beachten Sie, dass wir bestanden haben 'sandbox_theme_display'als Funktion, die aufgerufen wird, wenn dieser Menüpunkt angeklickt wird. Denken Sie daran, dass wir in Teil 3 diese Funktion eingeführt haben (und in Teil 5 verfeinert haben). Es ist insbesondere für das Rendern unserer Seite mit Optionen für Registerkartenmotive verantwortlich.

Übergeben Sie diesen vorhandenen Funktionsnamen an die add_menu_page Funktion, wir nutzen den Code, den wir bereits geschrieben haben, und rendern eine Standardoptionsseite für den Menüpunkt.

Jetzt können Sie mit dem Hinzufügen von Untermenüs beginnen. Bevor Sie jedoch fortfahren, stellen Sie 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

Fügen Sie die Untermenüs hinzu

Untermenüs sind Menüs sehr ähnlich, außer dass sie zu einem vorhandenen Menü "gehören". Die API zum Registrieren von Untermenüs ist ebenfalls relativ ähnlich. Die Funktion akzeptiert sechs Argumente, wobei die ersten fünf erforderlich sind, wobei das letzte optional ist:

parent_slug bezieht sich auf die eindeutige ID des übergeordneten Menüelements. In unserem Fall, "sandbox_theme_menu".
Seitentitel ist der Text, der in der Symbolleiste des Browsers dargestellt werden soll, wenn dieser Untermenüpunkt aktiv ist
menu_title ist der Text für dieses Untermenüelement im Dashboard
Fähigkeit ist die Rolle, die ein Benutzer benötigen muss, um auf diesen Menüpunkt zuzugreifen
menu_slug ist die eindeutige ID für diesen bestimmten Menüpunkt
Funktionsname Dies wird aufgerufen, wenn auf das Menü geklickt wird, um die Optionsseite anzuzeigen

Die Funktion ist unkompliziert. Wir haben zwei Menüpunkte zur Einführung - einen für "Anzeigeoptionen" und einen für "Soziale Optionen".

Anzeigeoptionen

Lassen Sie uns zunächst ein Untermenüelement für Anzeigeoptionen einführen. Fügen Sie den folgenden Codeblock direkt unter ein add_menu_page nennen wir das oben definiert:

add_submenu_page ('sandbox_theme_menu', // Die ID der obersten Menüseite, zu der dieser Untermenüpunkt 'Display Options' gehört, // Der Wert, mit dem die Titelleiste des Browsers gefüllt wird, wenn die Menüseite aktiv ist 'Display Options'). // Die Bezeichnung dieses Untermenüelements im Menü 'administrator'. // Welche Rollen können auf dieses Untermenüelement 'sandbox_theme_display_options' zugreifen? // Die ID, die für dieses Untermenüelement 'sandbox_theme_display' verwendet wird // Die verwendete Rückruffunktion um die Optionen für diesen Untermenüpunkt darzustellen);

Jeder der oben genannten Parameter sollte eindeutig sein, mit Ausnahme des Funktionsnamens, den wir als abschließendes Argument übergeben haben. Beachten Sie, dass es sich um denselben Funktionsnamen handelt, den wir in angegeben haben add_menu_page Anruf. Aber das macht Sinn, richtig? Schließlich ist die "Anzeigeoptionen" die Standardregisterkarte, die angezeigt wird, wenn die Designoptionen ausgewählt werden. Es macht daher Sinn, dass sie gerendert wird, wenn das Menü auf der obersten Ebene ausgewählt wird und wenn der Menüpunkt "Anzeigeoptionen" ausgewählt wird.

An dieser Stelle gibt es eine wichtige Funktion von WordPress, die hervorgehoben werden soll: Wenn Sie das erste Untermenüelement hinzugefügt haben, zeigt WordPress tatsächlich zwei Untermenüelemente an das Menü der obersten Ebene an - ein Element, das die Funktion der obersten Ebene dupliziert Menü und ein Element, das dem gerade definierten Untermenüelement entspricht. Ich spreche das an, weil nach meiner Erfahrung Entwickler verwirrt waren, wie (und warum) dies geschieht. Kurz gesagt, WordPress macht das - es ist nichts falsch mit Ihrem Code.

Soziale Optionen

Das Hinzufügen eines Menüelements für die sozialen Optionen entspricht fast dem Hinzufügen eines Menüelements für die Anzeigeoptionen. Natürlich möchten wir nur die Werte für die Titelleiste, das Menüelement und die Seite ändern, die angezeigt wird, wenn das Menü ausgewählt wird. Lassen Sie uns zuerst unseren Aufruf an die add_submenu_page Funktion. Es sollte so aussehen:

add_submenu_page ('sandbox_theme', 'Sozialoptionen', 'Sozialoptionen', 'administrator', 'sandbox_theme_social_options', 'sandbox_theme_display'));

Speichern Sie Ihren Code, aktualisieren Sie Ihr Dashboard, und Sie sollten den Menüpunkt "Soziale Optionen" jetzt unter dem Menü "Sandbox-Thema" finden. Beachten Sie jedoch, dass durch Klicken auf den neuen Untermenüpunkt nur die "Anzeigeoptionen" angezeigt werden. Da haben wir die "bestanden"sandbox_theme_display"Als Funktionsnamen sollten wir das erwarten, oder? Wir haben es jetzt mit einer kleinen Herausforderung zu tun: Wie wählen wir die Registerkarte" Soziale Optionen "aus, wenn Sie auf den Untermenüpunkt klicken?

Refactoring unserer Tab-Funktionalität

Es gibt verschiedene Optionen, um das neue Untermenüelement an die entsprechende Registerkarte auf der Seite mit den Designoptionen zu binden:

Wir können eine neue Funktion definieren, die die sozialen Optionen darstellt. Dies erfordert, dass wir einige zusätzliche Arbeit bei der Einführung einer neuen Funktion durchführen müssen, indem wir die Tab-Funktion so einrichten, dass die Erfahrung der vorhandenen Seite nicht beeinträchtigt wird, und ein wenig Code dupliziert wird.
Wir können das Bestehende umgestalten sandbox_theme_display Funktion, um einen optionalen Parameter zu akzeptieren, und verwenden Sie dann eine anonyme Funktion im add_submenu_page Aufruf, um einen Parameter an ihn zu übergeben.

Letztendlich liegt eine dieser Optionen bei Ihnen; Ich möchte jedoch meine vorhandene Funktion eher umgestalten als doppelten Code, so dass ich dies im weiteren Verlauf dieses Artikels tun werde.

Beginnen wir mit der Umgestaltung unserer sandbox_theme_display Funktion. Lassen Sie uns ein optionales Argument akzeptieren, das verwendet wird, um anzugeben, welche Registerkarte wir auswählen möchten. Suchen Sie die folgende Signatur in Ihrem Functions.php Datei:

function sandbox_theme_display () / * Konsolidiert für diesen Teil des Artikels. * / // Sandbox_theme_display beenden

Aktualisieren Sie die Signatur, sodass ein einzelnes Argument akzeptiert wird und es auf null gesetzt wird, wenn es nicht definiert ist:

Funktion sandbox_theme_display ($ active_tab = null) / * Für diesen Teil des Artikels konsolidiert. * / // Sandbox_theme_display beenden

Wenn Sie PHP noch nicht kennen, können Sie auf dieser Seite die Standardargumente nachlesen.

Denken Sie im letzten Artikel daran, dass unsere Anzeigefunktion tatsächlich nach einem Abfragezeichenfolgewert sucht, der festgelegt werden soll. Wir möchten diese Funktionalität weiterhin beibehalten, müssen jedoch berücksichtigen, dass der Parameter auch in die Funktion übergeben werden kann. Um dieses Refactoring durchzuführen, suchen Sie zuerst die folgende Codezeile in der sandbox_theme_display Funktion:

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

Beachten Sie, dass diese bestimmte Codezeile nur die Abfragezeichenfolgeparameter betrifft. Um den neuen optionalen Parameter zu berücksichtigen, müssen wir eine Logik einführen, die zuerst prüft, ob der Parameter für die Abfragezeichenfolge aktiviert ist. Wenn dies nicht der Fall ist, wird geprüft, ob das Argument der Funktion so eingestellt ist, dass die sozialen Optionen angezeigt werden, und wenn nicht, dann Standardmäßig werden die Anzeigeoptionen angezeigt. Ersetzen Sie die 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';  // Ende wenn / else

Die endgültige Version der Funktion sollte folgendermaßen aussehen:

Funktion sandbox_theme_display ($ active_tab = ") ?>

Optionen der Sandbox-Themen

"> Anzeigeoptionen"> Soziale Optionen

Wir sind noch nicht ganz fertig. Obwohl wir die erforderliche Arbeit geleistet haben, um die sozialen Optionen anzuzeigen, wenn der richtige Parameter übergeben wurde, haben wir die Funktion nicht wirklich mit einem Parameter aufgerufen. Um dies zu erreichen, müssen wir das umgestalten add_submenu_page Funktion von oben. Derzeit sieht der Funktionsaufruf so aus:

add_submenu_page ('sandbox_theme', 'Sozialoptionen', 'Sozialoptionen', 'administrator', 'sandbox_theme_social_options', 'sandbox_theme_display'));

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

add_submenu_page ('sandbox_theme_menu', 'Sozialoptionen', 'Sozialoptionen', 'Administrator', 'sandbox_theme_social_options'), create_function (null, 'sandbox_theme_display ("social_options");');

Wenn Sie sich mit PHP noch nicht auskennen, lesen Sie bitte die create_function Feature und anonyme Funktionen. Obwohl sie sich außerhalb des Rahmens dieses Artikels befinden, können sie mächtig (und nützlich!) Sein, wenn sie im richtigen Kontext verwendet werden.

Die endgültige Version des sandbox_example_theme_menu Funktion sollte wie folgt sein:

Funktion sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Der Titel, der für diese Seite im Browserfenster angezeigt werden soll. 'Sandbox Theme', // Der Text, der für diesen Menüpunkt 'administrator' angezeigt werden soll, // Welche Benutzer sehen diesen Menüeintrag 'sandbox_theme_options'. // Die eindeutige ID - d. h. der Slug - für diesen Menüpunkt 'sandbox_theme_display' // Name der Funktion, die beim Rendern der Menüseite aufgerufen werden soll; add_menu_page ('Sandbox Theme', // Der Wert, der zum Auffüllen der Titelleiste des Browsers verwendet wird, wenn die Menüseite aktiv ist 'Sandbox Theme', // Der Text des Menüs in der Seitenleiste des Administrators 'administrator', // Welche Rollen sind in der Lage? Um auf das Menü 'sandbox_theme_menu' zuzugreifen, // die ID, mit der Untermenüelemente an dieses Menü gebunden werden 'sandbox_theme_display' // Die Rückruffunktion, die zum Rendern dieses Menüs verwendet wird); add_submenu_page ('sandbox_theme_menu', // Die ID der obersten Menüseite, zu der dieser Untermenüpunkt 'Display Options' gehört, // Der Wert, mit dem die Titelleiste des Browsers gefüllt wird, wenn die Menüseite aktiv ist 'Display Options'). // Die Bezeichnung dieses Untermenüelements im Menü 'administrator'. // Welche Rollen können auf dieses Untermenüelement 'sandbox_theme_display_options' zugreifen? // Die ID, die für dieses Untermenüelement 'sandbox_theme_display' verwendet wird // Die verwendete Rückruffunktion um die Optionen für diesen Untermenüpunkt darzustellen); add_submenu_page ('sandbox_theme_menu', 'Sozialoptionen', 'Sozialoptionen', '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');

Fazit

Zu diesem Zeitpunkt verfügt unser Thema jetzt über ein eigenes Menüelement auf oberster Ebene, auf das Sie mit den einzelnen Einstellungs-Registerkarten über Untermenüelemente zugreifen können. Obwohl dies nützlich ist, halte ich es für wichtig, zu beachten, dass es unterschiedliche Meinungen gibt, wenn man Menüs in das WordPress-Dashboard einführt. Obwohl sie Ihre Arbeit prominenter und zugänglicher machen können, können sie auch bestehende WordPress-Menüs oder andere Arbeiten von Drittanbietern stören insbesondere wenn Sie versuchen, Ihre Menüs mithilfe des Positionsparameters irgendwo zu platzieren. Obwohl es kein absolutes Recht oder absolutes Unrecht gibt, wenn es um die Einführung von Menüs geht, sollten Sie sich genau überlegen, wo Sie Ihre Menüs ausstellen. Wenn ein vorhandenes WordPress-Menü sinnvoll ist, registrieren Sie Ihre Arbeit als Untermenü.

Im nächsten Beitrag werden wir uns die verschiedenen Eingabeelemente ansehen, die wir verwenden können, um Optionen in unser WordPress-Theme einzuführen, und wie Sie die Daten validieren und bereinigen, bevor Sie sie serialisieren.