Obsługa ekranu personalizacji motywu poprzez JavaScript

W poprzednich wpisach pokazywałem obsługę ekranu personalizacji motywu z użyciem PHP – w tym oraz kilku kolejnych wpisach pokażę, że całkiem sporo można osiągnąć także po stronie przeglądarki korzystając z JavaScript.

Wprowadzenie

API dostępne w JavaScript dla ekranu personalizacji motywu jest stale rozbudowywane – ostatnią dużą zmianą wprowadzoną w WordPressie 4.1 były szablony kontrolek tworzone z użyciem szablonów wykorzystywanych przez bibliotekę underscore. Krótko mówiąc niektóre kontrolki są teraz generowane na bazie szablonu dla języka JavaScript – dzięki temu możliwe jest np. ponowne wygenerowanie kodu kontrolki w locie z uwzględnieniem zmian wartości jej opcji. Zanim jednak przejdziemy do tak wyszukanych zagadnień, musimy zapoznać się z podstawami API. Po tym wpisie możecie się spodziewać serii krótszych i dłuższych wpisów poświęconych praktycznym przykładom wykorzystania JavaScriptowej części API ekranu personalizacji motywu.

Podstawy

Wszystkie kolekcje i metody API ekranu personalizacji motywu zawarte są w obiekcie wp.customize. Wielu developerów dla wygody tworzy na początku zmienną api aby skrócić późniejszy kod:

var api = wp.customize;

W wypadku gdy odwołujemy się do API z poziomu ramki wyświetlającej podgląd motywu należy odwoływać się do obiektu parent.wp.customize.

Kod możemy dodać poprzez akcję customize_preview_init lub customize_controls_enqueue_scripts.

Kolekcja kontrolek znajduje się w obiekcie wp.customize.control, natomiast kolekcja ustawień znajduje się bezpośrednio w obiekcie wp.customize. Sekcje można znaleźć w kolekcji wp.customize.section a panele w kolekcji wp.customize.panel. Każdy z elementów kolekcji jest instancją klasy Values, która posiada kilka użytecznych metod z których najbardziej przydatne to:

• add(id, value) – dodaje obiekt kolekcji o określonym identyfikatorze i wartości
• each(callback, context) – iteruje po wszystkich elementach kolekcji wykonując wybraną funkcję
• has(id) – sprawdza czy istnieje element kolekcji o danym identyfikatorze
• instance(id) – zwraca element kolekcji o zadanym identyfikatorze (choć wystarczy wywołać kolekcję jako metodę aby uzyskać ten sam efekt: wp.customize.control(id))
• remove(id) – usuwa element kolekcji o zadanym identyfkatorze

Modyfikowanie elementów

Elementy ekranu personalizacji można modyfikować poprzez wiele metod – poniżej lista najbardziej przydatnych:

• expand() – rozwija panel/sekcję
• collapse() – zwija panel/sekcję
• toggle() – pozwala zmienić stan aktywności danego elementu
• activate() – aktywuje element
• deactivate() – dezaktywuje element
• focus() – przewija panel boczny do danego elementu
• priority() – pobiera/zmienia kolejność elementów
• active() – zwraca stan aktywności danego elementu
• panel() – zwraca nazwę panelu do którego należy dany element
• section() – zwraca nazwę sekcji do której należy dany element
• renderContent() – generuje na nowo strukturę HTML elementu (o ile dany element jest generowany z użyciem szablonów w JS – na razie są to tylko bardziej złożone kontrolki wyboru plików, koloru i własne kontrolki użytkowników)
• ready() – wyświetla wyrenderowany element (należy użyć po renderContent).

Dodatkowo elementy w polu params przechowują ustawienia takie jak etykieta czy opis:

• params.label
• params.description

Innym wartym uwagi polem elementów jest container – zawiera on uchwyt do elementu przechowującego kontrolkę/panel/sekcję. Dzięki temu możemy zmodyfikować elementy, których nie możemy modyfikować poprzez zmianę parametrów oraz wywołanie metody renderContent.

Akcje podglądu

Poprzez obiekt wp.customize.previewer możemy wykonywać takie akcje jak:

• odświeżenie podglądu – metoda refresh(),
• zapisanie ustawień – metoda save()

Kilka prostych przykładów

Otworzenie sekcji „Kolory”:

wp.customize.section("colors").expand();

Zmiana kolejności elementów:

wp.customize.control("blogname").priority(100);

Przeniesienie kontrolki do innej sekcji:

wp.customize.control("blogname").section("colors");

Zmiana nazwy kontrolki i odświeżenie jej struktury na bazie szablonu:

var ctrl = wp.customize.control("background_color");
ctrl.params.label = "New label";
ctrl.renderContent();
ctrl.ready();

Podsumowanie

Obecne API w JavaScript dla ekranu personalizacji motywu posiada już naprawdę szerokie możliwości i może być wykorzystane do znaczącego wzbogacenia możliwości konfiguracji motywu.