⌨️ Kuinka lisätä oma osio WordPressin asetussivulle

Standard WordPressin asetussivut, "Yleinen", "Lukeminen", "Keskustelu", kattavat sivuston perustarpeet. Mutta heti kun kirjoitat lisäosan tai räätälöit teeman asiakkaalle, sisäänrakennettu kenttävalikoima ei enää riitä. Tarvitset lohkon, jossa on omat asetuksesi: API-avain, alatunnisteen teksti, tilanvaihtokytkin.

Erillisen ylläpitosivun luominen vain kahdelle kentälle on liioittelua. On paljon siistimpää lisätä oma osio olemassa olevalle asetussivulle, juuri sinne, missä WordPressin oletusasetukset sijaitsevat. Settings API tarjoaa tähän yhden funktion: add_settings_section.

Käydään läpi sen syntaksi, parametrit ja rakennetaan toimiva esimerkki, jossa on osio ja kenttä, admin_init-koukusta tulosteeseen ylläpitopaneelissa. Ei turhia abstraktioita: vain se, minkä voit kopioida ja ajaa itse.

💡 Pikaopas:

• Määrittele kohdesivu (general, reading, writing, discussion, media tai mukautettu), tarvitset sen polkutunnisteen neljänteen parametriin
• Rekisteröi osio add_settings_section()-funktiolla admin_init-koukussa: anna tunnus, otsikko ja callback-funktio kuvailevalle tekstille
• Liitä kentät osioon add_settings_field()-funktiolla ja tallenna itse asetus register_setting()-funktiolla
• Kutsu do_settings_sections()-funktiota sivun callbackissa mukautetuille sivuille, osio renderöityy automaattisesti

Mikä Settings API on ja miksi tarvitset sitä

Settings API ilmestyi WordPress 2.7:ssä ja on siitä lähtien ollut standarditapa lisätä asetuksia ylläpitopaneeliin. Idea on yksinkertainen: sen sijaan, että tulostaisit <form>-elementin käsin ja käsittelisit $_POST-muuttujaa, kuvailet osiot ja kentät funktioiden kautta, ja WordPress itse renderöi merkinnän, hoitaa tallennuksen ja varmistaa noncen.

Settings API:n kolme pilaria:

• register_setting(), rekisteröi asetuksen wp_options-tauluun;
• add_settings_section(), luo lohkon (osion), jolla on otsikko;
• add_settings_field(), lisää tietyn kentän osioon.

Juuri add_settings_section on vastuussa "säiliöstä", visuaalisesta lohkosta, joka ryhmittelee useita kenttiä yhteisen otsikon alle asetussivulla. Ilman sitä kentille ei yksinkertaisesti ole paikkaa.

Add_settings_section-syntaksi

Funktion allekirjoitus on ytimekäs, neljä pakollista parametria ja yksi valinnainen taulukko:

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

Funktio ei palauta mitään. Se rekisteröi osion globaaliin $wp_settings_sections-taulukkoon, josta WordPress hakee sen, kun do_settings_sections() kutsutaan kohdesivulla. Jos kutsut add_settings_section-funktiota ilman, että sen jälkeen kutsutaan do_settings_sections-funktiota mukautetulla sivulla, osio jää hiljaisesti renderöitymättä.

Tärkeä vivahde: add_settings_section ainoastaan kuvailee lohkon. Itse kentät lisätään erillisillä add_settings_field-kutsuilla, joissa osion tunnus määritellään viidennessä parametrissa. Ilman kenttiä osio jää tyhjäksi kääreeksi, mikä on joskus hyödyllistä tekstiselitykselle, mutta käytännössä sen viereen sijoitetaan lähes aina vähintään yksi kenttä.

Funktion parametrit, mitä välittää

$id (merkkijono, pakollinen), osion yksilöllinen polkutunniste. Käytä pieniä kirjaimia, numeroita ja alaviivoja: my_plugin_main_section. Määrittelet tämän saman tunnuksen add_settings_field-funktiossa "liittääksesi" kentän osioon, ja se näkyy myös kääreelementin id-HTML-attribuutissa.

