Ekran personalizacji motywu - kontrolki

Podstawowym elementem, który służy do zarządzania opcjami w ekranie personalizacji motywu jest kontrolka. Może to być pole tekstowe, lista wyboru lub bardziej złożony element jak np. pole wyboru koloru.

WordPress 4.0 wprowadził dużo usprawnień w tym temacie, dzięki czemu tworzenie rozbudowanych opcji stało się dużo wygodniejsze.

Tworzenie kontrolki

Kontrolki tworzymy poprzez metodę add_control, która ma dwa rodzaje wywołań – jedno i dwuargumentowe. Jeżeli korzystamy z podstawowych kontrolek to używamy wywołania z dwoma argumentami:

$wp_customize->add_control(
    'nazwa_ustawienia',
    array(
        'opcja' => 'wartość'
    )
);

Warto pamiętać, że przed stworzeniem kontrolki, powinniśmy najpierw zdefiniować ustawienie metodą add_setting – ustawienie jest ściśle związane z kontrolką poprzez pierwszy argument metody add_control. Tablica asocjacyjna z opcjami określa dodatkowe parametry kontrolki. Przykładowa tablica ustawień:

array(
    'label' => 'Test option',
    'description' => 'Test description',
    'type' => 'text',
    'section' => 'test',
    'priority' => 0
);

Krótki opis poszczególnych parametrów:

label – to etykieta kontrolki,
description – opis kontrolki wyświetlany pod etykietą – dodany w WordPressie 4.0,
type – rodzaj kontrolki,
section – identyfikator sekcji do której zostanie przypisana kontrolka,
priority – parametr służący do określania kolejności kontrolek w sekcji

Teoretycznie możliwe jest wykorzystanie jeszcze innego zapisu metody tworzącej kontrolkę:

$wp_customize->add_control(
    'nazwa_kontrolki',
    array(
        …
        'setting' => 'nazwa_ustawienia',
        …
    )
);

W powyższym wypadku pierwszy argument nie musi być powiązany z nazwą ustawienia – wtedy dowiązanie jest tworzone na bazie parametru setting.

Jeżeli zaś chodzi o jednoargumentowe wywołanie metody add_control, jest ono wykorzystywane przy bardziej złożonych kontrolkach oferowanych przez WordPressa oraz w wypadku tworzenia własnych kontrolek:

$wp_customize->add_control(
    new WP_Customize_Color_Control(
        $wp_customize,
        'text_color',
        array(
            'label' => __('Text Color', 'mytheme'),
            'section' => 'colors'
        )
    )
);

Jedynym argumentem jest w tym wypadku instancja klasy tworzącej kontrolkę, która pobiera trzy argumenty:

obiekt menadżera ekranu personalizacji,
nazwę ustawienia (lub nazwę kontrolki, jeżeli korzystamy z parametru setting),
tablicę asocjacyjną ustawień tak jak w wypadku dwuargumentowego wywołania metody add_control.

Dostępne rodzaje kontrolek

Do naszej dyspozycji mamy następujące typy kontrolek:

text,
textarea,
radio (wymaga ona dodatkowego parametru choices),
select (wymaga ona dodatkowego parametru choices),
checkbox,
dropdown-pages

Dodatkowo z kontrolek, które wykorzystują jednoargumentowe wywołanie metody add_control warto wymienić:

WP_Customize_Color_Control,
WP_Customize_Image_Control,
WP_Customize_Upload_Control,
WP_Customize_Background_Image_Control,
WP_Customize_Header_Image_Control

Jeszcze więcej kontrolek

Jeżeli wcześniej wspomniane kontrolki nam nie wystarczają, to możemy skorzystać z faktu, że od WordPressa 4.0 możemy jako parametr type podać każdą wartość jaka jest obsługiwana przez atrybut type elementu input w HTML5.

Dodatkowo w parametrze input_attrs możemy podać tablicę asocjacyjną dodatkowych atrybutów, których może wymagać dany element:

$wp_customize->add_control(
    'mytheme_layout_width',
    array(
        'type' => 'range',
        …
        'input_attrs' => array(
            'min' => 720,
            'max' => 1280,
            'step' => 1
        )
    )
);

Oczywiście należy pamiętać o tym, że wiele z typów kontrolek ma bardzo ograniczone wsparcie, zatem może się okazać, że w wielu przeglądarkach po prostu nasze kontrolki nie wyświetlą się odpowiednio.

Proste modyfikacje kontrolek

Istniejące kontrolki możemy modyfikować na dwa sposoby – z poziomu PHP oraz poprzez kod CSS/JS.

W wypadku kodu PHP korzystamy z następujących metod:

get_control – pozwala nam modyfikować parametry zadeklarowanej już kontrolki,
remove_control – pozwala nam usunąć daną kontrolkę

Przykładowy kod zmieniający opis kontrolki:

$wp_customize->get_control('test_control')->description = 'New description';

Oraz kod usuwający tą kontrolkę:

$wp_customize->remove_control('test_control');

Dzięki powyższym funkcjom możemy pousuwać zbędne kontrolki dodawane przez WordPressa albo wtyczki lub też np. poprzenosić standardowe kontrolki pomiędzy sekcjami.

W wypadku modyfikacji na poziomie JS/CSS wykorzystujemy akcję customize_controls_enqueue_scripts, która pozwala dodać do ekranu personalizacji własne skrypty JS i style CSS.

Dodatkowo przy okazji modyfikacji kontrolek poprzez kod JS, polecam dodać uprzednio do elementów, które chcemy zmieniać jakieś dodatkowe klasy CSS poprzez argument input_attrs:

array(
    "input_attrs" => array(
        "class" => "js-override"
    )
)

Własne kontrolki?

Oczywiście API ekranu personalizacji dopuszcza tworzenie własnych kontrolek – de facto takowymi są wszystkie kontrolki, które tworzymy poprzez jednoargumentowe wywołanie funkcji add_control. Tworzenie własnych kontrolek to dość złożony temat, dlatego poświęcę mu oddzielny wpis. W tym miejscu chciałbym tylko zauważyć, że warto zastanowić się czy rzeczywiście musimy tworzyć własne kontrolki – sporo możemy osiągnąć modyfikując istniejące kontrolki, a wiele funkcji możemy uzyskać wykorzystując kontekst.

Podsumowanie

Kontrolki to niewątpliwie element ekranu personalizacji na który deweloper motywu może mieć największy wpływ i który też ma największy wpływ na wygodę konfiguracji motywu w WordPressie.

Ekran personalizacji motywu – kontrolki