⌨️ Kuidas lisada oma jaotis WordPressi seadete lehele

Standard WordPressi seadete lehed, „General", „Reading", „Discussion", katavad saidi põhivajadused. Kuid niipea, kui kirjutate kliendile plugina või kohandate teemat, ei piisa enam sisseehitatud väljade komplektist. Teil on vaja plokki oma valikutega: API võti, jaluse tekst, režiimilüliti.

Eraldi admin-lehe loomine vaid kahe välja jaoks on liialdus. Palju puhtam on lisada oma sektsioon olemasolevale seadete lehele, just sinna, kus asuvad WordPressi vaikimisi valikud. Settings API pakub selleks ühte funktsiooni: add_settings_section.

Vaatame läbi selle süntaksi, parameetrid ja loome töötava näite koos sektsiooni ja väljaga, alates admin_init konksust kuni väljundini admin-paneelis. Ei mingeid tarbetuid abstraktsioone: ainult see, mida saate ise kopeerida ja käivitada.

💡 Kiirülevaade:

• Määratlege sihtleht (general, reading, writing, discussion, media või kohandatud), selle nimetust läheb vaja neljandas parameetris
• Registreerige sektsioon add_settings_section() abil admin_init konksul: andke ID, pealkiri ja tagasikutse kirjeldava teksti jaoks
• Kinnitage väljad sektsiooni külge add_settings_field() abil ja salvestage valik ise register_setting() abil
• Kutsuge kohandatud lehtede lehe tagasikutses välja do_settings_sections(), sektsioon renderdatakse automaatselt

Mis on Settings API ja miks seda vaja on

Settings API ilmus WordPress 2.7-s ja on sellest ajast alates olnud standardne viis admin-paneelile seadete lisamiseks. Idee on lihtne: selle asemel, et käsitsi <form> väljastada ja $_POST käsitleda, kirjeldate sektsioone ja välju funktsioonide kaudu ning WordPress ise renderdab märgendi, tegeleb salvestamisega ja kontrollib nonce'i.

Settings API kolm tugisammast:

• register_setting(), registreerib valiku wp_options tabelis;
• add_settings_section(), loob ploki (sektsiooni) koos pealkirjaga;
• add_settings_field(), lisab konkreetse välja sektsiooni.

Just add_settings_section vastutab „konteineri" eest, visuaalse ploki eest, mis rühmitab mitu välja ühise pealkirja alla seadete lehel. Ilma selleta pole välju lihtsalt kuhugi panna.

Add_settings_section süntaks

Funktsiooni signatuur on lakooniline, neli kohustuslikku parameetrit ja üks valikuline massiiv:

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

Funktsioon ei tagasta midagi. See registreerib sektsiooni globaalses $wp_settings_sections massiivis, kust WordPress selle hangib, kui sihtlehel kutsutakse välja do_settings_sections(). Kui kutsute add_settings_section ilma järgneva do_settings_sections'ita kohandatud lehel, siis sektsiooni vaikimisi ei renderdata.

Oluline nüanss: add_settings_section ainult kirjeldab plokki. Väljad ise lisatakse eraldi add_settings_field väljakutsetega, määrates viiendas parameetris sektsiooni ID. Ilma väljadeta jääb sektsioon tühjaks ümbriseks, mis on mõnikord kasulik tekstilise selgituse jaoks, kuid praktikas paigutatakse selle kõrvale peaaegu alati vähemalt üks väli.

Funktsiooni parameetrid, mida edastada

$id (string, kohustuslik), sektsiooni unikaalne nimetus. Kasutage väiketähti, numbreid ja alakriipse: my_plugin_main_section. Sama ID määrate ka add_settings_field'is, et väli sektsiooni külge „kinnitada", ning see ilmub ka ümbrise HTML-sildi id atribuudis.

$title (string, kohustuslik), sektsiooni pealkiri, mida administraator näeb. See väljastatakse seadete lehel <h2> elemendina. Kirjutage see adminile arusaadavas keeles: «Настройки интеграции с CRM», mitte my_plugin_crm_settings.

$callback (callable, kohustuslik), funktsiooni nimi, mis väljastab kirjeldava teksti sektsiooni pealkirja ja väljade vahel. Signatuur: function my_callback($args), kus $args on massiiv võtmetega id, title ja callback. Kui selgitust pole vaja, edastage '__return_false'.

$page (string, kohustuslik), seadete lehe nimetus, kuhu sektsioon lisatakse. WordPressi sisseehitatud lehed: general, reading, writing, discussion, media. Kohandatud lehe puhul nimetus, mis edastati add_options_page()'ile. ⚠ misc ja privacy lehed on tuumikust eemaldatud (iganenud), WordPress suunab automaatselt misc → general, privacy → reading, kuid parem on sellele käitumisele mitte loota.

$args (massiiv, valikuline, alates WordPress 6.1.0), massiiv sektsiooni HTML-ümbrise kohandamiseks:

$args argument töötab ainult siis, kui kutsutakse välja do_settings_sections(). Kui ekslikult kasutatakse do_settings_fields(), ignoreeritakse massiivi ning before_section/after_section ei avalda vaikimisi mingit mõju.

Praktiline näide: sektsioon väljaga lehel „General"

Paneme kokku kasutusvalmis näidise faili functions.php või teie enda plugina jaoks. Kood lisab lehele options-general.php sektsiooni „Visiitkaardi saidi seaded" koos ühe tekstiväljaga, näiteks telefoninumbri jaoks jaluses.

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
}

