⌨️ Slik legger du til din egen seksjon på WordPress-innstillingssiden

Standard WordPress-innstillingssider, «Generelt», «Lesing», «Diskusjon», dekker et nettsteds grunnleggende behov. Men så snart du skriver en plugin eller tilpasser et tema for en kunde, er det innebygde feltsettet ikke lenger nok. Du trenger en blokk med dine egne alternativer: en API-nøkkel, bunntekst, en modusbryter.

Å opprette en egen administratorside for bare to felt er overkill. Det er mye ryddigere å legge til din egen seksjon på en eksisterende innstillingsside, akkurat der standard WordPress-alternativene ligger. Innstillings-API-et gir én enkelt funksjon for dette: add_settings_section.

La oss gå gjennom syntaksen, parametrene og bygge et fungerende eksempel med en seksjon og et felt, fra admin_init-hooken til utdata i adminpanelet. Ingen unødvendige abstraksjoner: bare det du kan kopiere og kjøre selv.

💡 Rask oversikt:

• Definer målsiden (generelt, lesing, skriving, diskusjon, media eller en egendefinert), du trenger dens slug i den fjerde parameteren
• Registrer seksjonen via add_settings_section() på admin_init-hooken: oppgi en ID, tittel og en callback for beskrivende tekst
• Fest felt til seksjonen via add_settings_field(), og lagre selve alternativet via register_setting()
• Kall do_settings_sections() i side-callbacken for egendefinerte sider, seksjonen vil rendres automatisk

Hva Innstillings-API-et er og hvorfor du trenger det

Innstillings-API-et dukket opp i WordPress 2.7 og har siden vært standardmåten å legge til innstillinger i adminpanelet. Ideen er enkel: i stedet for å manuelt skrive ut et <form>-element og håndtere $_POST, beskriver du seksjoner og felt gjennom funksjoner, og WordPress selv rendrer markeringen, håndterer lagring og verifiserer noncen.

De tre pilarene i Innstillings-API-et:

• register_setting(), registrerer et alternativ i wp_options;
• add_settings_section(), oppretter en blokk (seksjon) med en tittel;
• add_settings_field(), legger til et spesifikt felt i en seksjon.

Det er add_settings_section som er ansvarlig for «beholderen», den visuelle blokken som grupperer flere felt under en felles overskrift på innstillingssiden. Uten den er det rett og slett ingen steder å plassere feltene.

Syntaks for add_settings_section

Funksjonssignaturen er konsis, fire obligatoriske parametre og én valgfri array:

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

Funksjonen returnerer ingenting. Den registrerer seksjonen i den globale arrayen $wp_settings_sections, som WordPress henter den fra når do_settings_sections() kalles på målsiden. Hvis du kaller add_settings_section uten en påfølgende do_settings_sections på en egendefinert side, vil seksjonen stille og rolig ikke rendres.

En viktig nyanse: add_settings_section beskriver bare blokken. Selve feltene legges til av separate add_settings_field-kall, som spesifiserer seksjons-ID-en i den femte parameteren. Uten felt forblir seksjonen en tom wrapper, noe som noen ganger er nyttig for en tekstforklaring, men i praksis plasseres nesten alltid minst ett felt ved siden av den.

Funksjonsparametre, hva du skal sende inn

$id (streng, obligatorisk), den unike slug-en for seksjonen. Bruk små bokstaver, tall og understreker: my_plugin_main_section. Du vil spesifisere denne samme ID-en i add_settings_field for å «feste» feltet til seksjonen, og den vises også i id HTML-attributtet til wrapper-taggen.

$title (streng, obligatorisk), seksjonstittelen som administratoren ser. Den skrives ut som en <h2> inne på innstillingssiden. Skriv den i klartekst for administratoren: «Настройки интеграции с CRM», ikke my_plugin_crm_settings.

$callback (callable, obligatorisk), navnet på funksjonen som ekkoer ut den beskrivende teksten mellom seksjonstittelen og feltene. Signatur: function my_callback($args), der $args er en array med nøklene id, title og callback. Hvis ingen forklaring er nødvendig, send inn '__return_false'.

$page (streng, obligatorisk), slug-en til innstillingssiden der seksjonen legges til. Innebygde WordPress-sider: general, reading, writing, discussion, media. For en egendefinert side, slug-en som sendes til add_options_page(). ⚠ Sidene misc og privacy er fjernet fra kjernen (utdatert), WordPress vil automatisk omdirigere misc → general, privacy → reading, men det er bedre å ikke stole på denne oppførselen.

$args (array, valgfri, siden WordPress 6.1.0), en array for å tilpasse seksjonens HTML-wrapper:

$args-argumentet fungerer bare når do_settings_sections() kalles. Hvis do_settings_fields() brukes ved en feil, ignoreres arrayen, og before_section/after_section har stille og rolig ingen effekt.

Praktisk eksempel: en seksjon med et felt på «Generelt»-siden

La oss sette sammen en klar-til-bruk-snutt for functions.php eller din egen plugin. Koden legger til en «Innstillinger for visittkortside»-seksjon på options-general.php-siden med ett tekstfelt, for eksempel for et telefonnummer i bunnteksten.

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
}

