SDC: Integration von Storybook & Einzelverzeichnis-Komponente

Heute sprechen wir über Drupal Single Directory Components (SDC) und Storybook. Single Directory Components in Drupal ermöglichen es Ihnen, Ihre UI-Komponenten zu organisieren, während Storybook Ihnen die Interaktion mit ihnen ermöglicht. Ihre Integration verändert Ihren Entwicklungsprozess und schafft eine wegweisende Methode zum Erstellen und Testen von UI-Komponenten. 

Und die Veröffentlichung von Drupal 11 bringt eine stabilisierte Version der Drupal Single Directory Components.  

Denken Sie einen Moment darüber nach - 

Stellen Sie sich eine Lösung vor, die Website-UI-Komponenten übersichtlich, für verschiedene Projekte wiederverwendbar, auf allen Webseiten einheitlich halten und noch weitere Vorteile bieten kann.

SDC (Single Directory Components) ist eine Schlüsselfunktion in Drupal 10.1 und Drupal 11, die all dies ermöglicht.

In diesem Blogbeitrag werden wir erörtern, wie die Integration von SDC und Storybook Ihnen helfen kann, schneller zu entwickeln und effizienter zu arbeiten. 

Wenn Sie von Ihrem aktuellen Content-Management-System zu Drupal wechseln möchten, werfen Sie einen Blick auf unsere Migrationsdienste, bevor wir fortfahren.

Jetzt zu Drupal migrieren! 

Legen wir los! 

Was ist SDC? 

SDC war einst ein beigesteuertes Modul, ist aber seit der Veröffentlichung von Drupal Version 11 Teil des Cores und stabiler. SDC oder Single Directory Components bietet eine neue Methode zur Strukturierung und Organisation von Komponenten. SDC ist die Art und Weise, wie Drupal Komponenten verwendet. 

SDC verbessert Ihre Drupal-Themes für einen moderneren Stil. Diese Komponenten umfassen HTML-, CSS- und JavaScript-Code, was die Anpassung und Verwendung auf verschiedenen Seiten oder Anwendungen vereinfacht. 

Alle für eine Komponente benötigten Dateien befinden sich in einem einzigen Verzeichnis. 

Aber was genau sind Komponenten? 

Im Kontext von Single Directory Components (SDC) in Drupal beziehen sich Komponenten auf modulare, wiederverwendbare Bausteine, die alle zur Darstellung eines bestimmten UI-Elements erforderlichen Ressourcen kapseln. SDC organisiert Templates, Stile, Skripte und Metadaten in einem einzigen Verzeichnis für jede Komponente, was ein kohärenteres und wartbareres Entwicklungserlebnis bietet. 

Mit SDC können Entwickler austauschbare und modulare Komponenten entwerfen, wodurch ihr Code flexibler und wiederverwendbarer wird. Komponenten helfen bei der Organisation, Wiederverwendung, Konsistenz, Skalierung, beim Testen und bei der Zusammenarbeit. Diese Konfiguration erleichtert die Integration mit Tools wie Storybook.

Das Verzeichnis eines SDC enthält diese Dateien:

1. Eine YAML-Datei mit Metadaten, die Drupal bei der Identifizierung der Komponente unterstützen. 

2. Eine Twig-Datei mit den Templates. 

3. Eine CSS-Datei mit den Stilen. 

4. Eine JavaScript-Datei mit den Skripten. 

Eine Komponente kann auch einen Screenshot, eine PHP-Datei (mit Hooks und Alters), Medien (wie Bilder, Audio oder Video) oder andere verwandte Elemente enthalten, dies ist jedoch optional. 

Zuverlässigere und einfachere Frontends, die leicht zu aktualisieren sind?

Ja, bitte! 

Lesen Sie auch: 

1. Drupal 11: Elf Änderungen & Updates in Drupal 11 

2. DrupalCon Barcelona: Rückblick 2024 aus Europa 

3. Drupal 7 End of Life: Die wichtigsten Gründe, warum Sie zu Drupal 10 migrieren sollten 

4. RFP: Wie erstellt man eine RFP für Open-Source-Lösungen? 

Was ist Storybook? 

