Drupal Paragraphs Tutorial, Teil 1: Architektur planen und Basistypen

Dies ist Teil 1 einer zweiteiligen Anleitung zum Aufbau einer komponentenbasierten Unternehmenswebsite mit Drupal Paragraphs. Am Ende der Serie haben Sie eine Bibliothek aus 10-12 universellen Paragraph-Typen mit Stilvarianten, responsiven Layouts und redakteursfreundlichen Abstandssteuerungen.

Ein Drupal Paragraphs Tutorial findet man leicht für die Grundlagen - Modul installieren, Typ anlegen, Feld hinzufügen. Schwerer zu finden ist eine Anleitung zum Aufbau einer kohärenten Komponentenbibliothek: ein kleines, universelles Set aus Paragraph-Typen, das Redakteure gerne nutzen und Entwickler jahrelang warten können. Genau das liefert diese Serie; Teil 1 legt das Fundament: Architektur planen, das Modul korrekt einrichten und die ersten drei Paragraph-Typen mit echtem Code bauen.

Diese Anleitung setzt Drupal 10 oder 11 und Grundkenntnisse des Drupal Paragraphs Moduls voraus. Sie müssen kein Experte sein - aber Sie sollten mit dem Anlegen von Feldern und dem Bearbeiten von Twig-Templates vertraut sein. Wenn Ihre aktuelle Konfiguration Redakteure eher frustriert als unterstützt, erklärt unser Beitrag Drupal Paragraphs: von unbrauchbar zu redakteursfreundlich, was eine defekte Implementierung von einer trennt, die in der Produktion funktioniert.

In diesem Artikel:

• Was bauen Sie in dieser Drupal Paragraphs Tutorial-Serie?
• Wie planen Sie eine wiederverwendbare Komponentenbibliothek?
• Wie richten Sie das Paragraphs-Fundament ein?
• Wie bauen Sie Ihre ersten drei Drupal-Paragraph-Typen?
• Wie testen und validieren Sie die Redakteurserfahrung?

Was bauen Sie in dieser Drupal Paragraphs Tutorial-Serie?

Das Ziel ist kein Haufen einmaliger Sektionen, sondern eine vielseitige Komponentenbibliothek - ein kleines Set aus Paragraph-Typen, das die meisten Seiten einer Unternehmenswebsite abdeckt. Über beide Teile hinweg bauen Sie:

• Teil 1 (dieser Artikel): die Architektur, das Modulfundament und drei Kern-Paragraph-Typen - Hero, Text + Bild und Feature Grid.
• Teil 2: Farb- und Stilvarianten, dedizierte responsive Layouts, redaktionell steuerbare Abstände, bedingte Felder, Admin-UX, Performance und langfristige Wartung - plus die restlichen Typen (CTA, Cards, Testimonial, FAQ, Stats).

Das Leitprinzip ist Wiederverwendbarkeit. Eine gut designte Bibliothek ist klein - 10 bis 15 wiederverwendbare Bausteine - und deckt dennoch viele Layouts ab, weil die Komponenten vielseitig genug sind, um sich unterschiedlich zu kombinieren. Diese Denkweise - in Komponenten statt in Seitenvorlagen - ist derselbe Wandel, den wir in Kunden das Komponentendenken beibringen beschreiben.

Lesen Sie auch: flexible und einfache Inhaltserstellung mit dem Drupal Paragraphs Modul und Paragraph View Mode - Modul-Review für Drupal.

Wie planen Sie eine wiederverwendbare Komponentenbibliothek?

Bevor Sie etwas installieren, entscheiden Sie, was Sie wirklich brauchen. Komponentenbibliotheken scheitern, wenn sie zu einem Friedhof seiten-spezifischer Typen werden - planen Sie Wiederverwendung von Anfang an.

Beginnen Sie mit einem Audit. Listen Sie die Seiten auf, die eine typische Unternehmenswebsite braucht: Startseite, Produkt- oder Service-Seiten, Über uns, Landingpages, Kontakt, News. Statt jede Seite zu designen, zerlegen Sie sie in wiederkehrende Sektionen. Schnell erkennen Sie wiederkehrende Muster - ein Hero oben, abwechselnde Text-Bild-Blöcke, ein Feature-Grid, ein Call-to-Action, Karten.

