⌨️ Jak dodać własną sekcję na stronę ustawień WordPress

Standardowe strony ustawień WordPress, „Ogólne", „Czytanie", „Dyskusja", pokrywają podstawowe potrzeby witryny. Jednak gdy tylko piszą Państwo wtyczkę lub dopracowują motyw dla klienta, wbudowany zestaw pól przestaje wystarczać. Potrzebny jest blok z własnymi opcjami: klucz API, tekst w stopce, przełącznik trybu.

Tworzenie osobnej strony w panelu administracyjnym dla dwóch pól to przesada. Znacznie czystszym rozwiązaniem jest dodanie własnej sekcji do już istniejącej strony ustawień, tam, gdzie znajdują się domyślne opcje WordPress. Służy do tego jedna funkcja w Settings API: add_settings_section.

Przeanalizujmy jej składnię, parametry i zbudujmy działający przykład z sekcją i polem, od haka admin_init do wyświetlenia w panelu administracyjnym. Bez zbędnych abstrakcji: tylko to, co Państwo skopiują i uruchomią u siebie.

💡 Szybki przegląd:

• Proszę określić stronę docelową (general, reading, writing, discussion, media lub niestandardową), slug będzie potrzebny w czwartym parametrze
• Proszę zarejestrować sekcję przez add_settings_section() na haku admin_init: proszę podać ID, tytuł i callback dla tekstu objaśniającego
• Proszę powiązać pola z sekcją przez add_settings_field(), a samą opcję zapisać przez register_setting()
• Proszę wywołać do_settings_sections() w callbacku strony dla stron niestandardowych, sekcja wyrenderuje się automatycznie

Czym jest Settings API i dlaczego jest potrzebne

Settings API pojawiło się w WordPress 2.7 i od tego czasu pozostaje standardowym sposobem dodawania ustawień do panelu administracyjnego. Istota jest prosta: zamiast ręcznego wypisywania <form> i przetwarzania $_POST opisują Państwo sekcje i pola za pomocą funkcji, a WordPress sam renderuje znaczniki, obsługuje zapisywanie i sprawdza nonce.

Trzy filary Settings API:

• register_setting(), rejestruje opcję w wp_options;
• add_settings_section(), tworzy blok (sekcję) z tytułem;
• add_settings_field(), dodaje konkretne pole do sekcji.

To właśnie add_settings_section odpowiada za „kontener", wizualny blok, który grupuje kilka pól pod wspólnym tytułem na stronie ustawień. Bez niej pól po prostu nie ma gdzie umieścić.

Składnia add_settings_section

Sygnatura funkcji jest zwięzła, cztery obowiązkowe parametry i jedna opcjonalna tablica:

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

Funkcja nic nie zwraca. Rejestruje sekcję w globalnej tablicy $wp_settings_sections, skąd WordPress pobiera ją podczas wywołania do_settings_sections() na stronie docelowej. Wywołanie add_settings_section bez późniejszego do_settings_sections na stronie niestandardowej sprawi, że sekcja po cichu się nie wyrenderuje.

Ważny niuans: add_settings_section jedynie opisuje blok. Same pola dodaje się osobnymi wywołaniami add_settings_field z podaniem ID sekcji w piątym parametrze. Bez pól sekcja pozostanie pustą obwolutą, czasami jest to potrzebne dla tekstowego objaśnienia, ale w praktyce prawie zawsze towarzyszy jej co najmniej jedno pole.

Parametry funkcji, które należy przekazać

$id (string, obowiązkowy), unikalny slug sekcji. Proszę używać małych liter, cyfr i podkreśleń: my_plugin_main_section. Ten sam ID podadzą Państwo w add_settings_field, aby „powiązać" pole z sekcją, i to on pojawia się w atrybucie HTML id znacznika obwoluty.

$title (string, obowiązkowy), tytuł sekcji widoczny dla administratora. Wyświetlany jako <h2> wewnątrz strony ustawień. Proszę pisać po polsku dla polskiego panelu administracyjnego: «Настройки интеграции с CRM», a nie my_plugin_crm_settings.