Storybook ist ein Tool, das Entwicklern und Designern hilft, alle ihre Komponenten an einem Ort anzuzeigen und zu testen, bevor sie diese auf der eigentlichen Website verwenden. Es ist fantastisch, weil es Open Source, weit verbreitet und mit einer benutzerfreundlichen Oberfläche ausgestattet ist, was es ideal für moderne Entwicklungs-Workflows macht!

Sie können Komponenten einzeln erstellen und testen. Dies bestätigt, dass sie vor der Integration unabhängig voneinander funktionieren. Es bietet einen visuellen Leitfaden zu den Komponenten, der es einfach macht, zu sehen und zu verstehen, wie jede Komponente funktioniert.  

Storybook bietet ein einfacheres Dateilayout als verschiedene Alternativen, verwendet Webpack und ist mit einer Vielzahl von Frontend-Technologien kompatibel. Es kann sich leicht an individuelle Bedürfnisse anpassen. Storybook ist eines der führenden Designsysteme, die heute mit Drupal verwendet werden.

In Storybook sind Atome, Moleküle und Organismen Komponenten, die das Atomic Design System bilden. 

• Atome: Grundlegende UI-Elemente wie Schaltflächen, Eingabefelder, Beschriftungen und Ãœberschriften. 
• Moleküle: Dies sind fortgeschrittenere UI-Komponenten, die aus Atomen gebildet werden, wie ein Suchfeld in Kombination mit einer Absende-Schaltfläche. 
• Organismen: Dies sind größere UI-Komponenten, die aus Molekülen gebildet werden, wie eine Produktliste, ein Header oder Formulare. 

OpenSense Labs gehört zu den nur 100 Organisationen weltweit, die als Drupal Association Certified Partner anerkannt sind. Wenn Sie Ihre Drupal 7-Website migrieren möchten, sehen Sie sich noch heute unsere Dienstleistungen an.

Jetzt zu Drupal 10 migrieren! 

Warum sollten Sie SDC mit Storybook in Drupal integrieren? 

Die Integration von SDC mit Storybook in Drupal bietet viele Vorteile. Sie lädt Komponenten automatisch, was den Prozess der Erstellung und Verwaltung von Stories mit minimalem Aufwand vereinfacht. Die SDC Storybook-Integrationen bieten einzigartige Vorteile, die Tools wie der SDC Styleguide und Drupal Storybook allein nicht bieten können.  

Werfen wir einen Blick auf einige dieser Vorteile:  

1. Komponenten funktionieren separat und lassen sich leicht integrieren 

Eine Komponente kann in verschiedenen Umgebungen eigenständig funktionieren, unter Verwendung der BEM-Methode (Block Element Modifier). Eine Komponente kann unabhängig von der verwendeten Drupal-Version oder dem Theme eigenständig funktionieren. Sie ist mit allen Systemen kompatibel. 

2. Einfache Drupal-Einrichtung erforderlich 

Sie können Komponenten entwickeln, ohne Drupal-Abhängigkeiten installieren oder einrichten zu müssen. Sie können Frontend-Komponenten in Storybook erstellen, um Ihre Arbeit zu beschleunigen, ohne eine große Drupal-Einrichtung ausführen zu müssen. Dies beschleunigt die Entwicklung und stellt sicher, dass alles reibungslos funktioniert. 

3. Vereinfacht DevOps- und CI/CD-Pipelines 

Separate Komponenten vereinfachen das Testen und die Bereitstellung. Sie können Drupal-spezifische Integrationen in CI-Pipelines überspringen, Ihre Workflows optimieren und einfacher verwalten. Es hält Komponenten organisiert und erleichtert die Verwaltung von JavaScript- und CSS-Dateien, Templates und Datenflüssen innerhalb von Komponenten.

4. Einsatz von Faker.js und JSON Schema für Skalierbarkeit und Anpassungsfähigkeit 

Mit Tools wie Faker.js können Sie Testdaten für Komponenten erstellen, ohne tatsächliche Inhalte zu verwenden. JSON Schema definiert Komponentendaten klar und konsistent, was zur Wahrung der Datenintegrität beiträgt. Sie können Komponenten einzeln testen und anzeigen, was die Verwaltung und Erweiterung von UI-Komponenten erleichtert.

