⌨️ Hur du lägger till en egen sektion på WordPress inställningssida

Standard WordPress-sidor för inställningar, "Allmänt", "Läsning", "Diskussion", täcker en sajts grundläggande behov. Men så fort du skriver ett tillägg eller anpassar ett tema åt en kund räcker inte de inbyggda fälten längre. Du behöver ett block med egna alternativ: en API-nyckel, sidfotstext, en lägesväxlare.

Att skapa en separat admin-sida för bara två fält är overkill. Det är mycket renare att lägga till en egen sektion på en befintlig inställningssida, precis där standardalternativen i WordPress finns. Settings API erbjuder en enda funktion för detta: add_settings_section.

Låt oss gå igenom dess syntax, parametrar och bygga ett fungerande exempel med en sektion och ett fält, från admin_init-hooken till utskrift i adminpanelen. Inga onödiga abstraktioner: bara det du kan kopiera och köra själv.

💡 Snabb översikt:

• Definiera målsidan (allmänt, läsning, skrivande, diskussion, media eller en anpassad), du behöver dess slug i den fjärde parametern
• Registrera sektionen via add_settings_section() på admin_init-hooken: ange ett ID, en titel och en callback för beskrivande text
• Koppla fält till sektionen via add_settings_field(), och spara själva alternativet via register_setting()
• Anropa do_settings_sections() i sidans callback för anpassade sidor, så renderas sektionen automatiskt

Vad Settings API är och varför du behöver det

Settings API dök upp i WordPress 2.7 och har sedan dess varit standardmetoden för att lägga till inställningar i adminpanelen. Tanken är enkel: istället för att manuellt skriva ut ett <form> och hantera $_POST, beskriver du sektioner och fält genom funktioner, och WordPress själv renderar märkspråket, hanterar sparandet och verifierar noncen.

De tre pelarna i Settings API:

• register_setting(), registrerar ett alternativ i wp_options;
• add_settings_section(), skapar ett block (sektion) med en titel;
• add_settings_field(), lägger till ett specifikt fält i en sektion.

Det är add_settings_section som ansvarar för "behållaren", det visuella blocket som grupperar flera fält under en gemensam rubrik på inställningssidan. Utan den finns det helt enkelt ingenstans att placera fälten.

Add_settings_section syntax

Funktionssignaturen är koncis, fyra obligatoriska parametrar och en valfri array:

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

Funktionen returnerar ingenting. Den registrerar sektionen i den globala arrayen $wp_settings_sections, från vilken WordPress hämtar den när do_settings_sections() anropas på målsidan. Om du anropar add_settings_section utan ett efterföljande do_settings_sections på en anpassad sida, renderas sektionen tyst inte.

En viktig nyans: add_settings_section beskriver bara blocket. Själva fälten läggs till genom separata add_settings_field-anrop, där sektionens ID anges i den femte parametern. Utan fält förblir sektionen en tom omslutare, vilket ibland är användbart för en textförklaring, men i praktiken placeras nästan alltid minst ett fält bredvid den.

Funktionsparametrar, vad du ska skicka in

$id (sträng, obligatorisk), sektionens unika slug. Använd gemener, siffror och understreck: my_plugin_main_section. Du anger samma ID i add_settings_field för att "koppla" fältet till sektionen, och det visas också i id HTML-attributet för omslutningstaggen.

$title (sträng, obligatorisk), sektionstiteln som administratören ser. Den skrivs ut som en <h2> inuti inställningssidan. Skriv den på ett enkelt språk för administratören: «Настройки интеграции с CRM», inte my_plugin_crm_settings.

$callback (anropsbar, obligatorisk), namnet på funktionen som skriver ut den beskrivande texten mellan sektionstiteln och fälten. Signatur: function my_callback($args), där $args är en array med nycklarna id, title och callback. Om ingen förklaring behövs, skicka in '__return_false'.

$page (sträng, obligatorisk), slugen för inställningssidan där sektionen läggs till. Inbyggda WordPress-sidor: general, reading, writing, discussion, media. För en anpassad sida, slugen som skickades till add_options_page(). ⚠ Sidorna misc och privacy har tagits bort från kärnan (utfasad), WordPress omdirigerar automatiskt misc → general, privacy → reading, men det är bättre att inte förlita sig på detta beteende.

$args (array, valfri, sedan WordPress 6.1.0), en array för att anpassa sektionens HTML-omslutare:

Argumentet $args fungerar bara när do_settings_sections() anropas. Om do_settings_fields() används av misstag ignoreras arrayen, och before_section/after_section får tyst ingen effekt.

Praktiskt exempel: en sektion med ett fält på sidan "Allmänt"

Låt oss sätta ihop ett körklart kodsnutt för functions.php eller ditt eget tillägg. Koden lägger till en sektion "Inställningar för visitkortssajt" på sidan options-general.php med ett textfält, till exempel för ett telefonnummer i sidfoten.

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
}

