SDC: Integration von Storybook & Single Directory Component
AI-Translated
Heute sprechen wir über Drupal Single Directory Components (SDC) und Storybook. Single Directory Components in Drupal ermöglichen die Strukturierung Ihrer UI-Komponenten, während Storybook deren Interaktion und Visualisierung erleichtert. Ihre Integration verändert den Entwicklungsprozess grundlegend und schafft eine innovative Methode zum Erstellen und Testen von UI-Komponenten.
Mit der Veröffentlichung von Drupal 11 wird eine stabilisierte Version der Drupal Single Directory Components eingeführt.
Stellen Sie sich das einmal vor -
Stellen Sie sich eine Lösung vor, die UI-Komponenten von Websites übersichtlich, für verschiedene Projekte wiederverwendbar, über alle Webseiten hinweg einheitlich hält und noch weitere Vorteile bietet.
SDC (Single Directory Components) ist eine Schlüsselfunktion in Drupal 10.1 und Drupal 11, die all dies ermöglicht.
In diesem Blogbeitrag erörtern wir, 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 Migrationsservices, bevor wir fortfahren.
Tauchen wir ein!
Was ist SDC?
SDC war einst ein Contributed Module, 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 nutzt.
SDC erweitert Ihre Drupal-Themes für einen zeitgemäßeren 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.
Doch 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 spezifischen UI-Elements erforderlichen Ressourcen kapseln. SDC organisiert Templates, Stile, Skripte und Metadaten für jede Komponente in einem einzigen Verzeichnis, was eine kohärentere und wartungsfreundlichere Entwicklungserfahrung bietet.
Mit SDC können Entwickler austauschbare und modulare Komponenten entwerfen, was ihren Code flexibler und wiederverwendbarer macht. Komponenten unterstützen bei der Organisation, Wiederverwendung, Konsistenz, Skalierung, beim Testen und bei der Zusammenarbeit. Diese Konfiguration erleichtert die Integration mit Tools wie Storybook.
Das Verzeichnis einer SDC enthält diese Dateien:
-
Eine YAML-Datei mit Metadaten, die Drupal bei der Identifizierung der Komponente unterstützt.
-
Eine Twig-Datei mit den Templates.
-
Eine CSS-Datei mit den Stilen.
-
Eine JavaScript-Datei mit den Skripten.
Eine Komponente kann optional auch einen Screenshot, eine PHP-Datei (mit Hooks und Alters), Medien (wie Bilder, Audio oder Video) oder andere zugehörige Elemente enthalten.
Zuverlässigere und einfachere Frontends, die leicht zu aktualisieren sind?
Ja, bitte!
Lesen Sie auch:
Was ist Storybook?
Storybook ist ein Tool, das Entwicklern und Designern hilft, alle ihre Komponenten an einem Ort anzuzeigen und zu testen, bevor sie auf der eigentlichen Website verwendet werden. Es ist fantastisch, weil es Open Source, weit verbreitet und benutzerfreundlich 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 funktionieren. Es bietet eine visuelle Anleitung zu den Komponenten, die es einfach macht, zu sehen und zu verstehen, wie jede Komponente funktioniert.
Storybook bietet ein einfacheres Dateilayout als verschiedene Alternativen, nutzt Webpack und ist mit einer Vielzahl von Frontend-Technologien kompatibel. Es lässt sich leicht an individuelle Bedürfnisse anpassen. Storybook ist heute eines der führenden Designsysteme, die 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, Labels und Überschriften.
- Moleküle: Dies sind fortgeschrittenere UI-Komponenten, die aus Atomen gebildet werden, wie ein Suchfeld in Kombination mit einem Absende-Button.
- 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 weltweit nur 100 Organisationen, die als Drupal Association Certified Partner anerkannt sind. Wenn Sie Ihre Drupal 7-Website migrieren möchten, informieren Sie sich noch heute über unsere Services.
Warum sollten Sie SDC mit Storybook in Drupal integrieren?
Die Integration von SDC mit Storybook in Drupal bietet zahlreiche Vorteile. Es 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. Einfaches Drupal-Setup 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 ein umfangreiches Drupal-Setup betreiben zu müssen. Dies beschleunigt die Entwicklung und stellt sicher, dass alles reibungslos funktioniert.
3. Erleichtert 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 die Datenintegrität gewährleistet. 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 es neuen Entwicklern erleichtert, einzusteigen, 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 ermöglicht, am Projekt teilzunehmen.
6. Drupal-bezogene Funktionen in Komponenten integriert
Integrieren Sie Drupal-Verhaltensweisen, wie z.B. [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.
Anforderungen 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 in Storybook beginnen können.
-
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.
-
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:
Wie integriert man SDC mit Storybook in Drupal 11?
Das Einrichten 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-Core-Modul. 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 einkommentieren
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 package.json-Ordner im Root-Verzeichnis 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
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
-
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. Der {% stories %}-Tag dient als Container für alle {% story %}-Tags; ohne ihn 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 und dabei Dateien zu überwachen, 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
-
SDC, das für Single Directory Components steht, bietet eine neue Methode zur Anordnung und Verwaltung von Komponenten in Drupal.
-
Storybook ist ein Tool, das Entwicklern und Designern hilft, alle ihre Komponenten an einem Ort anzuzeigen und zu testen, bevor sie auf der eigentlichen Website verwendet werden.
-
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.
-
Um SDC zu nutzen, benötigen Sie mindestens Drupal Version 10.1 oder die neueste Drupal 11.
-
Das Einrichten von Storybook mit Drupal 11 ist einfach: Erstellen Sie SDC, aktivieren Sie sie und installieren Sie die notwendigen Abhängigkeiten.
Abonnieren