5. Weit verbreitetes Tool für die Frontend-Entwicklung 

Storybook wird häufig in der Frontend-Entwicklung eingesetzt, was neuen Entwicklern den Einstieg erleichtert, auch wenn sie mit Drupal nicht vertraut sind. Mit JSON Schema können Entwickler Komponenten erstellen, ohne viel über Drupal wissen zu müssen, was es mehr Entwicklern erleichtert, am Projekt teilzunehmen.

6. Drupal-bezogene Funktionen in Komponenten integriert 

Integrieren Sie Drupal-Verhaltensweisen, wie [Drupal.attachBehaviors()], direkt in Storybook-Vorschauen. Dies stellt sicher, dass die Komponenten sowohl in Storybook als auch in der Live-Umgebung konsistent funktionieren. Integriert drupalSettings und once.js, um sicherzustellen, dass Storybook-Komponenten wie die in Drupal funktionieren.

Voraussetzungen für die Integration von SDC mit Storybook 

Sie müssen mindestens Drupal Version 10.1 oder die neueste Drupal 11 verwenden, um SDC nutzen zu können. Einige erste Schritte sind erforderlich, bevor Sie mit der Erstellung und Integration von Komponenten mit Storybook beginnen können.  

1. Stellen Sie sicher, dass Sie eine aktuelle Version von Node.js auf Ihrem Computer haben. Wir empfehlen die Verwendung des nvm-Tools zur Verwaltung von Node-Versionen, aber Sie können jede Methode verwenden, die Sie normalerweise bevorzugen, um Node zu installieren.

2. Richten Sie eine lokale Umgebung für Ihre Drupal-Website ein. Storybook verbindet sich mit Drupal, um die einzelnen Komponenten anzuzeigen, daher muss Drupal laufen und zugänglich sein.

Lesen Sie auch: 

1. 7 schnelle Schritte zur Erstellung von API-Dokumentation mit Postman 

2. Was ist der Product Engineering Life Cycle? 

3. Drupal's Omnichannel-Fähigkeiten: Verbesserung der Kundenbindung und des Kundenerlebnisses 

4. Die Bedeutung des Erlernens von Soft Skills: Eine Reise der Selbstfindung 

Wie integriert man SDC mit Storybook in Drupal 11? 

Die Einrichtung von Storybook mit Drupal 11 ist einfach. Sie müssen lediglich SDC erstellen, aktivieren und die erforderlichen Abhängigkeiten installieren. Entwickler können SDC einfach mit Storybook verbinden, indem sie bestimmte Schritte befolgen. Sie können Tools wie Twig und Webpack5 verwenden, um die Templating- und Rendering-Prozesse ihrer Komponenten zu verbessern. 

Schritt 1: SDC einrichten 

Aktivieren Sie das SDC-Kernmodul. Es ist standardmäßig in Drupal 10.1 und späteren Versionen enthalten. 

Schritt 2: CORS-Einstellungen zur Konfiguration von Storybook 
 

Erstellen Sie einen .storybook-Ordner im Projekt-Root-Verzeichnis 

Erstellen Sie zwei Dateien: main.js und preview.js

Installieren und aktivieren Sie das Storybook-Modul oder das CL Server-Modul

Nach der Installation dieses Moduls verbinden Sie es mit Drupal über die Datei development.services.yml

Einrichtung von development.service.yml 

parameters:
  http.response.debug_cacheability_headers: true
  cl_server.development: true
  cors.config:
    enabled: true
    allowedHeaders:
      ["Origin", "X-Requested-With", "Content-Type", "Accept", "*"]
    allowedMethods: ["*"]
    allowedOrigins: ["*"]
    exposedHeaders: false
    maxAge: false
    supportsCredentials: false
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory

Danach in der Datei settings.php diesen Code auskommentieren 

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

UND kopieren Sie example.settings.local.php und fügen Sie es in den Ordner sites/default ein und benennen Sie es in settings.local.php um

 

<?php

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

