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.