Etter å ha lagt til koden, gå til adminpanelet: Innstillinger → Generelt, og under standardfeltene vil du se «Innstillinger for visittkortside»-seksjonen med feltet «Telefonnummer i bunntekst». Lagre siden, og verdien vil bli skrevet til wp_options.

Koden plasseres i functions.php til det aktive temaet eller, mer korrekt, i en separat plugin. En plugin overlever et temabytte, noe functions.php ikke gjør. Hvis seksjonen bare trengs mens et spesifikt tema er aktivt, er functions.php akseptabelt; i alle andre tilfeller, kun en plugin.

$Args-argumentet: hva som endret seg i WordPress 6.1

Før versjon 6.1 hadde add_settings_section nøyaktig fire parametre, og du måtte «fikse på» seksjonswrapperen via CSS etter ID, eller gripe inn i output-bufferen. Fra og med 6.1 ble en femte parameter $args lagt til, og nå settes HTML-innrammingen direkte ved registrering av seksjonen:

• before_section, en div-wrapper eller et forklarende banner FØR innholdet;
• after_section, en avsluttende tagg eller et hint ETTER innholdet;
• section_class, en egendefinert klasse hvis standard form-table ikke er nok.

Et eksempel med et forklarende banner og en egendefinert 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
);

Det som er viktig å huske: after_section skrives ikke ut hvis seksjonen er tom, det vil si når det ikke er noen registrerte felt inne i den. Hvis du regner med en avsluttende </div>, sørg for at minst ett felt er lagt til via add_settings_field. Og viktigst av alt: bruk do_settings_sections(), ikke do_settings_fields(), da sistnevnte vil ignorere $args fullstendig.

Før du bruker before_section / after_section, sjekk WordPress-versjonen, på nettsteder eldre enn 6.1 vil sending av den femte parameteren forårsake en fatal feil. En trygg tilnærming: pakk kallet inn i en global $wp_version-sjekk eller bruk function_exists for å verifisere tilstedeværelsen av hooks.

⁉️🤔 Vanlige spørsmål

Kan jeg hoppe over add_settings_section og legge til felt direkte?

Formelt sett, nei. Felt registreres via add_settings_field(), og den femte parameteren til denne funksjonen krever en seksjons-ID. Hvis seksjonen ikke eksisterer, vil ikke feltet rendres. For et enkelt felt kan du opprette en seksjon med en tom tittel og en '__return_false'-callback, seksjonen vil være usynlig, og feltet vil fungere.

Hva er forskjellen mellom add_settings_section og add_settings_field?

En seksjon er en beholder med en tittel og beskrivende tekst. Et felt er et spesifikt input-element (input, select, checkbox) inne i en seksjon. Én seksjon kan inneholde et hvilket som helst antall felt, alle gruppert under én overskrift og lagret med ett enkelt klikk på «Lagre»-knappen.

Hva skjer hvis jeg spesifiserer en ikke-eksisterende side-slug i $page?

Seksjonen vil bli registrert i $wp_settings_sections, men vil aldri rendres, da WordPress ikke vet på hvilken side den skal skrives ut. Det vil ikke oppstå noen feil, seksjonen vil bare «henge i luften». Sjekk slug-en: for innebygde sider er det general / reading / writing / discussion / media; for egendefinerte, den nøyaktige slug-en fra add_menu_page eller add_options_page.

Kan jeg legge til en seksjon på en annen plugins side?

Ja, hvis du kjenner dens side-slug. Send den inn i $page, og seksjonen vil vises på den andre pluginens innstillingsside. Men dette er en skjør løsning: plugin-forfatteren kan endre slug-en i en oppdatering, og seksjonen din vil «falle av». Bruk det bare for dine egne prosjekter eller når det ikke finnes alternativer.

Hva gjør admin_init-hooken og hvorfor kalles add_settings_section på den?

admin_init utløses ved hver forespørsel til adminpanelet FØR siden rendres. Dette er det rette øyeblikket for å registrere innstillinger: seksjoner og felt må deklareres før WordPress begynner å sette sammen skjemaet. Hvis du kaller add_settings_section senere, for eksempel inne i side-callbacken, vil ikke seksjonen komme med i $wp_settings_sections og vil ikke bli vist.

Din egen seksjon eller en separat side, hva du skal velge

Å legge til en seksjon på general er enklere: mindre kode, og brukeren ser innstillingene på samme sted som de redigerer nettstedstittelen. Men når det er mer enn tre eller fire alternativer, blåser seksjonen opp standardsiden og forvirrer administratoren.

Regelen er enkel: ett eller to alternativer, logisk relatert til generelt-siden (telefonnummer i bunntekst, API-nøkkel for kommentarer), bruk en seksjon på general. Tre eller flere alternativer, frittstående funksjonalitet (en slider, CRM-integrasjon, en prisoversikt), bruk en separat side via add_options_page(). I begge tilfeller er add_settings_section selve byggeklossen der monteringen begynner.

Før du kopierer koden, sørg for at WordPress er oppdatert til siste versjon. $args-arrayen, section_class og before_section/after_section-wrapperne krever minst 6.1, mens selve funksjonen har levd i kjernen siden versjon 2.7. To tiår med bakoverkompatibilitet er ikke en grunn til å sitte på en utdatert motor.