$title (merkkijono, pakollinen), osion otsikko, jonka ylläpitäjä näkee. Se tulostetaan <h2>-elementtinä asetussivulla. Kirjoita se ylläpitäjälle selkokielellä: «Настройки интеграции с CRM», ei my_plugin_crm_settings.

$callback (kutsuttava, pakollinen), sen funktion nimi, joka tulostaa kuvailevan tekstin osion otsikon ja kenttien väliin. Allekirjoitus: function my_callback($args), jossa $args on taulukko, jonka avaimet ovat id, title ja callback. Jos selitystä ei tarvita, välitä '__return_false'.

$page (merkkijono, pakollinen), sen asetussivun polkutunniste, johon osio lisätään. WordPressin sisäänrakennetut sivut: general, reading, writing, discussion, media. Mukautetulle sivulle add_options_page()-funktiolle välitetty polkutunniste. ⚠ misc- ja privacy-sivut on poistettu ytimestä (vanhentuneet), WordPress ohjaa automaattisesti misc → general, privacy → reading, mutta tähän toimintaan on parempi olla luottamatta.

$args (taulukko, valinnainen, WordPress 6.1.0:sta lähtien), taulukko osion HTML-kääreen mukauttamiseen:

$args-argumentti toimii vain, kun do_settings_sections() kutsutaan. Jos vahingossa käytetään do_settings_fields()-funktiota, taulukko ohitetaan, eikä before_section/after_section-määrityksillä ole mitään vaikutusta.

Käytännön esimerkki: osio ja kenttä "Yleinen"-sivulla

Kootaan valmis pätkä functions.php-tiedostoon tai omaan lisäosaasi. Koodi lisää "Käyntikorttisivuston asetukset" -osion options-general.php-sivulle yhdellä tekstikentällä, esimerkiksi puhelinnumerolle alatunnisteessa.

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
}

Koodin lisäämisen jälkeen mene ylläpitopaneeliin: Asetukset → Yleinen, ja oletuskenttien alapuolella näet "Käyntikorttisivuston asetukset" -osion, jossa on "Alatunnisteen puhelinnumero" -kenttä. Tallenna sivu, ja arvo kirjoitetaan wp_options-tauluun.

Koodi sijoitetaan aktiivisen teeman functions.php-tiedostoon tai, oikeaoppisemmin, erilliseen lisäosaan. Lisäosa säilyy teeman vaihdossa, toisin kuin functions.php. Jos osiota tarvitaan vain tietyn teeman ollessa aktiivinen, functions.php on hyväksyttävä; kaikissa muissa tapauksissa vain lisäosa.

$Args-argumentti: mikä muuttui WordPress 6.1:ssä

Ennen versiota 6.1 add_settings_section-funktiossa oli tasan neljä parametria, ja osion käärettä piti "viimeistellä" CSS:llä tunnuksen perusteella tai kajota tulostuspuskuriin. Versiosta 6.1 alkaen lisättiin viides parametri $args, ja nyt HTML-kehys asetetaan suoraan osiota rekisteröitäessä:

• before_section, div-kääre tai selittävä banneri ENNEN sisältöä;
• after_section, sulkeva tagi tai vihje sisällön JÄLKEEN;
• section_class, mukautettu luokka, jos standardi form-table ei riitä.

Esimerkki selittävällä bannerilla ja mukautetulla luokalla:

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

Mikä on tärkeää muistaa: after_section-osiota ei tulosteta, jos osio on tyhjä, eli kun sen sisällä ei ole rekisteröityjä kenttiä. Jos lasket sulkevan </div>-tagin varaan, varmista, että vähintään yksi kenttä on lisätty add_settings_field-funktiolla. Ja mikä tärkeintä: käytä do_settings_sections(), älä do_settings_fields(), sillä jälkimmäinen ohittaa $args-argumentin kokonaan.

Ennen before_section / after_section-määritysten käyttöä tarkista WordPress-versio; alle 6.1-versiota vanhemmilla sivustoilla viidennen parametrin välittäminen aiheuttaa kriittisen virheen. Turvallinen lähestymistapa: kääri kutsu global $wp_version -tarkistukseen tai käytä function_exists-funktiota koukkujen olemassaolon varmistamiseksi.

