Advertisement
  1. Code
  2. Theme Development

Die WordPress-Einstellungs-API, Teil 2: Abschnitte, Felder und Einstellungen

Scroll to top
Read Time: 20 min
This post is part of a series called The Complete Guide to the WordPress Settings API.
The WordPress Settings API, Part 1: What It Is, Why It Matters
The WordPress Settings API, Part 3: All About Menus

German (Deutsch) translation by Federicco Ancie (you can also view the original English article)

Wenn es um die Entwicklung von WordPress-Themes und -Plugins geht, gibt es verschiedene Möglichkeiten, wie Entwickler ihre Menüs, Optionen und Validierungsfunktionen erstellen können. Die Sache ist die, es gibt wirklich nur eine Möglichkeit, dies in WordPress richtig zu tun: die Einstellungs-API.

Diese Serie soll der endgültige Leitfaden für die Nutzung der WordPress-Einstellungs-API sein, damit Sie einen einzigen Bezugspunkt für die richtige Entwicklung Ihrer Themes und Plugins haben.

Im ersten Artikel dieser Serie haben wir uns ausführlich mit der Einstellungs-API befasst und erklärt, warum sie wichtig ist. Hier tauchen wir in die API ein und erfahren, wie Sie alle Vorteile nutzen können, die sie bietet.

Wir werfen einen Blick auf die grundlegenden Einheiten der WordPress-Optionen – Abschnitte, Felder und Einstellungen – und wie man sie in das native WordPress-Dashboard einfügt.


In Abschnitten, Feldern und Einstellungen

Bevor wir mit dem Schreiben von Code beginnen, ist es wichtig, die drei Hauptkomponenten der WordPress-Einstellungs-API zu verstehen.

  1. Felder sind einzelne Optionen, die auf Menüseiten angezeigt werden. Felder entsprechen tatsächlichen Elementen auf dem Bildschirm. Das heißt, ein Feld wird durch ein Textfeld, ein Optionsfeld, ein Kontrollkästchen usw. verwaltet. Felder repräsentieren einen Wert, der in der WordPress-Datenbank gespeichert ist.
  2. Abschnitte sind eine logische Gruppierung von Feldern. Wenn Sie mit mehreren Feldern arbeiten, werden Sie wahrscheinlich verwandte Optionen zusammen gruppieren - Abschnitte repräsentieren diese Gruppierung. Wenn Ihre Arbeit mehrere Verwaltungsseiten umfasst, entspricht außerdem jeder Abschnitt oft einer eigenen Menüseite (Sie können sie jedoch auch zu bestehenden Abschnitten hinzufügen).
  3. Die Einstellungen werden registriert, nachdem Sie sowohl Felder als auch Abschnitte definiert haben. Stellen Sie sich Einstellungen als eine Kombination aus dem Feld und dem Abschnitt vor, zu dem es gehört.

Machen Sie sich an dieser Stelle keine Sorgen, wenn Sie sich über eine der Hauptkomponenten noch nicht sicher sind. Wir werden uns jede Komponente eingehend ansehen, zusammen mit Beispielquellcode, der alles miteinander verbindet.


Eine Sandbox für unsere Einstellungen

Um mit der Programmierung für die Einstellungs-API zu beginnen, richten wir ein grundlegendes Thema ein, das in diesem Artikel und im Rest der Serie verwendet werden kann. Der gesamte Quellcode ist auch auf GitHub verfügbar.

Navigieren Sie in Ihrer lokalen Installation von WordPress zum Verzeichnis „themes“ und erstellen Sie ein neues, leeres Verzeichnis und nennen Sie es „WordPress-Settings-Sandbox“. Fügen Sie die folgenden drei Dateien hinzu:

  • style.css – Dies ist das Stylesheet für das Theme. Es enthält alle Metainformationen zum Thema. Es wird von WordPress benötigt
  • index.php – Dies ist die Standardvorlage für das Thema. Es kann zunächst leer sein. Es wird von WordPress benötigt
  • functions.php – Hier werden wir die meiste Arbeit erledigen. Wir werden dies während des Tutorials ausfüllen

Fügen Sie style.css den folgenden Code hinzu:

Als nächstes fügen Sie der index.php den folgenden Code hinzu:

Beachten Sie, dass das obige Markup außergewöhnlich einfach ist und ich nicht empfehle, es als Grundlage für die Themenentwicklung zu verwenden. Es ist auf diese Artikelserie zugeschnitten und bietet lediglich die Möglichkeit, Werte aus der Einstellungs-API zu lesen.

Aktualisieren Sie auf dem Bildschirm zur Verwaltung von Designs die Seite und Sie sollten sehen, dass das neue Sandbox-Design angezeigt wird. Fahren Sie fort und aktivieren Sie es.

Theme Selection

An diesem Punkt sind wir bereit, loszulegen.


