Obraz tytułowy: KIRKI – biblioteka, która rozbuduje Twój motyw WordPress

KIRKI – biblioteka, która rozbuduje Twój motyw WordPress

Zapewne każdy twórca motywów na platformę WordPress miał styczność z Customizer API. Podejrzewam, że pierwszą wzmiankę o tym rozwiązaniu Web Developerzy znajdują w chwili kiedy zbudują swój pierwszy motyw na tę platformę i przychodzi moment kiedy pasowałoby pozwolić użytkownikowi końcowemu na swobodną edycję treści, czy w małym stopniu wyglądu motywu.

Część twórców motywów w tym celu implementuje Settings API, czyli w praktyce tworzy dodatkową kartę ustawień w ramach panelu i stopniowo „zapina” węzły z niej do motywu. Jest to rozwiązanie w dużym stopniu zaspokajające potrzeby użytkownika, aby np. dodać linki do mediów społecznościowych, zmienić ułożenie bloków na stronie głównej itd.

To rozwiązanie może być wystarczające, ale WordPress pozwala nam na edycję treści na żywo. Zupełnie bez użycia jakiegokolwiek Visual Buildera jak Elementor, czy Visual Composer. Customizer API jest rozwiązaniem, z którym mamy kontakt już na samym początku przygody z WordPressem. Wchodząc do zakładki Wygląd > Dostosuj naszym oczom pojawi się nasza strona z panelem umożliwiającym dopasowanie niektórych opcji motywu witryny. Z reguły są to zdublowane rzeczy z innych ustawień strony internetowej, ale możemy widzieć na żywo wprowadzone zmiany. Rewelacja prawda?

Domyślnie Customizer API nie wspiera niestety wielu ciekawych rozwiązań. Pozwala na co najwyżej dodanie: pól wyboru koloru, edycję CSS, pól tekstowych i checkboxów.

Tutaj pojawia się biblioteka Kirki. Warto nadmienić na początku, że jest rozwijana na zasadach open source na licencji MIT. Biblioteka wprowadza m.in. :

  • Kirki udostępnia nam blisko 32 nowe pola.
  • Umożliwia wygodne tworzenie paneli i sekcji
  • Pozwala powielać pola i tworzyć z nich tablice.
  • Umożliwia walidację wprowadzanych danych
  • Pozwala na tworzenie podstawowej logiki w celu pokazywania, lub chowania wybranych pól

Dzięki funkcjonalności wymienionej powyżej nasz motyw stanie się przystępniejszy i wygodniejszy w obsłudze dla naszego klienta. W większości przypadków pozwoli zrezygnować z wdrażania jakichkolwiek Visual Builderów.

Implementacja biblioteki KIRKI w motywie

Zasadniczo mamy dwie drogi. Każda ma swoje plusy i minusy. Możemy wdrożyć bibliotekę:

  • Jako wtyczkę w WordPressie.
  • Bezpośrednio zaimplementować w motywie

Obierając drogę instalacji biblioteki w formie wtyczki zyskujemy bezpośredni dostęp do bieżących aktualizacji. Moim zdaniem lepszą drogą jest implementacja bezpośrednio w motywie, ponieważ niweluje możliwość usunięcia/wyłączenia jej przez roztargnionego klienta, dlatego też poniżej opiszę tą drugą metodę.

Pobieranie biblioteki

Przechodzimy na stronę projektu kirki.org, a dokładniej do zakładki Download i pobieramy paczkę. Musimy podać swoje imię oraz adres email, ale możemy oczywiście skorzystać z tymczasowego maila jak Temp Mail.

Wdrożenie biblioteki do motywu

Tworzymy katalog includes i wklejamy do niego pobrany folder. W moim przypadku ścieżka to /includes/kirki.

Przechodzimy do pliku functions.php i deklarujemy naszą bibliotekę.

include_once( dirname( __FILE__ ) . '/includes/kirki/kirki.php' );

function mytheme_kirki_configuration() {
    return array( 'url_path'     => get_stylesheet_directory_uri() . '/includes/kirki/' );
}
add_filter( 'kirki/config', 'mytheme_kirki_configuration' );

Gotowe od tego momentu możemy dodawać panele, sekcje oraz pola wymienione w dokumentacji KIRKI: https://kirki.org/docs/controls/

Zanim przejdziemy dalej rozjaśnię relacje jakie mają między sobą panele, sekcja oraz pola.

  • Panel – jest kontenerem zbiorczym na sekcje. Wyświetla się bezpośrednio w zakładce Dostosuj.
  • Sekcja – rozdziela pola w ramach panelu.
  • Pola – przypisujemy je do sekcji. Pozwalają nam wprowadzać dane.