⁉️🤔 Usein kysytyt kysymykset

Voinko ohittaa add_settings_section-funktion ja lisätä kenttiä suoraan?

Muodollisesti et. Kentät rekisteröidään add_settings_field()-funktiolla, ja tämän funktion viides parametri vaatii osion tunnuksen. Jos osiota ei ole olemassa, kenttä ei renderöidy. Yksittäiselle kentälle voit luoda osion, jolla on tyhjä otsikko ja '__return_false'-callback; osio on näkymätön, ja kenttä toimii.

Mikä on ero add_settings_section- ja add_settings_field-funktioiden välillä?

Osio on säiliö, jolla on otsikko ja kuvaileva teksti. Kenttä on tietty syöte-elementti (input, select, checkbox) osion sisällä. Yksi osio voi sisältää minkä tahansa määrän kenttiä, jotka kaikki on ryhmitelty yhden otsikon alle ja tallennetaan yhdellä "Tallenna"-painikkeen napsautuksella.

Mitä tapahtuu, jos määrittelen olemattoman sivun polkutunnisteen $page-parametrissa?

Osio rekisteröidään $wp_settings_sections-taulukkoon, mutta se ei koskaan renderöidy, koska WordPress ei tiedä, millä sivulla se tulostetaan. Virhettä ei tule, osio yksinkertaisesti "roikkuu ilmassa". Tarkista polkutunniste: sisäänrakennetuille sivuille se on general / reading / writing / discussion / media; mukautetuille sivuille tarkka polkutunniste add_menu_page- tai add_options_page-funktiosta.

Voinko lisätä osion toisen lisäosan sivulle?

Kyllä, jos tiedät sen sivun polkutunnisteen. Välitä se $page-parametrissa, ja osio ilmestyy toisen lisäosan asetussivulle. Mutta tämä on hauras ratkaisu: lisäosan tekijä voi muuttaa polkutunnistetta päivityksessä, ja osiosi "putoaa pois". Käytä tätä vain omissa projekteissasi tai kun vaihtoehtoja ei ole.

Mitä admin_init-koukku tekee ja miksi add_settings_section kutsutaan siinä?

admin_init laukeaa jokaisessa ylläpitopaneelin pyynnössä ENNEN sivun renderöintiä. Tämä on oikea hetki rekisteröidä asetukset: osiot ja kentät on määriteltävä ennen kuin WordPress alkaa koota lomaketta. Jos kutsut add_settings_section-funktiota myöhemmin, esimerkiksi sivun callbackin sisällä, osio ei ehdi $wp_settings_sections-taulukkoon eikä sitä näytetä.

Oma osio vai erillinen sivu, kumpi valita

Osion lisääminen general-sivulle on yksinkertaisempaa: vähemmän koodia, ja käyttäjä näkee asetukset samassa paikassa, jossa hän muokkaa sivuston otsikkoa. Mutta kun vaihtoehtoja on enemmän kuin kolme tai neljä, osio paisuttaa vakiosivua ja hämmentää ylläpitäjää.

Sääntö on yksinkertainen: yksi tai kaksi vaihtoehtoa, jotka liittyvät loogisesti yleiseen sivuun (alatunnisteen puhelinnumero, API-avain kommenteille), käytä osiota general-sivulla. Kolme tai useampi vaihtoehto, itsenäinen toiminnallisuus (liukusäädin, CRM-integraatio, hinnoittelutaulukko), käytä erillistä sivua add_options_page()-funktiolla. Molemmissa tapauksissa add_settings_section on juuri se rakennuspalikka, josta kokoaminen alkaa.

Ennen koodin kopioimista varmista, että WordPress on päivitetty uusimpaan versioon. $args-taulukko, section_class ja before_section/after_section-kääreet vaativat vähintään version 6.1, kun taas itse funktio on elänyt ytimessä versiosta 2.7 lähtien. Kaksi vuosikymmentä taaksepäin yhteensopivuutta ei ole syy istua vanhentuneen moottorin päällä.