Unsere ersten Optionen

Beachten Sie, dass wir in der obigen Indexvorlage drei spezifische Inhaltsbereiche definiert haben: Kopfzeile, Inhalt und Fußzeile. Lassen Sie uns mit der Einstellungs-API einen Abschnitt "Allgemein" mit drei Feldern erstellen, von denen jedes einem der spezifischen Inhaltsbereiche entspricht, die wir gerade definiert haben.

Bevor ich Code schreibe, finde ich es immer hilfreich, genau aufzulisten, was ich tun muss. In diesem Fall müssen wir Folgendes tun:

  • Definieren Sie einen Abschnitt, der verwendet wird, um jedes Feld zu gruppieren
  • Fügen Sie dem oben definierten Abschnitt drei Felder hinzu – eines für jeden Inhaltsbereich.
  • Registrieren Sie die Einstellungen mit der WordPress-API.

Um massive Codeblöcke zu vermeiden und sicherzustellen, dass wir alle unsere Grundlagen abdecken, werden wir jeden der oben genannten Punkte Punkt für Punkt betrachten.

Abschnitt erstellen

Um unseren Abschnitt "Allgemein" mit Optionen zu finden, müssen wir die Funktion add_settings_section der Einstellungs-API verwenden. Laut WordPress-Codex erfordert add_settings_section drei Argumente:

  • ID – Dies ist die eindeutige Kennung für diesen bestimmten Abschnitt. Beachten Sie, dass dies der Wert ist, der verwendet wird, um jedes Feld in diesem Abschnitt zu registrieren. Fühlen Sie sich frei, es zu benennen, wie Sie möchten, aber ich empfehle, es aus Gründen der Lesbarkeit klar zu machen.
  • Titel – Dieser Wert wird oben auf der Seite im WordPress-Dashboard angezeigt, wenn Benutzer mit Ihren Optionen arbeiten.
  • Callback – Dies ist der Name einer Funktion, die wir definieren, die Text auf dem Bildschirm für die Funktion rendert. Es kann für eine Vielzahl von Funktionen verwendet werden. Im einfachsten Fall kann es verwendet werden, um eine Anleitung oder Beschreibung für Ihre Optionsseite bereitzustellen.
  • Seite – Dieser Wert wird verwendet, um WordPress mitzuteilen, auf welcher Seite Ihre Optionen angezeigt werden sollen. In einem zukünftigen Artikel werden wir dies verwenden, um unseren eigenen benutzerdefinierten Seiten Optionen hinzuzufügen. Vorerst fügen wir dies der vorhandenen Seite Allgemeine Optionen hinzu.

Lassen Sie uns damit fortfahren und unseren Abschnitt definieren. Sehen Sie sich den folgenden, kommentierten Code an. Wir fügen dies unserer Datei functions.php hinzu.

Ein Wort zu den Code-Snippets in dieser Serie: Kopieren Sie diesen Code nicht einfach und fügen Sie ihn ein. Nehmen Sie sich die Zeit, jede Zeile zu lesen, sehen Sie, wie die Argumente mit den einzelnen API-Funktionen übereinstimmen, die wir behandeln, und folgen Sie den entsprechenden Kommentaren, um sicherzustellen, dass Sie verstehen, was wir tun:

Sinn ergeben? Im Allgemeinen sieht es nicht nach viel aus, aber navigieren Sie zu Ihrem Einstellungsmenü und klicken Sie auf Allgemein. Scrollen Sie zum Ende der Seite und Sie sollten Ihren neuen Abschnitt mit Optionen sehen.

General SettingsGeneral SettingsGeneral Settings

Sie können diesen Abschnitt zu jeder der Seiten im Menü Einstellungen hinzufügen. Im obigen Beispiel haben wir "general" als letzten Parameter an den add_settings_section übergeben, aber wenn Sie ihn zu einer anderen Seite hinzufügen möchten, können Sie einen anderen Seitentitel angeben. Hier ist eine Referenz für jede der Einstellungsseiten und ihre entsprechenden Tasten:

  • Allgemein, "allgemein"
  • Schreiben, "schreiben"
  • Lesen, "lesen"
  • Diskussion, "Diskussion"
  • Medien, "Medien"
  • Datenschutz, "Datenschutz"
  • Permalinks, "Permalink"

Felder hinzufügen

Nachdem wir nun einen Abschnitt definiert haben, können wir einige Optionen einführen. Denken Sie daran, dass wir in unserer Indexvorlage drei spezifische Containerelemente definiert haben: Kopfzeile, Inhalt und Fußzeile.

Obwohl wir im Laufe dieser Serie weitere Optionen einführen werden, werden wir heute eine Möglichkeit vorstellen, die Sichtbarkeit jedes der oben genannten Elemente umzuschalten.