$callback (callable, obowiązkowy), nazwa funkcji, która wypisuje przez echo tekst objaśniający między tytułem sekcji a polami. Sygnatura: function my_callback($args), gdzie $args to tablica z kluczami id, title i callback. Jeśli objaśnienie nie jest potrzebne, proszę przekazać '__return_false'.

$page (string, obowiązkowy), slug strony ustawień, do której dodawana jest sekcja. Wbudowane strony WordPress: general, reading, writing, discussion, media. Dla strony niestandardowej, slug przekazany w add_options_page(). ⚠ Strony misc i privacy zostały usunięte z jądra (przestarzałe), WordPress automatycznie przekieruje misc → general, privacy → reading, ale lepiej nie polegać na tym zachowaniu.

$args (array, opcjonalny, od WordPress 6.1.0), tablica do dostosowania HTML-owej obwoluty sekcji:

Argument $args działa tylko podczas wywołania do_settings_sections(). Jeśli omyłkowo użyte zostanie do_settings_fields(), tablica jest ignorowana, a before_section/after_section po cichu nie zadziałają.

Praktyczny przykład: sekcja z polem na stronie „Ogólne"

Zbudujmy gotowy fragment dla functions.php lub własnej wtyczki. Kod dodaje sekcję „Ustawienia wizytówki" na stronie options-general.php z jednym polem tekstowym, na przykład dla numeru telefonu w stopce.

1
/**
2
 * Додає кастомну секцію та поле на сторінку «Загальні».
3
 */
4
function sdstudio_add_visiting_card_section() {
5
    // 1. Секція
6
    add_settings_section(
7
        'visiting_card_section',               // ID секції
8
        'Visiting Card Settings',             // Заголовок
9
        'sdstudio_visiting_card_section_cb',   // Callback-пояснення
10
        'general',                             // Сторінка «Загальні»
11
        array(
12
            'before_section' => '<div class="visiting-card-wrapper">',
13
            'after_section'  => '</div>',
14
        )
15
    );
16
 
17
    // 2. Поле
18
    add_settings_field(
19
        'footer_phone',                        // ID поля
20
        'Footer Phone Number',                    // Лейбл
21
        'sdstudio_footer_phone_field_cb',      // Callback — рендерить <input>
22
        'general',                             // Та сама сторінка
23
        'visiting_card_section'                // До якої секції прив'язати
24
    );
25
 
26
    // 3. Реєстрація опції
27
    register_setting( 'general', 'footer_phone' );
28
}
29
add_action( 'admin_init', 'sdstudio_add_visiting_card_section' );
30
 
