⌨️ So fügen Sie Ihre eigene Sektion zur WordPress-Einstellungsseite hinzu

Standard-WordPress-Einstellungsseiten, „Allgemein", „Lesen", „Diskussion", decken die Grundbedürfnisse einer Website ab. Sobald Sie jedoch ein Plugin schreiben oder ein Theme für einen Kunden anpassen, reicht der eingebaute Feldsatz nicht mehr aus. Sie benötigen einen Block mit Ihren eigenen Optionen: einen API-Schlüssel, einen Footer-Text, einen Modus-Umschalter.

Eine separate Admin-Seite für nur zwei Felder anzulegen, ist übertrieben. Deutlich sauberer ist es, der bestehenden Einstellungsseite einen eigenen Abschnitt hinzuzufügen, genau dort, wo die standardmäßigen WordPress-Optionen leben. Die Settings API stellt dafür eine einzige Funktion bereit: add_settings_section.

Sehen wir uns ihre Syntax und Parameter an und erstellen ein funktionierendes Beispiel mit einem Abschnitt und einem Feld, vom admin_init-Hook bis zur Ausgabe im Admin-Panel. Ohne unnötige Abstraktionen: nur das, was Sie kopieren und selbst ausführen können.

💡 Kurzüberblick:

• Legen Sie die Zielseite fest (general, reading, writing, discussion, media oder eine eigene), Sie benötigen deren Slug im vierten Parameter
• Registrieren Sie den Abschnitt über add_settings_section() am admin_init-Hook: Geben Sie eine ID, einen Titel und einen Callback für den Beschreibungstext an
• Hängen Sie Felder über add_settings_field() an den Abschnitt an und speichern Sie die Option selbst über register_setting()
• Rufen Sie do_settings_sections() im Seiten-Callback für eigene Seiten auf, der Abschnitt wird automatisch gerendert

Was die Settings API ist und warum Sie sie brauchen

Die Settings API erschien in WordPress 2.7 und ist seitdem der Standardweg, um Einstellungen zum Admin-Panel hinzuzufügen. Die Idee ist einfach: Anstatt manuell ein <form> auszugeben und $_POST zu verarbeiten, beschreiben Sie Abschnitte und Felder über Funktionen, und WordPress selbst rendert das Markup, übernimmt das Speichern und verifiziert die Nonce.

Die drei Säulen der Settings API:

• register_setting(), registriert eine Option in wp_options;
• add_settings_section(), erstellt einen Block (Abschnitt) mit einem Titel;
• add_settings_field(), fügt ein bestimmtes Feld zu einem Abschnitt hinzu.

add_settings_section ist für den „Container" verantwortlich, den visuellen Block, der mehrere Felder unter einer gemeinsamen Überschrift auf der Einstellungsseite gruppiert. Ohne ihn gibt es schlicht keinen Ort, an den die Felder gesetzt werden können.

Syntax von add_settings_section

Die Funktionssignatur ist knapp, vier erforderliche Parameter und ein optionales Array:

1
add_settings_section(
2
    string $id,
3
    string $title,
4
    callable $callback,
5
    string $page,
6
    array  $args = array()
7
);

Die Funktion gibt nichts zurück. Sie registriert den Abschnitt im globalen Array $wp_settings_sections, aus dem WordPress ihn abruft, wenn do_settings_sections() auf der Zielseite aufgerufen wird. Wenn Sie add_settings_section ohne ein nachfolgendes do_settings_sections auf einer eigenen Seite aufrufen, rendert der Abschnitt stillschweigend nicht.

Eine wichtige Nuance: add_settings_section beschreibt nur den Block. Die Felder selbst werden durch separate add_settings_field-Aufrufe hinzugefügt, wobei die Abschnitts-ID im fünften Parameter angegeben wird. Ohne Felder bleibt der Abschnitt eine leere Hülle, was gelegentlich für eine Texterklärung nützlich ist, in der Praxis wird jedoch fast immer mindestens ein Feld daneben platziert.

Funktionsparameter, was zu übergeben ist

$id (string, erforderlich), der eindeutige Slug des Abschnitts. Verwenden Sie Kleinbuchstaben, Zahlen und Unterstriche: my_plugin_main_section. Dieselbe ID geben Sie in add_settings_field an, um das Feld an den Abschnitt „anzuhängen", und sie erscheint auch im id-HTML-Attribut des Wrapper-Tags.

$title (string, erforderlich), der Abschnittstitel, den der Administrator sieht. Er wird als <h2> innerhalb der Einstellungsseite ausgegeben. Formulieren Sie ihn in klarer Sprache für den Admin: «Настройки интеграции с CRM», nicht my_plugin_crm_settings.

$callback (callable, erforderlich), der Name der Funktion, die den Beschreibungstext zwischen dem Abschnittstitel und den Feldern ausgibt. Signatur: function my_callback($args), wobei $args ein Array mit den Schlüsseln id, title und callback ist. Wenn keine Erklärung nötig ist, übergeben Sie '__return_false'.

