🛠 Mukautetun kentän lisääminen WordPress-asetuksiin: add_settings_field

Standard WordPress -asetukset kattavat useimmat päivittäiset tehtävät. Ennemmin tai myöhemmin tarvitset kuitenkin kentän, jota hallintapaneelista ei löydy: yrityksen puhelinnumero Yleiset-osiossa, palvelun API-avain, lisenssinumerokenttä tai alatunnisteen teksti.

Teema- ja lisäosakehittäjät hoitavat tämän Settings API:n kautta, joka on joukko WordPress-funktioita omien osioiden ja kenttien rekisteröimiseksi tavallisille asetussivuille. Keskeisin niistä on add_settings_field(): se lisää mukautetun kentän määritettyyn osioon ja sivulle.

Tämän oppaan päätteeksi sinulla on toimiva koodi, joka tulostaa tekstikentän hallintapaneeliin, tallentaa arvon tietokantaan ja näyttää sen sivustolla. Ei kolmannen osapuolen lisäosia, vain sisäänrakennettu API.

💡 Nopea yleiskatsaus:

• Valmistele ympäristösi: luo lapsiteema tai asenna Code Snippets -lisäosa, jotta koodisi ei pyyhkiydy pois, kun pääteema päivittyy.
• Rekisteröi asetus: kutsu register_setting()-funktiota admin_init-koukussa, muuten WordPress ei tallenna kentän tietoja.
• Lisää osio ja kenttä: käytä add_settings_section()-funktiota uudelle lohkolle ja add_settings_field()-funktiota sen sisällä olevalle syötekentälle.
• Tulosta arvo: käytä get_option()-funktiota missä tahansa mallipohjassa näyttääksesi tallennetun tiedon sivustolla.

Mikä add_settings_field on ja missä sitä käytetään

add_settings_field()-funktio ilmestyi WordPress 2.7.0:ssa ja on pysynyt siitä lähtien ensisijaisena työkaluna asetussivujen laajentamiseen. WordPress-dokumentaation mukaan se lisää uuden kentän olemassa olevaan osioon jollakin hallintapaneelin sivuista.

Mitä tämä tarkoittaa käytännössä. Voit tulostaa ylimääräisen kentän mille tahansa vakiosivulle: Yleiset (general), Kirjoittaminen (writing), Lukeminen (reading), Keskustelu (discussion) tai Media (media). Ja jos loit oman asetussivusi add_options_page()-funktiolla, kenttä menee sinnekin.

Tyypillisiä käyttötapauksia:

• "Puhelinnumero"-kenttä yleisissä asetuksissa, jotta ylläpitäjän ei tarvitse koskea koodiin päivittääkseen numeron.
• API-avainkenttä lisäosallesi, johon käyttäjä syöttää avaimen hallintapaneelissa sen sijaan, että muokkaisi wp-config.php-tiedostoa.
• Kenttäryhmä mukautetulle osiolle (puhelin, sähköposti, osoite) käyttäen add_settings_section()-funktiota ja useita add_settings_field()-kutsuja.

Huomautus: add_settings_field() tulostaa vain kentän HTML:n. Varsinaisesta tallennuksesta huolehtii register_setting(); ilman sitä WordPress jättää syötetyt tiedot huomiotta.

Add_settings_field-syntaksi ja parametrit

Funktion allekirjoitus, neljä pakollista ja kaksi valinnaista parametria:

1
add_settings_field(
2
    string $id,
3
    string $title,
4
    callable $callback,
5
    string $page,
6
    string $section = 'default',
7
    array $args = array()
8
);

Käydään läpi jokainen parametri.

$id, yksilöllinen kenttätunniste. Tästä arvosta tulee callback-funktiossa tulostamasi <input>-tagin HTML id-attribuutti. Käytä etuliitettä ristiriitojen välttämiseksi, esimerkiksi myplugin_phone_number.

$title, kentän nimiö, joka näkyy hallintapaneelissa itse syötekentän vasemmalla puolella. Kirjoita se selkeästi: "Puhelinnumero", "Palvelun API-avain".

$callback, sen funktiosi nimi, joka tulostaa kentän HTML:n (input, textarea, select). Tässä kirjoitat echo-komennon. Funktio on määriteltävä etukäteen; välitä se merkkijonona: 'my_field_callback'.

$page, asetussivun polkutunnus. Vakioarvot: general, reading, writing, discussion ja media. Jos loit mukautetun sivun, käytä sen polkutunnusta. Määrittää, missä kenttä näkyy.

$section (valinnainen), sen osion polkutunnus, johon kenttä kuuluu. Oletuksena 'default', joka on sivun ylin osio. Jos loit oman osion add_settings_section()-funktiolla, määritä sen ID tähän.