31
/**
32
 * Пояснювальний текст над полями секції.
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
 * Рендерить текстове поле вводу.
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
}
52

Po dodaniu kodu proszę wejść do panelu administracyjnego: Ustawienia → Ogólne, pod standardowymi polami pojawi się sekcja „Ustawienia wizytówki" z polem „Telefon w stopce". Po zapisaniu strony wartość zostanie zapisana w wp_options.

Kod umieszcza się w functions.php aktywnego motywu lub, co jest bardziej poprawne, w osobnej wtyczce. Wtyczka przetrwa zmianę motywu, a functions.php nie. Jeśli sekcja jest potrzebna tylko gdy aktywny jest konkretny motyw, functions.php jest dopuszczalny; we wszystkich innych przypadkach, tylko wtyczka.

Argument $args: co zmieniło się w WordPress 6.1

Przed wersją 6.1 add_settings_section miało dokładnie cztery parametry, obwolutę sekcji trzeba było „podkolorowywać" przez CSS po ID lub ingerować w bufor wyjściowy. Począwszy od 6.1 dodano piąty parametr $args i teraz oprawę HTML można zdefiniować bezpośrednio podczas rejestracji sekcji:

• before_section, obwoluta div lub objaśniający baner PRZED zawartością;
• after_section, znacznik zamykający lub podpowiedź PO zawartości;
• section_class, własna klasa, jeśli standardowa form-table nie wystarcza.

Przykład z objaśniającym banerem i niestandardową klasą:

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

Co ważne, należy pamiętać: after_section nie jest wypisywane, jeśli sekcja jest pusta, to znaczy gdy nie ma w niej zarejestrowanych pól. Jeśli liczą Państwo na zamykający </div>, proszę upewnić się, że przez add_settings_field dodano co najmniej jedno pole. I najważniejsze: do_settings_sections(), a nie do_settings_fields(), to drugie całkowicie zignoruje $args.

Przed użyciem before_section / after_section proszę sprawdzić wersję WordPress, na stronach starszych niż 6.1 przekazanie piątego parametru spowoduje błąd krytyczny. Bezpieczne podejście: opakować wywołanie w global $wp_version lub użyć function_exists do sprawdzenia dostępności haków.

⁉️🤔 Często zadawane pytania

Czy można obejść się bez add_settings_section i dodawać pola bezpośrednio?

Formalnie, nie. Pola rejestruje się przez add_settings_field(), a piąty parametr tej funkcji wymaga ID sekcji. Jeśli sekcji nie ma, pole się nie wyrenderuje. Dla pojedynczego pola można utworzyć sekcję z pustym tytułem i callbackiem '__return_false', sekcja będzie niewidoczna, a pole będzie działać.

Czym różni się add_settings_section od add_settings_field?

Sekcja to kontener z tytułem i tekstem objaśniającym. Pole to konkretny element wejściowy (input, select, checkbox) wewnątrz sekcji. Jedna sekcja może zawierać dowolną liczbę pól, wszystkie są grupowane pod jednym tytułem i zapisywane jednym kliknięciem przycisku „Zapisz".

Co się stanie, jeśli w $page poda się slug nieistniejącej strony?

Sekcja zostanie zarejestrowana w $wp_settings_sections, ale nigdy się nie wyrenderuje, WordPress nie wie, na której stronie ma ją wyświetlić. Nie spowoduje to błędu, sekcja po prostu „zawiśnie w powietrzu". Proszę sprawdzać slug: dla wbudowanych stron jest to general / reading / writing / discussion / media; dla niestandardowych, dokładny slug z add_menu_page lub add_options_page.

Czy można dodać sekcję do strony cudzej wtyczki?

Tak, jeśli znają Państwo slug jego strony. Proszę przekazać go w $page, a sekcja pojawi się na cudzej stronie ustawień. Jest to jednak kruche rozwiązanie: autor wtyczki może zmienić slug w aktualizacji i Państwa sekcja „odpadnie". Proszę używać tylko dla własnych projektów lub gdy nie ma alternatyw.

Co robi hak admin_init i dlaczego add_settings_section wywołuje się właśnie na nim?

admin_init uruchamia się przy każdym żądaniu do panelu administracyjnego PRZED renderowaniem strony. To właściwy moment na rejestrację ustawień: sekcje i pola muszą być zadeklarowane zanim WordPress zacznie składać formularz. Jeśli wywoła się add_settings_section później, na przykład wewnątrz callbacku strony, sekcja nie trafi do $wp_settings_sections i nie wyświetli się.

Własna sekcja czy osobna strona: co wybrać

Dodanie sekcji do general jest prostsze: mniej kodu, użytkownik widzi ustawienia tam, gdzie edytuje tytuł witryny. Ale gdy opcji jest więcej niż trzy-cztery, sekcja rozdyma standardową stronę i dezorientuje administratora.

Zasada jest prosta: jedna-dwie opcje, logicznie powiązane ze stroną ogólną (telefon w stopce, klucz API dla komentarzy), to sekcja na general. Trzy i więcej opcji, samodzielna funkcjonalność (slider, integracja z CRM, siatka taryf), to osobna strona przez add_options_page(). W obu przypadkach add_settings_section to ta sama cegiełka, od której zaczyna się budowa.

Zanim Państwo skopiują kod, proszę upewnić się, że WordPress jest zaktualizowany do aktualnej wersji. Tablica $args, section_class oraz obwoluty before_section/after_section wymagają co najmniej 6.1, a sama funkcja żyje w jądrze od wersji 2.7. Dwie dekady kompatybilności wstecznej to nie powód, by siedzieć na przestarzałym silniku.