Notes ze szkicem szablonu strony internetowej

Layout builder – nowe narzędzie do budowania szablonów w Drupalu 8

27.03.2019

Buduj dynamiczne szablony w Drupalu z poziomu interfejsu użytkownika. Zobacz jak używać modułu Layout Builder z poziomu UI oraz z poziomu kodu.

Layout Builder to nowe narzędzie do budowania szablonów encji w Drupalu 8, który w ostatnim czasie zyskuje na olbrzymiej popularności. Pomimo tego, że wciąż znajduje się on w fazie eksperymentalnej jest coraz chętniej wykorzystywany do budowania layoutów za jego pomocą.

Moduł Layout Builder pojawił się w core Drupala od wersji 8.5 i wciąż przechodzi dosyć spore metamorfozy. Jego podstawowa funkcjonalność pozostaje nadal taka sama – pozwala wygodnie składać layouty stron w trybie UI. Ponadto, umożliwia osadzenie i przeplatanie ze sobą dowolnych elementów w szablonie – pól, widoków, menu czy formularzy.

Instalacja i konfiguracja modułu
Layout Builder

Moduł Layout builder jest dostępny w core Drupala od wersji 8.5 zatem wystarczy go zainstalować.

Zrzut ekranu instalacji modułu

Nie wymaga on żadnej dodatkowe konfiguracji, od razu możemy przejść do jego użycia.
Obecnie (marzec 2019) najnowsza stabilna gałąź Drupala to 8.6.13, na tej gałęzi będziemy bazować wszystkie nasze przykłady.

Uruchomienie Layout Buildera

W związku z tym, że Layout Builder może być wykorzystywany tylko w encjach, zaraz po instalacji, we wszystkich rodzajach encji, w zakładce zarządzania wyświetlaniem (manage display) pojawia nam się możliwość użycia Layout Buildera w miejsce domyślnego managera wyświetlania.

Zrzut ekranu przedstawiający zarządzanie wyświetlaniem encji.

Za pomocą Layout Builder domyślnie tworzymy szablony dla danego typu encji, zatem każda encja danego typu będzie miała identyczny layout. Jednakże możemy skorzystać z dodatkowej opcji:

Zrzut ekranu opcji szablonu.

która pozwala na nadpisywanie przez poszczególne encje domyślnego layout typu encji. Daje nam to nieograniczone możliwości manipulowania wyglądem tylko jednej encji danego typu, przy zachowaniu layout dla pozostałych encji.

Po zapisaniu wybranych opcji, formularz zarządzania wyświetlaniem zmienia wygląd i zostaje wzbogacony o dodatkowy przycisk „Manage layout”.

Zrzut ekranu zarządzania wyświetlaniem po odblokowaniu Layout Buildera.

Należy przy tym zwrócić uwagę, że moduł od wersji 8.6 pozwala na włączanie/wyłączanie Layout Buildera dla danego view moda, w związku z czym view mode „Teaser” pozostaje nietknięty i korzysta ze standardowego mechanizmu Drupala.

Zarządzanie szablonem

Co zatem kryje się pod enigmatycznym przyciskiem „Manage layout”? Przycisk przenosi nas na stronę edycji szablonu, korzystającej ze skórki strony.

Zrzut ekranu strony edycyjnej szablonu.

W trybie tym możemy zarządzać sekcjami oraz blokami w sekcji. Możemy tutaj łatwo zmieniać kolejność sekcji, a także przekładać bloki wewnątrz i pomiędzy sekcjami metodą drag&drop.

Ważne: Wszelkie dokonywane operacje należy zatwierdzać klikając na przycisk „Save Layout”.

Zrzut ekranu opcji zapisu szablonu.

Aby dodać nową sekcję klikamy na przycisk „Add Section”. Następnie z prawej strony pojawią nam się dostępne szablony.

Zrzut ekranu dostępnych szablonów.