Diese Muster sind Ihre Komponenten. Ein solides Minimum für eine Unternehmenswebsite:

• Hero - ein prominenter Seitenöffner mit Überschrift, Unterüberschrift, Bild und Call-to-Action.
• Text + Bild - Überschrift und Text neben einem Bild, links oder rechts positioniert.
• Feature Grid - Überschrift plus wiederholbare Elemente in konfigurierbarer Spaltenanzahl.
• CTA-Block - eine fokussierte Call-to-Action-Sektion.
• Cards - eine Reihe verlinkter Karten für Navigation oder Highlights.
• Testimonial - Zitat mit Attribution.
• FAQ - Liste aus Frage-Antwort-Paaren.
• Stats / Numbers - eine Reihe zentraler Kennzahlen.
• Content List - dynamische Auflistung verwandter Inhalte.
• Contact Form - eingebettetes Formular.

Schließen Sie die Planung mit einer einfachen Paragraph-Matrix ab: eine Tabelle, die Paragraph-Typen den Seitentypen zuordnet. So prüfen Sie, ob Ihr Set wirklich universell ist - erscheint ein Typ nur auf einer Seite, gehört er vermutlich nicht in die Bibliothek.

Wie richten Sie das Paragraphs-Fundament ein?

Mit dem Plan installieren Sie das Modul und legen Konventionen fest, die jeder Paragraph-Typ befolgt.

Installation via Composer und Aktivierung:

composer require drupal/paragraphs
drush en paragraphs -y

Als Nächstes fügen Sie ein Paragraphs-Referenzfeld zum Content Type hinzu, der Ihre Komponenten hostet - typischerweise ein Landingpage- oder Basic-Page-Content-Type. Der Feldtyp ist Entity reference revisions, den Paragraphs für Revisionen nutzt:

# field.field.node.landing_page.field_components (illustrativ)
field_name: field_components
entity_type: node
bundle: landing_page
label: 'Components'
field_type: entity_reference_revisions
settings:
  handler: 'default:paragraph'

In der Formularanzeige des Felds nutzen Sie das Widget Paragraphs (stable) und setzen den „Add mode“ auf Button oder Dropdown, damit Redakteure ein klares Komponentenmenü erhalten. Für schnellere tägliche Bearbeitung kann Geysir die Admin-Erfahrung verbessern, sobald die Bibliothek wächst.

Zum „Basistyp“-Konzept: Drupal Paragraphs unterstützt keine Typvererbung, es gibt also keinen literalen Basistyp zum Erweitern. In der Praxis bedeutet „Basis“ zwei Dinge - eine Feldnamenskonvention, die über alle Typen konsistent gilt (z. B. nutzt jeder Typ mit Titel field_heading, jeder mit Stil field_style), und für wirklich übergreifende Einstellungen ein Paragraphs Behavior Plugin. Behaviors sind der Weg, eine gemeinsame Einstellung (Stilvariante oder Abstand) vielen Typen auf einmal hinzuzufügen; wir führen sie in Teil 2 dieser Drupal Paragraphs Tutorial-Serie ein. Adoptieren Sie vorerst die Namenskonvention - Konsistenz zahlt sich in jedem Template und Stylesheet aus.

Legen Sie Ihre Feldstrategie von Anfang an fest:

• halten Sie Pflichtfelder auf das Minimum, das eine Komponente wirklich braucht;
• machen Sie alles andere optional und designen Sie Templates für leere Felder;
• nutzen Sie konsistente Feldtypen und Namen über Komponenten hinweg;
• ordnen Sie Felder im Formular nach Nutzungshäufigkeit - am häufigsten zuerst.

Wie bauen Sie Ihre ersten drei Drupal-Paragraph-Typen?

Erstellen Sie nun drei Typen, die die Kernmuster abdecken: ein einfaches Banner (Hero), ein zweispaltiger Block (Text + Bild) und ein Grid mit wiederholbaren Elementen (Feature Grid). Jeder folgt derselben Feldnamenskonvention aus dem Fundament-Schritt und nutzt Twig-Templates, die Sie mitwachsen lassen können.