/**
* Show all error messages, with backtrace information.
*
* In case the error level could not be fetched from the database, as for
* example the database connection failed, we rely only on this value.
*/
$config['system.logging']['error_level'] = 'verbose';

/**
* Disable CSS and JS aggregation.
*/
$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;


$settings['rebuild_access'] = TRUE;


$settings['skip_permissions_hardening'] = TRUE;

Schritt 3: Package.json-Datei im Lando-Root-Ordner für Storybook erstellen und Storybook installieren 

Erstellen Sie den Ordner package.json im Root-Ordner und fügen Sie diesen Code hinzu

  

{
"name": "drupalstorybook",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "storybook": "storybook dev -p 6006",
  "build-storybook": "storybook build"
},
"author": "Opensense",
"license": "ISC",
"devDependencies": {
  "@lullabot/storybook-drupal-addon": "^2.0.1",
  "@storybook/addon-essentials": "^7.4.1",
  "@storybook/addon-links": "^7.4.1",
  "@storybook/blocks": "^7.4.1",
  "@storybook/server": "^7.4.1",
  "@storybook/server-webpack5": "^7.4.1",
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "storybook": "^7.4.1"
}
}

Danach npm install ausführen oder, falls Sie yarn verwenden, yarn install ausführen [Node Version 20 verwenden] 

Führen Sie nun für Storybook den Befehl aus 

yarn storybook oder, falls Sie npm verwenden, npm run storybook 

Hinweis: Für die neueste Storybook-Version prüfen Sie bitte die aktuelle Version von Storybook, fügen Sie sie in package.json hinzu und führen Sie npm oder yarn Install aus 

Zum Generieren von Stories ohne automatisches JSON-Format: 

drush storybook:generate-all-stories 

watch --color drush storybook:generate-all-stories 

Falls auf Mac (brew mit watch) 

Schritt 4: Stories für Komponenten erstellen  
 
Erstellen Sie Stories für jede SDC-Komponente, um deren Funktionen und Variationen zu demonstrieren. Verwenden Sie Twig-Dateien, um das Layout und die Details jeder Komponenten-Story einzurichten. Stellen Sie außerdem sicher, dass jede Story klar zeigt, wie die Komponente aussieht und funktioniert. 

Schauen wir uns ein Beispiel an:

Unten sehen Sie eine Beispiel-Dateistruktur für die Entwicklung einer SDC-Komponente, die die Storybook-Integration beinhaltet. Die Komponente hier ist 'hero'.

 

Hier haben wir uns für eine Methode entschieden, die sich auf atomare Komponenten konzentriert. Wir haben die Hero-Komponente unter den Atomen hinzugefügt.  

Hinweis: Es ist wichtig, SDC-Komponenten im Ordner components/ zu halten. 

Hier sind die Codebeispiele für die obige Komponente:  

1. hero.component.yml

$schema: https://git.drupalcode.org/project/drupal/-/raw/10.1.x/core/modules/sdc/src/metadata.schema.json
name: Hero
description: Hero with title, text, and image
status: experimental
slots:
  body: {}
  media_image: {}
props:
  type: object
  properties:
    heading:
      title: Heading
      description: The title for the hero text.
      examples:
        - You Are My Hero
      type: string
    bodyText:
      title: Hero body text
      type: string
      examples:
        - hello lorum ipsum
    Image_Inverse:
      label: "inverse"
      type: boolean
    mediaImage:
      title: Media Image
      description: Media image for the hero.
      type: string

2. hero.css 

Wir können eine SCSS-Datei erstellen und diese dann in eine CSS-Datei kompilieren. Hier ist die Methode, dies in einer gulp.js-Datei zu tun:  

gulp.src([‘.components/**/*.scss’]).pipe(gulpSass()).pipe(gulp.dest([‘./components’])) 

 

.c-hero {
  background-color:var(--black);
  margin:0 -50vw;
  width:100vw;
  position:relative;
  left:50%;
  right:50%;
  overflow:hidden;
}

@media (width >= 1024px) {
  .c-hero__wrap {
    display:flex;
    align-items:center
  }
}

.c-hero__content-wrap {
  padding:1.25rem 1.875rem 1.25rem 1.25rem;
}

