Własne opcje w WordPress Customizer dodasz przez hook customize_register. Potrzebujesz trzech elementów: sekcji, ustawienia oraz kontrolki. Sekcja porządkuje opcję w panelu, ustawienie zapisuje jej wartość, a kontrolka udostępnia pole do edycji.
Dlaczego warto korzystać z Customizer API?
Customizer jest natywnym narzędziem WordPressa do konfiguracji motywu. Dodanie prostego pola bezpośrednio w kodzie nie wymaga instalowania rozbudowanego page buildera ani dodatkowego frameworka. Mniejsza liczba zależności zwykle oznacza prostszą konserwację i mniejszy narzut dla motywu.
Customizer API pozwala tworzyć między innymi pola tekstowe, pola wyboru, selektory kolorów i checkboxy. Wartości zapisane przez użytkownika można później pobrać w plikach szablonu.
Jak zbudowana jest hierarchia Customizera?
Każda własna opcja składa się z trzech powiązanych elementów. Ich kolejność ma znaczenie, ponieważ kontrolka musi wskazywać istniejące ustawienie, a ustawienie powinno należeć do konkretnej sekcji:
- Sekcja – kontener widoczny w menu Customizera, który grupuje powiązane opcje.
- Ustawienie – wartość konfiguracyjna zapisywana przez WordPress, na przykład tekst, kolor albo liczba.
- Kontrolka – element interfejsu, taki jak pole tekstowe, checkbox lub próbnik koloru.
W praktyce stosujesz więc schemat add_section(), następnie add_setting(), a na końcu add_control(). Sama kontrolka nie zadziała bez przypisanego ustawienia i sekcji.
Jak dodać własną opcję do Customizera?
Poniższy przykład dodaje sekcję „Ustawienia nagłówka” oraz pole tekstowe na krótkie hasło wyświetlane w motywie. Kod możesz umieścić w pliku functions.php aktywnego motywu potomnego. Przy większym projekcie podobną funkcję można przenieść do dedykowanej wtyczki.
- Zarejestruj hook
customize_register– WordPress wywołuje go podczas budowania panelu Customizera. - Dodaj sekcję – określ jej identyfikator, tytuł i priorytet.
- Dodaj ustawienie – zdefiniuj domyślną wartość oraz funkcję sanitizującą.
- Dodaj kontrolkę – połącz pole tekstowe z ustawieniem i sekcją.
<?php
/**
* Dodaje własną opcję do WordPress Customizer.
*
* @param WP_Customize_Manager $wp_customize Obiekt zarządzający Customizerem.
*/
function moja_motywowa_konfiguracja( $wp_customize ) {
// 1. Dodanie sekcji w panelu Customizera.
$wp_customize->add_section(
'moja_sekcja_naglowka',
array(
'title' => __( 'Ustawienia nagłówka', 'moja-motywowa' ),
'description' => __( 'Konfiguracja tekstu nagłówka.', 'moja-motywowa' ),
'priority' => 30,
)
);
// 2. Dodanie ustawienia zapisywanego przez WordPress.
$wp_customize->add_setting(
'moja_motywowa_haslo',
array(
'default' => '',
'sanitize_callback' => 'sanitize_text_field',
'transport' => 'refresh',
)
);
// 3. Dodanie kontrolki pola tekstowego.
$wp_customize->add_control(
'moja_motywowa_haslo',
array(
'label' => __( 'Hasło nagłówka', 'moja-motywowa' ),
'description' => __( 'Wpisz tekst wyświetlany w nagłówku.', 'moja-motywowa' ),
'section' => 'moja_sekcja_naglowka',
'type' => 'text',
)
);
}
add_action( 'customize_register', 'moja_motywowa_konfiguracja' );
Najważniejsze jest spójne ID ustawienia. W przykładzie moja_motywowa_haslo występuje zarówno przy add_setting(), jak i przy add_control(). Jeśli wpiszesz inne identyfikatory, kontrolka nie będzie zapisywać oczekiwanej wartości.
Jak wyświetlić wartość w motywie?
Zapisane ustawienie pobierzesz funkcją get_theme_mod(). Pierwszy argument to ID ustawienia, a drugi – wartość domyślna używana wtedy, gdy użytkownik niczego jeszcze nie zapisał.
<?php
$haslo_naglowka = get_theme_mod( 'moja_motywowa_haslo', 'Witaj na naszej stronie' );
echo '<p class="header-slogan">' . esc_html( $haslo_naglowka ) . '</p>';
?>
Taki fragment możesz umieścić na przykład w header.php. Funkcja esc_html() zabezpiecza tekst przed wstawieniem niebezpiecznego kodu HTML. Gdy wartość ma trafić do atrybutu HTML, użyj esc_attr().
Na co uważać przy własnych opcjach?
Sanityzację definiuj już podczas rejestrowania ustawienia. Dla zwykłego tekstu sprawdzi się sanitize_text_field, dla liczby całkowitej absint, a dla adresu URL esc_url_raw. Funkcja powinna odpowiadać rodzajowi danych, które użytkownik może wpisać.
Stosuj własny prefiks w ID sekcji i ustawień, na przykład moja_motywowa_. Ogranicza to ryzyko konfliktu z motywem, wtyczką albo innym fragmentem kodu. Sprawdź też, czy kontrolka wskazuje właściwą sekcję, a po zapisaniu zmian odczytujesz dokładnie to samo ID za pomocą get_theme_mod().
Jeżeli opcja nie zapisuje się, najczęściej przyczyną jest literówka w identyfikatorze, brak funkcji podpiętej do customize_register albo nieprawidłowe umieszczenie kodu w pliku motywu. Po poprawnym zarejestrowaniu sekcji, ustawienia i kontrolki nowe pole powinno pojawić się w panelu Wygląd → Dostosuj.
Customizer API opiera się na prostym łańcuchu: sekcja porządkuje panel, ustawienie przechowuje wartość, a kontrolka pozwala ją zmienić. Po zapisaniu konfiguracji pobierasz dane przez get_theme_mod(), pamiętając o sanitizacji podczas zapisu i escapowaniu przy wyświetlaniu.