Der Hero-Paragraph

Legen Sie einen Paragraph-Typ hero unter /admin/structure/paragraphs_type mit diesen Feldern an:

• field_heading - Plain Text
• field_subheading - Plain Text (optional)
• field_image - Media-Referenz (Bild)
• field_cta - Link

Dann fügen Sie ein Template hinzu, 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>

Die |render|trim-Prüfung ist eine kleine, aber wichtige Gewohnheit: Sie verhindert leeres Wrapper-Markup, wenn ein optionales Feld leer bleibt. Dasselbe Muster finden Sie in unserem Leitfaden zum schnellen Bearbeiten und Anpassen eines Drupal-Paragraphs.

Der Text + Bild-Paragraph

Erstellen Sie einen Paragraph-Typ text_image mit:

• field_heading - Plain Text
• field_body - formatierter Text (long)
• field_image - Media-Referenz (Bild)
• field_image_position - Liste (Text): left, right

Lesen Sie das Positionsfeld als Modifier-Klasse, damit dieselbe Komponente ihr Layout spiegeln kann:

{% 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;
}

Der Feature-Grid-Paragraph

Für wiederholbare Elemente ist der saubere Ansatz verschachtelte Paragraphs: ein feature_grid-Typ, der viele feature_item-Paragraphs referenziert.

Erstellen Sie zuerst einen feature_item-Typ mit field_icon (Media), field_heading und field_text. Dann feature_grid mit:

• field_heading - Plain Text
• field_items - Entity reference revisions zu feature_item
• field_columns - Liste (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);
}

Verschachtelte Paragraphs halten jedes Feature-Item unabhängig editierbar, während das Grid nur das Layout steuert - genau die Trennung, die eine wartbare Bibliothek braucht.

Wie testen und validieren Sie die Redakteurserfahrung?

Bevor Sie weitergehen, beweisen Sie, dass das Fundament aus der Redakteursperspektive funktioniert - nicht nur aus Ihrer.

Erstellen Sie eine Testseite und fügen Sie alle drei Paragraph-Typen hinzu. Prüfen Sie dann drei Dinge:

• Bearbeitung. Können Sie Paragraphs einfach hinzufügen, umsortieren und entfernen? Ist das Hinzufügen-Menü klar?
• Output. Hat das gerenderte HTML eine sinnvolle Struktur und korrekte Heading-Hierarchie? Erzeugen leere optionale Felder kein überflüssiges Markup?
• Responsivität. Hält das Layout zusammen, wenn Sie den Viewport verengen - auch vor der dedizierten Responsive-Arbeit in Teil 2?

Fühlt sich die Bearbeitung jetzt umständlich an, wird es mit zehn Typen nur schlimmer. Das Fundament hier zu reparieren ist deutlich günstiger als später. Teil 2 dieser Serie ergänzt Abstandssteuerungen, Farbvarianten und responsive Layouts - die Features, die eine starre Bibliothek in eine verwandeln, der Redakteure auf echten Seiten vertrauen. Für einen Deep Dive, warum Abstände immer zum Problem werden, siehe Drupal Paragraphs Abstände und Layout-Lücken.

Möchten Sie eine komponentenbasierte Drupal-Website mit Paragraphs bauen?

Dieses Drupal Paragraphs Tutorial basiert auf Mustern aus produktiven Unternehmens-Neuaufbauten - eine kleine universelle Bibliothek planen, Feldnamenskonventionen durchsetzen und die Redakteurserfahrung beweisen, bevor die Bibliothek wächst. Die drei Typen, die Sie hier gebaut haben (Hero, Text + Bild, Feature Grid), sind dasselbe Fundament, das wir in Teil 2 mit Varianten, Abständen und Admin-UX erweitern.

Sie bauen eine komponentenbasierte Drupal-Website und wollen erfahrene Hände an der Architektur? Unser Team designt und baut täglich redakteursfreundliche Paragraphs-Systeme - von Twig-Templates und verschachtelten Paragraph-Typen bis zu Abstandssteuerungen und langfristiger Wartung. Besuchen Sie unsere Drupal-Agentur, um zu sehen, wie wir helfen können.