Efter att du lagt till koden, gå till adminpanelen: Inställningar → Allmänt, så ser du sektionen "Inställningar för visitkortssajt" med fältet "Telefonnummer i sidfoten" under standardfälten. Spara sidan, så skrivs värdet till wp_options.

Koden placeras i det aktiva temats functions.php eller, mer korrekt, i ett separat tillägg. Ett tillägg överlever ett temabyte, vilket functions.php inte gör. Om sektionen bara behövs när ett specifikt tema är aktivt är functions.php acceptabelt; i alla andra fall, endast ett tillägg.

Argumentet $args: vad som ändrades i WordPress 6.1

Före version 6.1 hade add_settings_section exakt fyra parametrar, och du var tvungen att "snygga till" sektionens omslutare via CSS med ID, eller gräva i utdatabufferten. Från och med 6.1 lades en femte parameter $args till, och nu kan HTML-inramningen sättas direkt vid registrering av sektionen:

• before_section, en div-omslutare eller en förklarande banner FÖRE innehållet;
• after_section, en avslutande tagg eller en ledtråd EFTER innehållet;
• section_class, en anpassad klass om standard form-table inte räcker till.

Ett exempel med en förklarande banner och en anpassad klass:

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
);

Vad som är viktigt att komma ihåg: after_section skrivs inte ut om sektionen är tom, det vill säga när det inte finns några registrerade fält inuti den. Om du räknar med en avslutande </div>, se till att minst ett fält läggs till via add_settings_field. Och viktigast av allt: använd do_settings_sections(), inte do_settings_fields(), eftersom den senare helt ignorerar $args.

Innan du använder before_section / after_section, kontrollera WordPress-versionen, på sajter äldre än 6.1 kommer ett fatalt fel att uppstå om den femte parametern skickas in. En säker metod: slå in anropet i en global $wp_version-kontroll eller använd function_exists för att verifiera att hookarna finns.

⁉️🤔 Vanliga frågor

Kan jag hoppa över add_settings_section och lägga till fält direkt?

Formellt sett, nej. Fält registreras via add_settings_field(), och den femte parametern i denna funktion kräver ett sektions-ID. Om sektionen inte finns kommer fältet inte att renderas. För ett enskilt fält kan du skapa en sektion med en tom titel och en '__return_false'-callback, sektionen blir osynlig och fältet fungerar.

Vad är skillnaden mellan add_settings_section och add_settings_field?

En sektion är en behållare med en titel och beskrivande text. Ett fält är ett specifikt inmatningselement (input, select, checkbox) inuti en sektion. En sektion kan innehålla valfritt antal fält, alla grupperade under en rubrik och sparade med ett enda klick på "Spara"-knappen.

Vad händer om jag anger en icke-existerande sidslug i $page?

Sektionen registreras i $wp_settings_sections men kommer aldrig att renderas, eftersom WordPress inte vet på vilken sida den ska skrivas ut. Inget fel uppstår, sektionen bara "hänger i luften". Kontrollera slugen: för inbyggda sidor är det general / reading / writing / discussion / media; för anpassade, den exakta slugen från add_menu_page eller add_options_page.

Kan jag lägga till en sektion på ett annat tilläggs sida?

Ja, om du känner till dess sidslug. Skicka in den i $page, så visas sektionen på det andra tilläggets inställningssida. Men detta är en bräcklig lösning: tilläggets utvecklare kan ändra slugen i en uppdatering, och din sektion "ramlar bort". Använd det bara för dina egna projekt eller när det inte finns några alternativ.

Vad gör admin_init-hooken och varför anropas add_settings_section på den?

admin_init körs vid varje anrop till adminpanelen INNAN sidan renderas. Detta är rätt tillfälle att registrera inställningar: sektioner och fält måste deklareras innan WordPress börjar bygga formuläret. Om du anropar add_settings_section senare, till exempel inuti sidans callback, hinner sektionen inte med i $wp_settings_sections och visas inte.

Din egen sektion eller en separat sida, vad du ska välja

Att lägga till en sektion på general är enklare: mindre kod, och användaren ser inställningarna på samma ställe där de redigerar sajtens titel. Men när det finns fler än tre eller fyra alternativ sväller sektionen ut standardsidan och förvirrar administratören.

Regeln är enkel: ett eller två alternativ, logiskt kopplade till den allmänna sidan (telefonnummer i sidfoten, API-nyckel för kommentarer), använd en sektion på general. Tre eller fler alternativ, fristående funktionalitet (en slider, CRM-integration, en prisgrid), använd en separat sida via add_options_page(). I båda fallen är add_settings_section själva byggblocket där monteringen börjar.

Innan du kopierar koden, se till att WordPress är uppdaterat till den senaste versionen. Arrayen $args, section_class och omslutarna before_section/after_section kräver minst 6.1, medan själva funktionen har funnits i kärnan sedan version 2.7. Två decennier av bakåtkompatibilitet är inte en anledning att sitta på en föråldrad motor.