@media (width >= 1024px) {
  .c-hero__content-wrap {
    padding:1.875rem 2.5rem 1.875rem 3.125rem;
    width:40%
  }
}

3. hero.stories.yml 

title: Components/SDC/Organisms/Hero
argTypes:
  Image_Inverse:
    defaultValue: ""
    control: boolean
    Inverse: "inverse"
stories:
  - name: "Hero Banner" 
    args:
      heading: Welcome to SDC
      heroImage: ''
      mediaImage: https://picsum.photos/id/29/1200/1200
      bodyText: |
        <p>Lorem ipsum generator tvinu lorem ipsum generator tvinu lorem ipsum generator tvinu</p>
 

Wir erstellen Stories, indem wir das Format {% story <name> with { args } %} verwenden, um sie hinzuzufügen. Das {% stories %}-Tag fungiert als Container für alle {% story %}-Tags; ohne es fehlt den Stories der Kontext.

4. hero.twig

Die primäre Template-Datei für die SDC-Komponente.

{#
# For slots that have an optional field, we need to do a
# render check right in the componet template using twig set
# and then check with a trim / is not empty.
# A "slot" which is basically some arbitrary text
# which will be replaced by the Drupal body text field anyway.
# Thus, the usage of {% block body %}
#}
{% set body_content %}
{% block body %}
{# Hero body text. #}
{{ bodyText | raw }}
{% endblock %}
{% endset %}
{# ------------------------- #}

{% if Image_Inverse == 1 %}
{% set inverse_class = 'c-hero__wrap--inverse' %}
{% endif %}

<section class="c-hero">
  <div class="c-hero__wrap {{ inverse_class }}">

    <div class="c-hero__content-wrap">
      {# Hero heading #}
      <div class="c-hero__heading">
        <h1>{{ heading }}</h1>
      </div>

      {% if body_content|trim is not empty %}
      <div class="c-hero__body-text">
        {{ body_content }}
      </div>
      {% endif %}
    </div>

    <div class="c-hero__media-wrap">
      <div class="c-hero__media">
        {% block media_image %}
        <img src="{{ mediaImage }}" width="1200" height="1200" loading="eager"
          alt="">
        {% endblock %}
      </div>
    </div>
  </div>
</section>

 Schritt 5: Komponenten-Stories generieren 

Die Storybook-Anwendung kann Stories im Twig-Format nicht verarbeiten. Die Stories müssen in *.stories.json-Dateien kompiliert werden. Dies erreichen Sie durch Ausführen von: drush storybook:generate-all-stories 

Um Stories zu erstellen, während Dateien überwacht werden, verwenden Sie diesen Befehl: 

watch --color drush storybook:generate-all-stories 

Schritt 6: Testen und Änderungen vornehmen 

Geben Sie den unten stehenden Befehl ein, um den Storybook-Server zu starten und die Komponenten zu testen: 

npm run storybook oder, falls Sie yarn verwenden, yarn storybook ausführen  

Aktualisieren Sie das Design und die Funktionen der Komponenten gemäß Feedback und Testergebnissen. Arbeiten Sie kontinuierlich an den SDC-Komponenten, um deren Benutzerfreundlichkeit und Effektivität zu steigern. So wird Ihre Storybook-Seite aussehen:

Wichtige Erkenntnisse 

1. SDC, was für Single Directory Components steht, bietet eine neue Methode zur Anordnung und Verwaltung von Komponenten in Drupal. 

2. Storybook ist ein Tool, das Entwicklern und Designern hilft, alle ihre Komponenten an einem Ort anzuzeigen und zu testen, bevor sie diese auf der eigentlichen Website verwenden. 

3. Die Integration von SDC mit Storybook in Drupal lädt Komponenten automatisch, was den Prozess der Erstellung und Verwaltung von Stories mit minimalem Aufwand vereinfacht. 

4. Um SDC zu verwenden, benötigen Sie mindestens Drupal Version 10.1 oder die neueste Drupal 11. 

5. Die Einrichtung von Storybook mit Drupal 11 ist einfach: SDC erstellen, aktivieren und die notwendigen Abhängigkeiten installieren.