Po dokonaniu wyboru dodana zostanie sekcja według szablonu, który wybraliśmy. Taką sekcję możemy wypełnić już poszczególnymi blokami.
Aby to zrobić klikamy na przycisk „Add Block”.

Zrzut ekranu dostępnych elementów do osadzenia.

Do wyboru mamy wiele dostępnych opcji. Poza polami danej encji możemy łatwo osadzić formularz, widok, menu, czy bloki.

Pełnię mocy można uzyskać łącząc Layout Builder z modułem Entity Blocks (entity_block), który pozwala na osadzanie dowolnej encji, w wybranym view modzie jako blok sekcji. W ten sposób możemy łatwo reużywać już stworzone elementy i łatwo osadzać je w dowolnym miejscu w szablonie.

Szablon dla pojedynczej encji

Jak dotąd pracowaliśmy nad layoutem typu encji. A co jeżeli chcielibyśmy, żeby pojedyncza encja wyświetlała się nieco inaczej niż pozostałe, np. z naszym własnym blokiem?
Layout builder rozszerza routing dla encji o dodatkową stronę z argumentem /layout. A zatem edytując np. blok czy node pojawia nam się dodatkowa zakładka layout.

Zrzut ekranu formularza edycji encji.

Podczas wyświetlania noda mamy również dostępne w zakładkach szybkie przejście do edycji layoutu:

Zrzut ekranu zakładek.

Teraz wystarczy już tylko zmodyfikować istniejący domyślny szablon według swoich potrzeb i dokonać zapisu.

Jeżeli kiedykolwiek zaistniałaby potrzeba, aby przywrócić szablon do domyślnego wyglądu, dostępna jest opcja „Revert to defaults”.

Zrzut ekranu przywracania ustawień domyślnych.

Ważne: Jeżeli chociaż raz skorzystaliście z opcji zmiany szablonu dla pojedynczej encji, możliwość wyłączenia Layout Buildera zostanie zablokowana.

Zrzut ekranu formularza zarządzania wyświetlaniem z zablokowaną edycją Layout Buildera.

Dopiero przywrócenie wszystkich zmienionych dotychczas szablonów do domyślne wartości pozwoli nam ponownie zmieniać opcje layoutu.

Layout Builder „pod maską”

Pod względem zarządzania z poziomu interfejsu użytkownika, Layout Builder z pewnością robi wrażenie. Jednakże na co dzień zadania programistyczne, z którymi przychodzi nam się spotykać mogą być nieco bardziej złożone. Jak zatem pracować z Layout Builderem od strony kodu?

Okazuje się, że włączenie i odblokowanie szablonów dla pojedynczej encji jest stosunkowo proste.

Wystarczy załadować dany display:

$entityViewDisplay = \Drupal::entityTypeManager->getStorage('entity_view_display')->load('ENTITY_TYPE.ENTITY_BUNDLE.VIEW_MODE');

Zwróci nam on obiekt typu LayoutBuilderEntityViewDisplay na którym musimy wykonać operacje:

$entityViewDisplay->enableLayoutBuilder();

aby włączyć sam layout builder dla tego view moda. Możemy też dodatkowo ustawić flagę, aby możliwe było tworzenie osobnych szablonów dla pojedynczej encji:

$entityViewDisplay->setOverridable(TRUE);

Całość zapisujemy:

$entityViewDisplay->save();

W rzeczywistości moduł Layout Buildera dodaje do third_part_settings danego typu encji klucz layout_builder z wartościami dla powyższych parametrów (enabled, allow_custom) oraz pod kluczem 'sections' przechowuje domyślny szablon dla tego typu encji.

W przypadku ustawienia flagi setOverridable na TRUE, tworzy on programistycznie nowe pole encji o nazwie maszynowej layout_builder__layout, w którego wartości zapisywany jest zmodyfikowany layout dla tego konkretnego przypadku.