$page (string, erforderlich), der Slug der Einstellungsseite, auf der der Abschnitt hinzugefügt wird. Eingebaute WordPress-Seiten: general, reading, writing, discussion, media. Für eine eigene Seite der Slug, der an add_options_page() übergeben wurde. ⚠ Die Seiten misc und privacy wurden aus dem Kern entfernt (veraltet), WordPress leitet misc → general, privacy → reading automatisch um, aber es ist besser, sich nicht auf dieses Verhalten zu verlassen.

$args (array, optional, seit WordPress 6.1.0), ein Array zur Anpassung des HTML-Wrappers des Abschnitts:

Das Argument $args funktioniert nur, wenn do_settings_sections() aufgerufen wird. Wird versehentlich do_settings_fields() verwendet, wird das Array ignoriert und before_section/after_section bleiben stillschweigend wirkungslos.

Praxisbeispiel: ein Abschnitt mit einem Feld auf der Seite „Allgemein"

Stellen wir ein einsatzbereites Snippet für functions.php oder Ihr eigenes Plugin zusammen. Der Code fügt der Seite options-general.php einen Abschnitt „Visitenkarten-Seiteneinstellungen" mit einem Textfeld hinzu, beispielsweise für eine Telefonnummer im Footer.

1
/**
2
 * Adds a custom section and field to the «General» page.
3
 */
4
function sdstudio_add_visiting_card_section() {
5
    // 1. Section
6
    add_settings_section(
7
        'visiting_card_section',               // Section ID
8
        'Visiting Card Settings',             // Title
9
        'sdstudio_visiting_card_section_cb',   // Callback explanation
10
        'general',                             // «General» page
11
        array(
12
            'before_section' => '<div class="visiting-card-wrapper">',
13
            'after_section'  => '</div>',
14
        )
15
    );
16
 
17
    // 2. Field
18
    add_settings_field(
19
        'footer_phone',                        // Field ID
20
        'Footer Phone Number',                    // Label
21
        'sdstudio_footer_phone_field_cb',      // Callback — renders <input>
22
        'general',                             // Same page
23
        'visiting_card_section'                // Which section to attach to
24
    );
25
 
26
    // 3. Registering the option
27
    register_setting( 'general', 'footer_phone' );
28
}
29
add_action( 'admin_init', 'sdstudio_add_visiting_card_section' );
30
 
31
/**
32
 * Explanatory text above the section fields.
33
 */
34
function sdstudio_visiting_card_section_cb( $args ) {
35
    ?>
36
    <p id="<?php echo esc_attr( $args['id'] ); ?>">
37
        Contact details displayed in the site footer.
38
    </p>
39
    <?php
40
}
41
 
42
/**
43
 * Renders a text input field.
44
 */
45
function sdstudio_footer_phone_field_cb() {
46
    $value = get_option( 'footer_phone', '' );
47
    printf(
48
        '<input type="text" id="footer_phone" name="footer_phone" value="%s" class="regular-text" />',
49
        esc_attr( $value )
50
    );
51
}

Nachdem Sie den Code hinzugefügt haben, gehen Sie ins Admin-Panel: Einstellungen → Allgemein, und unterhalb der Standardfelder sehen Sie den Abschnitt „Visitenkarten-Seiteneinstellungen" mit dem Feld „Telefonnummer im Footer". Speichern Sie die Seite, und der Wert wird in wp_options geschrieben.

Der Code wird in der functions.php des aktiven Themes platziert oder, korrekter, in einem separaten Plugin. Ein Plugin überlebt einen Theme-Wechsel, functions.php hingegen nicht. Wird der Abschnitt nur benötigt, solange ein bestimmtes Theme aktiv ist, ist functions.php akzeptabel; in allen anderen Fällen nur ein Plugin.

Das Argument $args: was sich in WordPress 6.1 geändert hat

Vor Version 6.1 hatte add_settings_section genau vier Parameter, und man musste den Abschnitts-Wrapper per CSS über die ID „nachbessern" oder in den Ausgabepuffer eingreifen. Ab 6.1 wurde ein fünfter Parameter $args hinzugefügt, und nun wird die HTML-Rahmung direkt bei der Registrierung des Abschnitts festgelegt:

• before_section, ein div-Wrapper oder ein erklärender Hinweis VOR dem Inhalt;
• after_section, ein schließendes Tag oder ein Hinweis NACH dem Inhalt;
• section_class, eine eigene Klasse, falls das standardmäßige form-table nicht ausreicht.

Ein Beispiel mit einem erklärenden Hinweis und einer eigenen Klasse:

1
add_settings_section(
2
    'api_keys_section',
3
    'API Keys',
4
    'sdstudio_api_keys_section_cb',
5
    'general',
6
    array(
7
        'before_section' => '<div class="notice notice-info inline"><p>Store keys in wp-config.php, override here only.</p></div>',
8
        'after_section'  => '',
9
        'section_class'  => 'api-keys-section',
10
    )
11
);