$args (valinnainen), taulukko lisäasetuksia. Tuetut avaimet ovat label_for (HTML for-attribuutin arvo <label>-tagissa) ja class (CSS-luokka kentän kääreelle).

Kaikki parametrit ja niiden toiminta on kuvattu virallisessa Settings API -oppaassa WordPress.orgissa.

Käytännön esimerkki: tekstikentän lisääminen Yleisiin asetuksiin

Kootaan kaikki yhteen. Tavoite: tulostaa "Puhelinnumero"-tekstikenttä Asetukset → Yleiset -sivulle, tallentaa syötetty arvo ja hakea se get_option()-funktiolla.

Koodi lisätään lapsiteeman functions.php-tiedostoon tai Code Snippets -lisäosan kautta. Jälkimmäinen vaihtoehto on turvallisempi: koodinpätkä ei pyyhkiydy pois teemapäivityksen yhteydessä.

1
// Callback to output the section description
2
function my_custom_section_callback() {
3
    echo 'Contact information for the organization. Phone number is displayed in the site footer.';
4
}
5
 
6
// Callback to output the input field
7
function my_phone_field_callback() {
8
    $value = get_option( 'my_contact_phone', '' );
9
    echo '<input 
10
        name="my_contact_phone" 
11
        type="text" 
12
        id="my_contact_phone" 
13
        value="' . esc_attr( $value ) . '" 
14
        class="regular-text" 
15
        placeholder="+1 (555) 123-4567" 
16
    />';
17
}
18
 
19
// Register the section and field
20
function my_register_settings() {
21
    // Register the setting — without this, data will not be saved
22
    register_setting( 'general', 'my_contact_phone' );
23
 
24
    // Add a section to the General settings page
25
    add_settings_section(
26
        'my_contact_section',            // Section ID
27
        'Contact Information',            // Section title
28
        'my_custom_section_callback',    // Callback for description
29
        'general'                         // Page slug
30
    );
31
 
32
    // Add a field to the section
33
    add_settings_field(
34
        'my_contact_phone',              // Field ID
35
        'Contact Phone',                  // Field label
36
        'my_phone_field_callback',       // Callback to render the field
37
        'general',                        // Page slug
38
        'my_contact_section'             // Section ID
39
    );
40
}
41
add_action( 'admin_init', 'my_register_settings' );

Mitä tässä tapahtuu rivi riviltä. register_setting() kertoo WordPressille: tallenna my_contact_phone-kentän arvo asetuksena wp_options-tauluun, kun "Tallenna muutokset" -painiketta napsautetaan general-sivulla.

add_settings_section() luo uuden lohkon otsikolla "Organisaation yhteystiedot" yleisille asetussivuille. my_custom_section_callback()-callback tulostaa kuvaustekstin osion kenttien yläpuolelle.

add_settings_field() sijoittaa kenttämme kyseisen osion sisään ja linkittää sen my_phone_field_callback()-callbackiin, joka renderöi <input type="text">-elementin. get_option()-funktio lisää tallennetun arvon value-attribuuttiin, ja esc_attr() suojaa tulosteen.

Kaikki koodi on kytketty admin_init-koukkuun, joka laukeaa, kun hallintapaneeli latautuu, ja takaa, että osio ja kenttä on jo rekisteröity siinä vaiheessa, kun asetussivu renderöidään.

Kun olet lisännyt koodin, avaa wp-admin/options-general.php ja näet tuloksen:

Syötä numero, napsauta Tallenna muutokset, ja arvo kirjoitetaan tietokantaan. Näyttääksesi puhelinnumeron sivustolla, käytä get_option()-funktiota missä tahansa mallipohjassa:

1
$phone = get_option( 'my_contact_phone', '' );
2
if ( $phone ) {
3
    echo '<a href="tel:' . esc_attr( $phone ) . '">' . esc_html( $phone ) . '</a>';
4
}

Mihin koodi sijoitetaan ja miten testataan

Kolme sijoitusvaihtoehtoa, huonoimmasta parhaaseen.

Pääteema (functions.php). Älä tee näin. Kun teema päivittyy, tiedosto korvautuu ja räätälöintisi katoaa.

*Lapsiteema (lapsiteeman functions.php).* Toimiva vaihtoehto tiettyyn sivustoon sidotuille muokkauksille. Koodi säilyy pääteeman päivityksissä.

Code Snippets -lisäosa. Paras valinta testaukseen ja pitkäaikaiseen ylläpitoon. Voit ottaa koodinpätkän käyttöön tai pois käytöstä yhdellä napsautuksella koskematta tiedostojärjestelmään. Lisäksi saat eristyksen: jos koodinpätkä aiheuttaa vakavan virheen, WordPress poistaa sen automaattisesti käytöstä, eikä sivusto kaadu.

