Ulepszone szablony Drupala. Przegląd modułu Twig Tweak

W przypadku korzystania z dowolnego rozwiązania zwykle natrafiamy na potrzebę tworzenia generycznych funkcji pomocniczych. Podobna sytuacja zachodzi podczas pracy z szablonami w Drupalu 9. Jeśli tworzyłeś/tworzyłaś kiedyś customowy kod, aby wyświetlić blok, widok lub encje w szablonie Drupala 9 i interesuje Cię gotowe i przetestowane rozwiązanie - ten artykuł jest dla Ciebie. Zapoznam Cię bliżej z modułem Twig Tweak, który dostarcza szereg funkcji pomocniczych.

Twig i Drupal

Twig to wydany w 2009 roku silnik szablonów dla języka PHP. Jest on stale rozwijany, na dzień pisania artykułu najnowszą wersją jest 3.4.1. Twig jest integralną częścią frameworka Symfony, a co za tym idzie - również Drupala 9. Drupal implementuje na swój sposób pewne koncepty, takie jak encje, bloki czy widoki. Aby budować końcowy HTML z tak zwanych tablic renderowania (ang. Render arrays), Drupal wykorzystuje wewnętrzne klasy, zaprojektowane w tym celu. Jednak Twig domyślnie nie wie o sposobie ich działania. Z tego powodu natywnie niemożliwe jest, na przykład, wyrenderowanie bloku czy widoku z dowolnymi parametrami w dowolnym miejscu, używając jedynie silnika Twig. Aby umożliwić takie operacje, społeczność Drupala stworzyła moduł Twig Tweak, który wprowadza pokaźną listę rozszerzeń do Twiga, które rozwiązują najbardziej popularne problemy, specyficzne dla Drupala.

Moduł Twig Tweak

Moduł został wydany 3 stycznia 2016 roku, a jego najnowsza aktualizacja pojawiła się 15 kwietnia 2022 roku. Twig Tweak posiada starszą wersję, kompatybilną z Drupalem 8 i 9 oraz nowszą, która wymaga Drupala 9. Z oczywistych względów (czyli użycia Symfony od wersji 8) moduł nie posiada wersji na Drupala 7.

Moduł Twig Tweak dostarcza zbiór rozszerzeń do Twiga, które pozwalają, na przykład, na renderowanie widoków, bloków, regionów, encji, pól, menu, formularzy, tokenów oraz wielu innych. Pełna lista możliwości znajduje się w stworzonej przez autorów ściądze.

Twig Tweak jest aktualnie używany na ponad 100 tysięcy stron internetowych. Najnowsza wersja 3.x zyskuje stałą popularność względem starszej wersji 2.x, która odnotowuje nieznaczne, lecz ciągłe spadki.

 

Źródło: Drupal.org

Twórcą oraz główną osobą, utrzymującą modułu jest użytkownik Chi. Ze względu na popularność modułu, pełna lista osób, które przyczyniły się do jego rozwoju jest zbyt obszerna, żeby ją przytaczać.

Instalacja

Instalacja modułu Twig Tweak przegieba standardowo.

composer require drupal/twig_tweak

drush pm:enable twig_tweak

Moduł nie posiada zależności innych niż Drupal Core, a także nie dostarcza niestandardowych uprawnień.

Dostępna jest jedna opcja konfiguracyjna - twig_tweak_enable_php_filter - którą ustawia się w pliku settings.php. Przyjmuje ona wartość TRUE/FALSE, domyślnie FALSE. Włączenie tej opcji powoduje dodanie możliwości użycia czystego PHP w Twigu. Opcja jest domyślnie wyłączona, prawdopodobnie ze względów bezpieczeństwa.

Jak używać Twig Tweak?

Po instalacji modułu otrzymujemy dostęp do następujących funkcji:

drupal_view

Renderuje podany widok. Przykład: 

{{ drupal_view(‘view_id’, 'view_display_id’) }}

drupal_view_result

Renderuje jedynie rezultat podanego widoku. Przykład:

 {{ drupal_view_result(‘view_id’, 'view_display_id’) }}

drupal_block

Renderuje podany blok. Przykład: 

{# Block with default configuration. #}
{{ drupal_block('block_id') }}

{# Block with custom configuration. #}
{{ drupal_block('block_id', {config_id: 'foo', another_config_id: false}) }}

{# Block without block.html.twig theming. #}
{{ drupal_block('block_id', wrapper=false) }}

drupal_region

Renderuje podany region. Przykład: 

{# Foo region of the default theme. #}
{{ drupal_region(‘foo’) }}

{# Foo region of Bartik theme. #}
{{ drupal_region('foo', 'bartik') }}

Pozostałe funkcje w Twig Tweak

Spójrzmy na inny opcje, dostępne w tym module:

drupal_entity - renderuje encje,

drupal_entity_form - renderuje formularz encji,

drupal_field - renderuje pole,

drupal_menu - renderuje menu,

drupal_form - renderuje formularz,

drupal_image - renderuje obrazek,

drupal_token - zamienia token,

drupal_config - renderuje konfiguracje,

drupal_dump / dd - renderuje czytelną wersję zawartości zmiennej (pomocne w debugowaniu),

drupal_title - renderuje tytuł aktualnej strony,

drupal_url - renderuje URL,

drupal_link - renderuje link,

drupal_messages - renderuje status messages,

drupal_breadcrumb - renderuje breadcrumby,

drupal_breakpoint - triggeruje breakpoint Xdebuga,

drupal_contextual_links - renderuje linki kontekstualne.

Filtry w modułe Twig Tweak

Teraz przyjrzymy się dostępnym w narzędziu filtrom:

token_replace - zamienia token,

preg_replace - umożliwia użycie funkcji preg_replace w Twigu,

image_style - aplikuje określony styl obrazka,

transliterate - transliteruje tekst z Unicode do US-ASCII,

check_markup - filtruje tekst na podstawie określonego w systemie stylu tekstu,

format_size - formatuje podaną liczbę bajtów na znakową reprezentacje z suffixem określającym wielokrotność,

truncate - ogranicza podany tekst do określonej liczby znaków,

view - zwraca render array dla podanej encji lub pola,

with - działa przeciwnie do core’owego filtra without,

children - używany na polach wielokrotnego wyboru, aby otrzymać listę elementów,

file_uri - zwraca URI podanego pliku media,

file_url - umożliwia użycie funkcji file_url w Twigu,

translation - zwraca tłumaczenie podanej encji,

cache_metadata - dokleja cache metadata do printowanego pola,

php - wykonuje podany ciąg znaków jako kod PHP.

Szeroki opis filtrów wraz z przykładami użycia znajduje się w podlinkowanej wyżej ściądze od autorów modułu.

Moduł Twig Tweak - podsumowanie

Moduł Twig Tweak oszczędza czas oraz otwiera programistów na nowe możliwości. Dostarczone filtry oraz funkcje przydają się w codziennej pracy w Twigu. Moduł jest bardzo popularny, wspierany i chętnie polecany przez społeczność. Jako zespół programistów Drupala rekomendujemy instalację i wypróbowanie możliwości, jakie dostarcza moduł Twig Tweak.