Wichtig zu beachten: after_section wird nicht ausgegeben, wenn der Abschnitt leer ist, das heißt, wenn keine Felder darin registriert sind. Wenn Sie auf ein schließendes </div> angewiesen sind, stellen Sie sicher, dass mindestens ein Feld über add_settings_field hinzugefügt wurde. Und vor allem: Verwenden Sie do_settings_sections(), nicht do_settings_fields(), da letzteres $args vollständig ignoriert.

Prüfen Sie vor der Verwendung von before_section / after_section die WordPress-Version, auf Seiten älter als 6.1 führt die Übergabe des fünften Parameters zu einem fatalen Fehler. Ein sicherer Ansatz: Wickeln Sie den Aufruf in eine global $wp_version-Prüfung oder nutzen Sie function_exists, um das Vorhandensein von Hooks zu verifizieren.

⁉️🤔 Häufige Fragen

Kann ich add_settings_section überspringen und Felder direkt hinzufügen?

Formal nein. Felder werden über add_settings_field() registriert, und der fünfte Parameter dieser Funktion erfordert eine Abschnitts-ID. Existiert der Abschnitt nicht, wird das Feld nicht gerendert. Für ein einzelnes Feld können Sie einen Abschnitt mit leerem Titel und einem '__return_false'-Callback erstellen, der Abschnitt ist dann unsichtbar und das Feld funktioniert.

Was ist der Unterschied zwischen add_settings_section und add_settings_field?

Ein Abschnitt ist ein Container mit einem Titel und Beschreibungstext. Ein Feld ist ein konkretes Eingabeelement (input, select, checkbox) innerhalb eines Abschnitts. Ein Abschnitt kann beliebig viele Felder enthalten, alle unter einer Überschrift gruppiert und mit einem einzigen Klick auf die Schaltfläche „Speichern" gesichert.

Was passiert, wenn ich in $page einen nicht existierenden Seiten-Slug angebe?

Der Abschnitt wird in $wp_settings_sections registriert, aber niemals gerendert, da WordPress nicht weiß, auf welcher Seite er ausgegeben werden soll. Es gibt keinen Fehler, der Abschnitt „hängt einfach in der Luft". Prüfen Sie den Slug: Für eingebaute Seiten lautet er general / reading / writing / discussion / media; für eigene Seiten der exakte Slug aus add_menu_page oder add_options_page.

Kann ich einen Abschnitt zur Seite eines anderen Plugins hinzufügen?

Ja, wenn Sie deren Seiten-Slug kennen. Übergeben Sie ihn in $page, und der Abschnitt erscheint auf der Einstellungsseite des anderen Plugins. Das ist jedoch eine fragile Lösung: Der Plugin-Autor kann den Slug in einem Update ändern, und Ihr Abschnitt „fällt heraus". Verwenden Sie dies nur für eigene Projekte oder wenn es keine Alternativen gibt.

Was macht der admin_init-Hook und warum wird add_settings_section daran aufgerufen?

admin_init wird bei jeder Anfrage an das Admin-Panel ausgelöst, BEVOR die Seite gerendert wird. Dies ist der richtige Zeitpunkt, um Einstellungen zu registrieren: Abschnitte und Felder müssen deklariert sein, bevor WordPress mit dem Zusammenbau des Formulars beginnt. Wenn Sie add_settings_section später aufrufen, beispielsweise innerhalb des Seiten-Callbacks, schafft es der Abschnitt nicht in $wp_settings_sections und wird nicht angezeigt.

Eigener Abschnitt oder separate Seite, was zu wählen ist

Einen Abschnitt zu general hinzuzufügen ist einfacher: weniger Code, und der Nutzer sieht die Einstellungen an derselben Stelle, an der er den Seitentitel bearbeitet. Wenn es jedoch mehr als drei oder vier Optionen sind, bläht der Abschnitt die Standardseite auf und verwirrt den Administrator.

Die Regel ist einfach: Ein oder zwei Optionen, die logisch mit der allgemeinen Seite zusammenhängen (Telefonnummer im Footer, API-Schlüssel für Kommentare), nutzen Sie einen Abschnitt auf general. Drei oder mehr Optionen, eigenständige Funktionalität (ein Slider, CRM-Integration, eine Preisübersicht), nutzen Sie eine separate Seite über add_options_page(). In beiden Fällen ist add_settings_section der grundlegende Baustein, mit dem der Aufbau beginnt.

Bevor Sie den Code kopieren, stellen Sie sicher, dass WordPress auf die neueste Version aktualisiert ist. Das $args-Array, section_class und die before_section/after_section-Wrapper erfordern mindestens 6.1, während die Funktion selbst seit Version 2.7 im Kern lebt. Zwei Jahrzehnte Abwärtskompatibilität sind kein Grund, auf einer veralteten Engine zu verharren.