Odrobinę bardziej skomplikowane jest natomiast programistyczne tworzenie sekcji i wypełnienie jej odpowiednią zawartością. Zacznijmy od utworzenia nowej sekcji. Aby tego dokonać tworzy nową instancję klasy \Drupal\layout_builder\Section z parametrem layout_id, który jest identyfikatorem layoutu.

Wskazówka: Layouty definiuje się w plikach *.layouts.yml, domyślne szablony można odnaleźć w module layout_discovery.

Następnie najprostszym sposobem jest dodanie kolejnego elementu do sekcji. W takim przypadku przyjdzie nam z pomocą metoda appendComponent, która w argumencie przyjmuje instancję klasy \Drupal\layout_builder\SectionComponent. Zanim będziemy chcieli utworzyć taki komponent sekcji potrzebujemy:

  • uuid osadzanego elementu,
  • nazwę regionu w sekcji,
  • konfigurację pluginu.

W naszym przykładzie osadzimy przykładowy node za pomocą pluginu dostarczanego przez Entity Blocks, do sekcji jednokolumnowej:

$section = new Section('layout_onecol');

$uuid = $node->uuid();
$region = ‘content’;
$pluginConfiguration = [
  'id' => 'entity_block:node',
  'provider' => 'entity_block',
  'label_display' => FALSE,
  'view_mode' => 'default',
  'entity' => $node->id(),
];
$component = new SectionComponent($uuid, $region, $pluginConfiguration);
$section->appendComponent($component);

Cały czas musimy trzymać w pamięci, że layouty zapisywane są w third_party_settings lub w polu. Dlatego, żeby zapisać naszą sekcję, musimy dokonać zapisu właśnie w jednym z tych miejsc. W naszym przykładzie będzie to pole, a zatem pozostaje nam ustawić wartość i dokonać zapisu:

$entity->layout_builder__layout->setValue($section);
$entity->save();

W ten sposób udało nam się dodać do encji sekcję jednokolumnową i wyświetlić w niej przykładowy node.

Wady i zalety

Poniżej lista kilku wad i zalet, które zaobserwowałem pracując z Layout Builderem:

Zalety:

  • łatwość uruchomienia – moduł jest już w core, nie trzeba wprowadzać nowych typów encji
  • wygodny interfejs z funkcją drag&drop
  • możliwość customizowania dla pojedynczej encji
  • łatwe mieszanie pól z innymi encjami, bez tworzenia dodatkowych pól z referencją
  • możliwość wygodnego osadzania istniejących encji przy wykorzystaniu Entity Blocks

Wady:

  • w miarę rozrostu serwisu (nowych typów encji i możliwych elementów do osadzenia), czas ładowania dostępnych elementów drastycznie spada
  • jak na moduł skupiony na UI, mało intuicyjne dodawanie nowych layoutów – utworzenie w kodzie plików .yml i szablonów
  • przy dużej liczbie elementów w szablonie przeciąganie elementów między sekcjami staje się nieco utrudnione
  • utrudniony dostęp do sekcji w twig, nazwy są suffixowane uuid, stąd ciężko wyrenderować wybraną sekcję

Podsumowanie

Layout Builder wnosi wiele ciekawych możliwości zarządzania szablonami zarówno od strony interfejsu, jak i programistycznie. Czy jest to zatem moduł, który wyprze wszystkie dotychczasowe rozwiązania?
W mojej opinii jest to narzędzie idealne do rozwiązywania problemu szablonów w skali makro. Idealnym wydaje się tworzenie w pierwszej kolejności zamkniętych komponentów przy wykorzystaniu popularnych modułów tj. paragraphs, field group, a następnie budowanie w Layout Builderze gotowych szablonów składających się z tych właśnie komponentów.
Layout Builder jak każdy moduł ma swoje określone zastosowanie. W rozwiązywaniu pewnych problemów spisze się lepiej, a w innych nieco gorzej. Przekonajcie się sami.

Porozmawiajmy o Twoich projektach

Napisz do nas