Jako przykład mogę podać taki scenariusz. Mamy panel o nazwie „Mój Motyw” w ramach którego deklarujemy sekcje „Linki do Social Media”, „Kolor”, „Zdjęcie w tle”. Do sekcji Kolor dodajemy pole color-palette, które pozwoli wybrać użytkownikowi dowolny kolor.

Deklaracja pól

Stwórzmy panel zbiorczy w ramach którego wyświetlimy dwie sekcje: Social Media oraz Dane Kontaktowe. W sekcji Social Media będą znajdować się linki do mediów społecznościowych, a w Dane Kontaktowe dokładne dane firmy. W tym celu deklarujemy w pliku functions.php nasz panel.

Kirki::add_panel( 'mainpanel_id', array(
    'priority'    => 10,
    'title'       => esc_html__( 'Panel Zbiorczy', 'kirki' ),
    'description' => esc_html__( 'Ten panel pozwoli Ci na dopasowanie wielu ustawień Twojego motywu.', 'kirki' ),
) );

Rozjaśnijmy sobie parametry.

  • mainpanel_id – w tym miejscu podajemy unikatowy identyfikator panelu. Za jego pomocą będziemy przypisywać sekcje do niego.
  • priority – określa pozycję naszego panelu w ramach menu.
  • title – tytuł panelu
  • description – opis

Zwróć uwagę, że tytuł oraz opis jest deklarowany w taki sposób, aby umożliwić tłumaczenie nazw i opisów przy użyciu wtyczek jak Polylang.

Teraz zadeklarujmy dwie sekcje do panelu.

Kirki::add_section( 'social_id', array(
    'title'          => esc_html__( 'Media Społecznościowe', 'kirki' ),
    'description'    => esc_html__( 'Podaj linki do profili na mediach społecznościowych', 'kirki' ),
    'panel'          => 'mainpanel_id',
    'priority'       => 160,
) );

Kirki::add_section( 'contact_id', array(
    'title'          => esc_html__( 'Dane kontaktowe', 'kirki' ),
    'description'    => esc_html__( 'Podaj swoje dane kontaktowe. Wyświetlają się w kilku miejscach.', 'kirki' ),
    'panel'          => 'mainpanel_id',
    'priority'       => 150,
) );

Przyjrzyjmy się bliżej parametrom. Opiszę tylko te, które wymagają rozjaśnienia.

  • social_id oraz contact_id to unikatowe identyfikatory sekcji, do których przypiszemy pola.
  • panel – tutaj deklarujemy nasz panel, do którego zostaną przypisane nasze sekcje.

Dobra to teraz czas na deklarację pól. Do sekcji Social Media przypiszemy trzy pola typu link (opis w dokumentacji TUTAJ), a do Dane Kontaktowe trzy pola typu text (opis w dokumentacji TUTAJ).

Nasza deklaracja pól do sekcji Social Media wygląda następująco:

Kirki::add_field( 'theme_config_id', [
	'type'     => 'link',
	'settings' => 'facebook_link',
	'label'    => __( 'Facebook', 'kirki' ),
	'section'  => 'social_id',
	'default'  => 'https://www.facebook.com/profil',
	'priority' => 10,
] );
Kirki::add_field( 'theme_config_id', [
	'type'     => 'link',
	'settings' => 'instagram_link',
	'label'    => __( 'Instagram', 'kirki' ),
	'section'  => 'social_id',
	'default'  => 'https://www.instagram.com/profil',
	'priority' => 10,
] );
Kirki::add_field( 'theme_config_id', [
	'type'     => 'link',
	'settings' => 'youtube_link',
	'label'    => __( 'YouTube', 'kirki' ),
	'section'  => 'social_id',
	'default'  => 'https://www.youtube.com/channel/123',
	'priority' => 10,
] );

Z kolei deklaracji pól do Danych Kontaktowych wygląda tak:

Kirki::add_field( 'theme_config_id', [
	'type'     => 'text',
	'settings' => 'companynname_setting',
	'label'    => esc_html__( 'Nazwa firmy', 'kirki' ),
	'section'  => 'contact_id',
	'default'  => esc_html__( 'Moja firma sp.z o.o.', 'kirki' ),
	'priority' => 10,
] );

Kirki::add_field( 'theme_config_id', [
	'type'     => 'text',
	'settings' => 'email_setting',
	'label'    => esc_html__( 'Adres email', 'kirki' ),
	'section'  => 'contact_id',
	'default'  => esc_html__( 'info@moja-firma.pl', 'kirki' ),
	'priority' => 20,
] );

Kirki::add_field( 'theme_config_id', [
	'type'     => 'text',
	'settings' => 'phone_settings',
	'label'    => esc_html__( 'Numer kontaktowy', 'kirki' ),
	'section'  => 'contact_id',
	'default'  => esc_html__( '123-123-123', 'kirki' ),
	'priority' => 30,
] );