Testausmenettely. Luo täysi varmuuskopio sivustosta (tietokanta + tiedostot), tämä on vakiovarotoimi kaikissa hallintapaneelin muokkauksissa. Lisää koodi valitsemallasi menetelmällä. Avaa asetussivu ja varmista, että kenttä näkyy. Syötä arvo ja tallenna. Tarkista pysyvyys: päivitä sivu, kentässä pitäisi näkyä syöttämäsi arvo.

Jos kenttä ei tule näkyviin, tarkista, ettet sekoittanut osion ID:tä add_settings_field()-funktion $section-parametrissa. Yleinen virhe: osio luodaan yhdellä ID:llä, mutta kentälle välitetään eri ID.

Video-opastus aiheesta

Materiaalin vahvistamiseksi katso WordPress-kehittäjän video-opastus Settings API:sta. Se näyttää koko syklin: osion rekisteröinnin, kentän lisäämisen, tallentamisen ja tulostamisen sivustolla.

⁉️🤔 Usein kysytyt kysymykset

Voinko lisätä useita kenttiä yhteen osioon?

Kyllä. Kutsu add_settings_field()-funktiota niin monta kertaa kuin tarvitset kenttiä. Välitä sama osion ID $section-parametrissa. Jokainen kenttä saa yksilöllisen $id-tunnisteen ja oman callbackinsa. add_settings_field()-kutsujen järjestys määrittää kenttien järjestyksen sivulla.

Miten lisään select-, textarea- tai checkbox-kentän tekstikentän sijaan?

Kentän tyyppi asetetaan callback-funktion sisällä HTML:n avulla. Select-kenttää varten rakenna <select> ja <option>-tageja; textarea-kenttää varten <textarea>-tagi; checkbox-kenttää varten <input type="checkbox">. Arvo tallennetaan samalla tavalla register_setting()-funktiolla ja haetaan get_option()-funktiolla. Eroavaisuudet ovat vain HTML:ssä.

Pitääkö callbackissa suojata tuloste?

Kyllä, ehdottomasti. Käytä esc_attr()-funktiota attribuuttien arvoille (value, name, id) ja esc_html()-funktiota tagien väliselle tekstille. Tämä suojaa XSS-hyökkäyksiltä ja varmistaa, etteivät tallennetun arvon erikoismerkit riko asettelua.

Voinko lisätä kentän oman lisäosani sivulle?

Kyllä. Luo sivu add_options_page()- tai add_menu_page()-funktiolla ja rekisteröi sitten osiot ja kentät samalla tavalla. Käytä sivusi polkutunnusta add_settings_field()-funktion $page-parametrissa. Mekaniikka ei eroa vakiosivuista.

Entä jos arvo ei tallennu "Tallenna muutokset" -painikkeen napsautuksen jälkeen?

Olet lähes varmasti ohittanut register_setting()-funktion. Ilman tätä funktiota WordPress ei tiedä, että kenttä pitää tallentaa, ja jättää sen huomiotta lähetyksessä. Tarkista: register_setting()-funktion ensimmäisen parametrin on vastattava sivun nimeä (esim. 'general'), ja toisen on vastattava kenttäsi name-attribuuttia.

Yhteenveto: milloin hallintapaneelin asetusten laajentaminen on järkevää

WordPress Settings API on kypsä ja vakaa mekanismi: add_settings_field() ei ole muuttunut versiosta 2.7 lähtien ja on edelleen relevantti vuonna 2026. Omien kenttien lisääminen hallintapaneeliin on perusteltua kolmessa tapauksessa:

• Kehität teemaa tai lisäosaa ja haluat antaa käyttäjälle käyttöliittymän tietojen syöttämiseen ilman koodin muokkaamista.
• Tarvitset sivustotason asetuskentän (puhelinnumero, API-avain, katalogin ID), ja sen pitäisi olla käytettävissä hallintapaneelin kautta, ei wp-config.php:n kautta.
• Räätälöit asiakassivustoa ja haluat, että ylläpitäjä voi itse muuttaa tietoja ottamatta yhteyttä kehittäjään.

Jos kenttä on vain sinua varten ja muuttuu kerran vuodessa, on yksinkertaisempaa kovakoodata arvo. Settings API loistaa silloin, kun asetuksia käyttää joku muu kuin kehittäjä.

Aloita yksinkertaisesti: lisää yksi tekstikenttä yllä olevan esimerkin mukaisesti. Kun hallitset perusprosessin, rekisteröinnin, callbackin, tallennuksen ja tulostuksen, siirry select-kenttiin, kenttäryhmiin ja mukautettuihin asetussivuihin. Ja minkä kenttätyypin kanssa työskentelet useimmiten? Kerro meille kommenteissa.