Ähnlich wie im Abschnitt "Einstellungen" möchte ich genau auflisten, was wir tun müssen, bevor wir Code schreiben. Da wir jeden der Inhaltsbereiche umschalten werden...

  • Wir brauchen drei Optionen – eine für jeden Inhaltsbereich
  • Da wir die Sichtbarkeit umschalten, können wir ein Kontrollkästchen als Oberflächenelement verwenden use

An dieser Stelle sind wir bereit, das erste Einstellungsfeld vorzustellen. Dazu verwenden wir die Funktion add_settings_field. Diese Funktion benötigt sechs Parameter (vier erforderlich, zwei optional). Sie sind wie folgt:

  • ID – Die ID des aktuellen Felds. Dies wird verwendet, um den Wert im gesamten Design zu speichern und abzurufen. Ich empfehle, dies sinnvoll zu benennen, um die Lesbarkeit Ihres Codes zu verbessern.
  • Titel – Dieser Wert wendet einen Titel auf die Feldoption auf der Verwaltungsseite an. Dies sollte klar sein, da es von Endbenutzern gelesen wird.
  • Rückruf – Dies ist der Name der Funktion, die verwendet wird, um das eigentliche Oberflächenelement zu rendern, mit dem Benutzer interagieren.
  • Seite – Ähnlich wie im Abschnitt, den wir umrissen haben, gibt dieser Parameter an, auf welcher Seite sich diese Option befinden soll. Wenn Sie nur eine einzelne Option einführen, können Sie sie einer vorhandenen Seite anstelle eines von Ihnen definierten Abschnitts hinzufügen.
  • Abschnitt – Dies bezieht sich auf den Abschnitt, den Sie mit der Funktion add_settings_section erstellt haben. Dieser Wert ist die ID, die Sie beim Erstellen Ihres Abschnitts angegeben haben. Dies ist ein optionaler Parameter.
  • Argumente – Dies ist ein Array von Argumenten, die an die Callback-Funktion übergeben werden. Dies ist nützlich, wenn es zusätzliche Informationen gibt, die Sie in das Rendern Ihres Optionselements einbeziehen möchten. Dies ist ein optionaler Parameter.

Lassen Sie uns damit fortfahren und unser erstes Einstellungsfeld definieren. Insbesondere werden wir eine Option zum Umschalten der Sichtbarkeit des Headers einführen.

Zuerst rufen wir add_settings_field direkt unter dem Funktionsaufruf add_settings_section in der Initialisierungsfunktion auf, die wir im ersten Teil des Tutorials geschrieben haben. Überprüfen Sie jede Zeile und die Kommentare für jede Option:

Als nächstes definieren wir den Callback, auf den sich die obige Funktion bezieht. Dieser Callback wird verwendet, um das Kontrollkästchen und die Beschreibung auf der Administrationsseite zu rendern:

Was das Kontrollkästchen betrifft, achten Sie auf die Kommentare, aber machen Sie sich keine Sorgen um einige der Attribute, die Sie nicht kennen (wie zum Beispiel einen Aufruf der Funktion checked()). Später in dieser Serie werden wir uns die einzelnen Eingabeelemente und ihre entsprechenden Hilfsfunktionen ansehen.

Ihre Datei functions.php sollte jetzt so aussehen:

Aktualisieren Sie an dieser Stelle die Seite Allgemeine Einstellungen. Sie sollten Ihr Kontrollkästchen mit dem Label "Header" und einer Beschreibung neben dem Kontrollkästchen sehen.

First OptionFirst OptionFirst Option

Leider wird der Wert noch nicht in der Datenbank gespeichert.

Registrieren unserer Einstellungen

Damit unsere Felder tatsächlich in der Datenbank gespeichert werden, müssen wir sie bei WordPress registrieren. Dies ist relativ einfach - wir müssen nur die Funktion register_setting nutzen.

Diese Funktion akzeptiert drei Argumente (zwei erforderlich, eines optional):

  • Optionsgruppe – Dies ist eigentlich der Name der Optionsgruppe. Dies kann entweder eine vorhandene Gruppe von Optionen sein, die von WordPress bereitgestellt werden, oder eine ID, die wir beim Erstellen unseres eigenen Einstellungsbereichs angegeben haben. Dieses Argument ist erforderlich.
  • Optionsname – Dies ist die ID des Felds, das wir registrieren. In unserem Fall registrieren wir nur ein einzelnes Feld, aber wenn wir mehrere Felder registrieren, müssen wir diese Funktion für jedes registrierte Feld aufrufen. Wir werden gleich mehr dazu sehen. Dieses Argument ist erforderlich.
  • Callback – Dieses Argument erfordert den Namen einer Funktion, die vor dem Speichern der Daten in der Datenbank aufgerufen wird. Dieses Argument ist außerhalb des Rahmens dieses Artikels, aber wir werden es besuchen, bevor die Serie zu Ende ist. Dieses Argument ist optional.