Znaczenie parametrów:

  • type określa typ pola w naszym przypadku to link
  • settings – unikalny identyfikator pola, do którego będziemy się odwoływać, aby wyświetlić dane.
  • label – etykieta pola
  • section – podajemy identyfikator sekcji do której przypisujemy pole
  • default – domyślna zawartość pola

Gotowe! Jeśli wszystko poszło zgodnie z planem w zakładce Dostosuj znajdziemy nasz panel, sekcje oraz pola.

Nasz panel
Zawartość panelu
Zawartość sekcji Media Społecznościowe
Zawartość sekcji Dane Kontaktowe

Prezentacja danych w motywie

Jest to niezwykle proste. Aby zaprezentować dane prostych pól jakie zadeklarowaliśmy wykorzystujemy funkcję get_theme_mod() i podajemy w parametrze identyfikator pola. Aby wyświetlić przykładowo pola z sekcji Dane Kontaktowe robimy to następująco:

<!-- Pokaże nazwę firmy -->
<?php echo get_theme_mod('companynname_setting'); ?>
<!-- Pokaże link z adresem email -->
<a href="mailto:<?php echo get_theme_mod('email_setting'); ?>"><?php echo get_theme_mod('email_setting'); ?></a>
<!-- Pokaże link z numerem telefonu -->
<a href="tel:<?php echo get_theme_mod('phone_settings'); ?>"><?php echo get_theme_mod('phone_settings'); ?></a>

Analogicznie robimy z polami Social Media.

W tym miejscu chciałbym cię ostrzec przed drobnym problemem. Parametry default w polach wyświetlają swoją zawartość wyłącznie w zakładce Dostosuj. Aby dane pojawiły się na naszej stronie musimy kliknąć przycisk Zapisz zmiany. Jeśli chcemy się ustrzec przed pojawianiem się pustych linków, czy bloków tekstu możemy zadeklarować domyślną wartość w formie parametru w funkcji get_theme_mod().

Przykładowo dla pola Nazwa firmy zrobimy to następująco:

echo get_theme_mod( 'companynname_setting', 'Twoja domyślna nazwa firmy sp.z o.o.' );

Dodanie możliwości tłumaczenia pól dodanych w ramach Customizer API

Jest to rzecz mniej oczywista na pierwszy rzut oka, ale warto mieć na uwadze, że wykorzystując wtyczkę Polylang możemy pozwolić na dopasowanie zawartości pól w zależności od wersji językowej strony. Na Githubie użytkownik Soderlind utworzył projekt, który umożliwia realizację tego zadania. Repozytorium znajduje się tutaj: https://github.com/soderlind/customizer-polylang.

Implementacja rozwiązania jest banalnie prosta. Z repozytorium pobieramy plik customizer-polylang.php oraz z katalogu js, plik customizer-polylang.js. Ważne jest to, aby plik customizer-polylang.js znajdował się w folderze o nazwie „js”. Możemy zmienić oczywiście jego ścieżkę w pliku customizer-polylang.php dokładnie w linijce 246. Plik z rozszerzeniem .php dodajemy na najwyższym poziomie w motywie i deklarujemy go na samym początku w pliku functions.php:

require_once get_stylesheet_directory() . '/customizer-polylang.php';

Aby wszystko działało poprawnie, musimy spełnić kilka wymagań:

  1. Wtyczka Polylang musi być zainstalowana i włączona
  2. Musimy mieć w ramach niej zadeklarowane języki, których chcemy używać.
  3. Jeśli nasza strona główna jest statyczna (stworzona np. przy użyciu pliku front-page.php) musimy utworzyć kilka stron głównych dla każdej wersji językowej, a następnie powiązać je z konkretnymi wersjami językowymi. Robimy to zgodnie z informacjami z dokumentacji Polylang: https://polylang.pro/doc/define-your-home-page-as-a-static-page/

Jeśli wszystko poszło zgodnie z planem to w zakładce Wygląd>Dostosuj w lewym górnym rogu znajdziemy przełącznik wersji językowej jak poniżej:

Podsumowanie

Biblioteka KIRKI jak sam widzisz jest całkiem potężnym narzędziem, które ułatwi Twoją pracę, bez zmuszania Cię do robienia fikołków w celu umożliwienia użytkownikowi swobodnej edycji treści. Mam nadzieję, że podane przeze mnie przykłady pozwolą Ci płynniej rozpocząć pracę z tą biblioteką. Zachęcam Cię do poznania na własną rękę wszystkich rodzajów pól oferowanych przez KIRKI. Skup się szczególnie na polu reapeter. Dzięki niemu będziesz mógł dodać powtarzalne grupy pól, które przydadzą Ci się np. przy tworzeniu slajdera.

Źródła:
https://github.com/soderlind/customizer-polylang
https://kirki.org/