Pärast koodi lisamist minge admin-paneeli: Settings → General ja standardväljade all näete sektsiooni „Visiitkaardi saidi seaded" koos väljaga „Jaluse telefoninumber". Salvestage leht ja väärtus kirjutatakse wp_options tabelisse.

Kood paigutatakse aktiivse teema functions.php faili või, õigemini, eraldi pluginasse. Plugin elab üle teemavahetuse, functions.php aga mitte. Kui sektsiooni on vaja ainult konkreetse teema aktiivsuse ajal, on functions.php vastuvõetav; kõigil muudel juhtudel ainult plugin.

$Args argument: mis muutus WordPress 6.1-s

Enne versiooni 6.1 oli add_settings_section'il täpselt neli parameetrit ja sektsiooni ümbrist tuli „viimistleda" CSS-i abil ID järgi või sirutuda väljundpuhvri järele. Alates 6.1-st lisati viies parameeter $args ja nüüd määratakse HTML-raamistus otse sektsiooni registreerimisel:

• before_section, div-ümbris või selgitav bänner ENNE sisu;
• after_section, sulgev silt või vihje PÄRAST sisu;
• section_class, kohandatud klass, kui standardsest form-table'ist ei piisa.

Näide koos selgitava bänneri ja kohandatud klassiga:

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

Mida on oluline meeles pidada: after_section ei väljastata, kui sektsioon on tühi, st kui selles pole registreeritud välju. Kui arvestate sulgeva </div>'iga, veenduge, et add_settings_field abil on lisatud vähemalt üks väli. Ja mis kõige tähtsam: kasutage do_settings_sections(), mitte do_settings_fields(), kuna viimane ignoreerib $args'i täielikult.

Enne before_section / after_section kasutamist kontrollige WordPressi versiooni, saitidel, mis on vanemad kui 6.1, põhjustab viienda parameetri edastamine fataalse vea. Ohutu lähenemine: mähkige väljakutse global $wp_version kontrolli või kasutage function_exists, et kontrollida konksude olemasolu.

⁉️🤔 Korduma kippuvad küsimused

Kas ma saan add_settings_section vahele jätta ja väljad otse lisada?

Formaalselt ei. Väljad registreeritakse add_settings_field() kaudu ja selle funktsiooni viies parameeter nõuab sektsiooni ID-d. Kui sektsiooni ei eksisteeri, siis väli ei renderdu. Üksiku välja jaoks võite luua sektsiooni tühja pealkirja ja '__return_false' tagasikutsega, sektsioon on nähtamatu ja väli töötab.

Mis vahe on add_settings_section ja add_settings_field vahel?

Sektsioon on konteiner koos pealkirja ja kirjeldava tekstiga. Väli on konkreetne sisendelement (input, select, checkbox) sektsiooni sees. Üks sektsioon võib sisaldada suvalist arvu välju, mis kõik on rühmitatud ühe pealkirja alla ja salvestatakse ühe „Salvesta" nupu klõpsuga.

Mis juhtub, kui määran parameetris $page olematu lehe nimetuse?

Sektsioon registreeritakse $wp_settings_sections'is, kuid ei renderdu kunagi, kuna WordPress ei tea, millisel lehel seda väljastada. Viga ei teki, sektsioon lihtsalt „jääb õhku rippuma". Kontrollige nimetust: sisseehitatud lehtede puhul on see general / reading / writing / discussion / media; kohandatud lehtede puhul täpne nimetus funktsioonist add_menu_page või add_options_page.

Kas ma saan lisada sektsiooni mõne teise plugina lehele?

Jah, kui teate selle lehe nimetust. Edastage see parameetris $page ja sektsioon ilmub teise plugina seadete lehele. Kuid see on habras lahendus: plugina autor võib uuenduses nimetust muuta ja teie sektsioon „kukub ära". Kasutage seda ainult oma projektide puhul või kui alternatiive pole.

Mida admin_init konks teeb ja miks kutsutakse add_settings_section sellel välja?

admin_init käivitub igal admin-paneeli päringul ENNE lehe renderdamist. See on õige hetk seadete registreerimiseks: sektsioonid ja väljad tuleb deklareerida enne, kui WordPress alustab vormi kokkupanekut. Kui kutsute add_settings_section hiljem, näiteks lehe tagasikutse sees, ei jõua sektsioon $wp_settings_sections'isse ja seda ei kuvata.

Teie enda sektsioon või eraldi leht, mida valida

Sektsiooni lisamine lehele general on lihtsam: vähem koodi ja kasutaja näeb seadeid samas kohas, kus ta muudab saidi pealkirja. Kuid kui valikuid on rohkem kui kolm või neli, paisutab sektsioon standardlehe üle ja ajab administraatori segadusse.

Reegel on lihtne: üks või kaks valikut, mis on loogiliselt seotud üldise lehega (jaluse telefoninumber, API võti kommentaaride jaoks), kasutage sektsiooni lehel general. Kolm või enam valikut, iseseisev funktsionaalsus (liugur, CRM integratsioon, hinnakujunduse tabel), kasutage eraldi lehte add_options_page() kaudu. Mõlemal juhul on add_settings_section just see ehituskivi, millest koostamine algab.

Enne koodi kopeerimist veenduge, et WordPress on uuendatud uusimale versioonile. $args massiiv, section_class ja before_section/after_section ümbrised nõuavad vähemalt versiooni 6.1, samas kui funktsioon ise on tuumikus elanud alates versioonist 2.7. Kaks aastakümmet tagasiühilduvust ei ole põhjus istuda aegunud mootori otsas.