Tutorial Drupal Paragraphs, część 1: planowanie architektury i typy bazowe

Tutorial Drupal Paragraphs łatwo znaleźć w wersji podstawowej: zainstaluj moduł, utwórz typ, dodaj pole. Trudniej znaleźć wskazówki, jak zbudować spójną bibliotekę komponentów: mały, uniwersalny zestaw typów paragrafów, który redaktorzy lubią, a developerzy mogą utrzymywać przez lata. Właśnie to dostarcza ta seria; część 1 kładzie fundament, czyli planowanie architektury, poprawną konfigurację modułu i budowę pierwszych trzech typów paragrafów z prawdziwym kodem.

Ten przewodnik zakłada wykorzystanie Drupal 10 lub 11 oraz wymaga podstawowej znajomości modułu Drupal Paragraphs. Nie musisz być ekspertem, ale powinieneś swobodnie tworzyć pola i edytować szablony Twig. Jeśli obecna konfiguracja frustruje redaktorów bardziej niż im pomaga, w artykule o Drupal Paragraphs: od bezużytecznej konfiguracji do CMS dla redaktorów opisujemy, co odróżnia zepsute wdrożenie od takiego, które działa na produkcji.

Co zbudujesz w tej serii tutorial Drupal Paragraphs?

Celem nie jest stos jednorazowych sekcji, lecz wszechstronna biblioteka komponentów: mały zestaw typów paragrafów, które razem pokrywają większość stron typowej witryny korporacyjnej. W obu częściach zbudujesz:

• Część 1 (ten artykuł): architekturę, fundament modułu i trzy kluczowe typy paragrafów: Hero, Tekst + obraz oraz Feature Grid.
• Część 2: warianty koloru i stylu, dedykowane układy responsywne, odstępy kontrolowane przez redaktorów, pola warunkowe, UX administracyjny, wydajność i utrzymanie długoterminowe; do tego dochodzą pozostałe typy (CTA, karty, testimonial, FAQ, statystyki).

Przez cały przewodnik obowiązuje zasada wielokrotnego użytku. Dobrze zaprojektowana biblioteka jest mała (10 do 15 klocków wielokrotnego użytku), a mimo to obejmuje wiele układów, bo komponenty są na tyle elastyczne, by łączyć je na różne sposoby. To samo podejście, czyli myślenie komponentami zamiast szablonami stron, opisujemy w artykule Mindset komponentowy: jak nauczyć klientów myślenia komponentami.

Przeczytaj: tworzenie treści w Drupalu: moduł Paragraphs oraz Paragraph View Mode: przegląd modułu dla Drupala.

Jak zaplanować bibliotekę komponentów wielokrotnego użytku?

Zanim zaczniesz instalację i konfigurację, określ, co naprawdę chcesz zbudować. Większość bibliotek komponentów nie przegrywa z powodów technicznych, lecz dlatego, że z czasem zamienia się w zbiór typów paragrafów stworzonych pod pojedyncze strony i jednorazowe potrzeby. Dlatego o wielokrotnym wykorzystaniu komponentów warto myśleć już na etapie planowania.

Zacznij od audytu. Wypisz strony, których potrzebuje typowa witryna korporacyjna: strona główna, produkt lub usługa, o nas, landing page, kontakt, aktualności. Zamiast projektować każdą stronę osobno, rozbij ją na powtarzające się sekcje. Szybko zobaczysz te same wzorce: hero u góry, naprzemienne bloki tekst-obraz, siatka funkcji, wezwanie do działania, karty.

Te powtarzające się wzorce to Twoje komponenty. Solidny minimalny zestaw dla witryny korporacyjnej to:

• Hero: wyraźny baner otwierający stronę z nagłówkiem, podtytułem, obrazem i wezwaniem do działania.
• Tekst + obraz: nagłówek i treść obok obrazu, z obrazem po lewej lub prawej.
• Feature Grid: nagłówek plus zestaw powtarzalnych elementów w konfigurowalnej liczbie kolumn.
• Blok CTA: skupiona sekcja wezwania do działania.
• Karty: rząd linkowanych kart do nawigacji lub wyróżnień.
• Testimonial: cytat z atrybucją.
• FAQ: lista par pytanie-odpowiedź.
• Statystyki / liczby: rząd kluczowych wskaźników.
• Lista treści: dynamiczne zestawienie powiązanych materiałów.
• Formularz kontaktowy: osadzony formularz.