Lassen Sie uns an dieser Stelle die Einstellung registrieren, die wir gerade erstellt haben. Schauen Sie sich den Code unten an. Fügen Sie diese Codezeile direkt unter dem Aufruf von add_settings_field in der Initialisierungsfunktion hinzu, die wir weiter oben im Artikel definiert haben. Es ist wohl der einfachste von allen Ausschnitten in diesem Artikel:

Probieren Sie es aus - aktivieren Sie das Kontrollkästchen, klicken Sie auf "Änderungen speichern" und beachten Sie, dass sich die Option beim Aktualisieren der Seite geändert hat. Deaktivieren Sie das Kontrollkästchen, speichern Sie und sehen Sie zu, wie es gespeichert wird.

Saved OptionSaved OptionSaved Option

Einfach genug, oder?

Hinzufügen der letzten beiden Optionen

Wir müssen noch die Optionen zum Umschalten der Sichtbarkeit des Inhaltsbereichs und des Fußbereichs einführen. Es ist fast genauso, wie wir die Option zum Umschalten des Headers einrichten.

Zunächst definieren wir das Feld für die Anzeige des Inhaltsbereichs. Dies geht unter den ersten Aufruf von add_settings_field:

Und lassen Sie uns die Callback-Funktion einrichten:

Als nächstes definieren wir das Feld für die Anzeige des Fußzeilenbereichs:

Und richten Sie auch den Rückruf für dieses Feld ein:

Zum Schluss registrieren wir diese beiden neuen Felder bei WordPress. Diese beiden Funktionsaufrufe stehen am Ende der Initialisierungsfunktion, die wir zuvor in diesem Artikel definiert haben.

Die endgültige Version von functions.php sollte wie folgt aussehen:

Aktualisieren Sie nun die Seite Allgemeine Einstellungen und stellen Sie fest, dass alle drei Kontrollkästchen voll funktionsfähig sind.

Final OptionsFinal OptionsFinal Options

Lesen der API

Was nützen Optionen, wenn wir sie nicht in unserem gesamten Theme oder unserem Plugin nutzen können? Wir müssen in der Lage sein, die Werte zu lesen, um unsere neuen Optionen richtig verwalten zu können.

Dazu müssen wir die Funktion get_option verwenden. Diese Funktion akzeptiert zwei Argumente (eines erforderlich, eines optional):

  • Options-ID – Dieses Argument ist die ID des Felds für den Wert, den Sie abrufen möchten. Dieses Argument ist erforderlich.
  • Standardoption – Dies ist der Wert, den die Funktion zurückgibt, wenn die Funktion einen leeren Wert zurückgibt (z. B. wenn die Option nicht in der Datenbank gefunden wird). Dieses Argument ist optional.

Versuchen wir zunächst, die Sichtbarkeit des Headers umzuschalten. Suchen Sie in der Indexvorlage, die wir weiter oben in diesem Artikel erstellt haben, das Element mit der ID von header. Es sollte so aussehen:

Als Nächstes rufen wir get_option im Kontext einer Bedingung auf. Wenn die Bedingung wahr ist (dh die Option wurde auf der Seite Allgemeine Einstellungen aktiviert), wird das Element angezeigt; Andernfalls wird das Element nicht angezeigt.

Gehen Sie danach zur Seite Allgemeine Einstellungen, aktivieren Sie die Option zum Ausblenden des Kopfzeilenelements und aktualisieren Sie Ihre Homepage. Das Kopfelement sollte nicht mehr erscheinen.

An dieser Stelle ist es einfach, den Vorgang auch für das Inhalts- und Fußzeilenelement zu wiederholen. Wir müssen die Inhalts- und Fußzeilenelemente mit Bedingungen umschließen, die das Ergebnis von get_option-Aufrufen auswerten.

Schau mal:

Rufen Sie die Seite Allgemeine Einstellungen erneut auf, aktivieren Sie jedes Kontrollkästchen und aktualisieren Sie die Themenseite. Ihre Elemente sollten jeweils unabhängig voneinander umschalten.


Als nächstes, Menüseiten

Das war es fürs Erste! Wir haben uns alle Funktionen angeschaut, die erforderlich sind, um neue Abschnitte, Felder und Einstellungen in WordPress einzuführen. Natürlich gibt es noch viel mehr abzudecken.

Im nächsten Artikel werfen wir einen Blick darauf, wie wir benutzerdefinierte Menüelemente zum WordPress-Menü hinzufügen und wie wir unsere eigenen Seiten in das WordPress-Dashboard einführen können.


Ähnliche Resourcen

Wir haben in diesem Artikel viel Material behandelt. Hier ist eine Referenz für alles, was wir in diesem Artikel verwendet haben.

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.