Zakończ planowanie prostą macierzą paragrafów: tabelą mapującą, które typy paragrafów pojawiają się na jakich typach stron. To weryfikuje, czy zestaw jest naprawdę uniwersalny; jeśli jakiś typ występuje tylko na jednej stronie, zastanów się, czy w ogóle powinien trafić do biblioteki.

Jak przygotować fundament Paragraphs?

Mając plan, zainstaluj moduł i ustal konwencje, których będzie przestrzegał każdy typ paragrafu.

Instalacja przez Composer i włączenie:

composer require drupal/paragraphs 

drush en paragraphs -y

Następnie dodaj pole referencji paragraphs do typu treści, który będzie hostował komponenty, zwykle landing page lub podstawowa strona. Typem pola jest Entity reference revisions, którego Paragraphs używa do obsługi wersji:

# field.field.node.landing_page.field_components (illustrative) 

field_name: field_components 

entity_type: node 

bundle: landing_page 

label: 'Components' 

field_type: entity_reference_revisions 

settings: 

  handler: 'default:paragraph'

W widoku formularza pola użyj widgetu Paragraphs (stable) i ustaw „Add mode” na przycisk lub listę rozwijaną, by redaktorzy mieli czytelne menu typów komponentów. Do szybszej codziennej edycji, gdy biblioteka urośnie, pomocny może być Geysir.

Kilka słów o koncepcji „typu bazowego”: Drupal Paragraphs nie wspiera dziedziczenia typów, więc nie ma dosłownego typu bazowego do rozszerzenia. W praktyce „baza” oznacza dwie rzeczy: konwencję nazewnictwa pól stosowaną konsekwentnie we wszystkich typach (np. każdy typ z tytułem używa field_heading, każdy ze stylem używa field_style) oraz, dla ustawień wspólnych dla wielu typów, wtyczkę Paragraphs behavior. Behavior to sposób na dodanie wspólnego ustawienia (wariant stylu lub odstęp) wielu typom naraz; wprowadzamy je w części 2 tej serii tutorial Drupal Paragraphs. Na razie przyjmij konwencję nazewnictwa; spójność zwraca się w każdym szablonie i arkuszu stylów, który napiszesz później.

Ustal strategię pól z góry:

• trzymaj pola wymagane przy minimum, którego komponent naprawdę potrzebuje;
• resztę oznacz jako opcjonalną i projektuj szablony tak, by obsługiwały puste pola;
• używaj spójnych typów i nazw pól między komponentami;
• układaj pola w formularzu według częstotliwości użycia, z najczęściej używanymi na początku.

Jak zbudować pierwsze trzy typy paragrafów Drupal?

Teraz utwórz trzy typy obejmujące kluczowe wzorce: prosty baner (Hero), blok dwukolumnowy (Tekst + obraz) i siatkę powtarzalnych elementów (Feature Grid). Każdy korzysta z tej samej konwencji nazewnictwa pól z kroku fundamentu i używa szablonów Twig, które możesz rozbudowywać wraz z biblioteką.

Paragraf Hero

Utwórz typ paragrafu hero pod adresem /admin/structure/paragraphs_type z polami:

• field_heading: zwykły tekst
• field_subheading: zwykły tekst (opcjonalnie)
• field_image: referencja do mediów (obraz)
• field_cta: link

Następnie dodaj szablon paragraph--hero.html.twig:

{# 

/** 

 * @file 

 * Default theme implementation for the Hero paragraph. 

 */ 

#} 

<section{{ attributes.addClass('paragraph', 'paragraph--hero') }}> 

  <div class="paragraph--hero__media"> 

    {{ content.field_image }} 

  </div> 

  <div class="paragraph--hero__body"> 

    {% if content.field_heading|render|trim %} 

      <h2 class="paragraph--hero__heading">{{ content.field_heading }}</h2> 

    {% endif %} 

    {{ content.field_subheading }} 

    {{ content.field_cta }} 

  </div> 

</section>

Sprawdzenie |render|trim to niewielki detal, który pomaga utrzymać czysty HTML. Dzięki temu szablon nie generuje pustych elementów opakowujących, gdy opcjonalne pole nie zawiera żadnej wartości. Ten sam wzorzec opisujemy w przewodniku o szybkim edytowaniu i dostosowywaniu paragrafu w Drupalu.

Paragraf Tekst + obraz

Utwórz typ paragrafu text_image z polami:

• field_heading: zwykły tekst
• field_body: sformatowany tekst (long)
• field_image: referencja do mediów (obraz)
• field_image_position: lista (text): left, right

Odczytaj pole pozycji jako klasę modyfikatora, by ten sam komponent mógł odwrócić układ:

{% set position = content.field_image_position['#items'].value|default('left') %} 

<section{{ attributes.addClass('paragraph', 'paragraph--text-image', 'paragraph--text-image--' ~ position) }}> 

  <div class="paragraph--text-image__media">{{ content.field_image }}</div> 

  <div class="paragraph--text-image__text"> 

    {% if content.field_heading|render|trim %} 

      <h2>{{ content.field_heading }}</h2> 

    {% endif %} 

    {{ content.field_body }} 

  </div> 

</section>

.paragraph--text-image { 

  display: grid; 

  gap: 2rem; 

  grid-template-columns: 1fr 1fr; 

  align-items: center; 

} 

  

.paragraph--text-image--right .paragraph--text-image__media { 

  order: 2; 

}

Paragraf Feature Grid

Dla powtarzalnych elementów najczystsze podejście to zagnieżdżone paragrafy: typ feature_grid referencjonujący wiele paragrafów feature_item.

Najpierw utwórz typ feature_item z polami field_icon (media), field_heading i field_text. Potem feature_grid z:

• field_heading: zwykły tekst
• field_items: entity reference revisions do feature_item
• field_columns: lista (integer): 2, 3, 4

{% set columns = content.field_columns['#items'].value|default(3) %} 

<section{{ attributes.addClass('paragraph', 'paragraph--feature-grid') }}> 

  {% if content.field_heading|render|trim %} 

    <h2 class="paragraph--feature-grid__heading">{{ content.field_heading }}</h2> 

  {% endif %} 

  <div class="paragraph--feature-grid__items" style="--columns: {{ columns }}"> 

    {{ content.field_items }} 

  </div> 

</section>

.paragraph--feature-grid__items { 

  display: grid; 

  gap: 1.5rem; 

  grid-template-columns: repeat(var(--columns, 3), 1fr); 

}

Zagnieżdżanie paragrafów sprawia, że każdy element feature można edytować osobno, a siatka kontroluje wyłącznie układ; to dokładnie taka separacja odpowiedzialności, jakiej wymaga biblioteka łatwa w utrzymaniu.

Jak przetestować i zweryfikować doświadczenie redaktora?

Zanim przejdziesz dalej, potwierdź, że fundament działa z perspektywy redaktora, a nie tylko Twojej.

Utwórz stronę testową i dodaj do niej wszystkie trzy typy paragrafów. Sprawdź potem trzy rzeczy:

• Edycja. Czy możesz łatwo dodawać, zmieniać kolejność i usuwać paragrafy? Czy menu dodawania jest czytelne?
• Wynik renderowania. Czy wygenerowany HTML ma sensowną strukturę i poprawną hierarchię nagłówków? Czy puste pola opcjonalne nie produkują zbędnego markupu?
• Responsywność. Czy układ trzyma się razem po zwężeniu okna przeglądarki, jeszcze przed dedykowaną pracą responsywną w części 2?

Jeśli już na tym etapie edycja wydaje się nieintuicyjna lub zbyt skomplikowana, problem będzie tylko narastał wraz z rozbudową biblioteki. Znacznie łatwiej dopracować fundament teraz niż porządkować go po dodaniu kolejnych typów paragrafów. W drugiej części serii rozszerzymy bibliotekę o kontrolę odstępów, warianty kolorystyczne i układy responsywne: elementy, które sprawiają, że komponenty są nie tylko elastyczne dla developerów, ale również wygodne w codziennej pracy redaktorów. O tym, dlaczego odstępy zawsze stają się problemem, piszemy w artykule o odstępach w Drupal Paragraphs i lukach w układach.