�ݺ�ߣ

Drupal, Storybook e SDC
The Book Is No Longer on the Table
1

Enrico Sato
Drupal Frontend Developer @ SparkFabrik
Drupal.org: www.drupal.org/u/enricosato
LinkedIn: www.linkedin.com/in/enricosato/
drupal.slack.com: EnricoSato
@enricosato

3
Componenti
Nello sviluppo frontend un componente è parte di una
pagina o di un’applicazione.
➔ ISOLATO
➔ RIUTILIZZABILE
➔ COMPONIBILE
➔ MANUTENIBILE

4
Design
System
Deﬁnisce quali sono e come sono i componenti UI di
un’applicazione.
Perché utilizzare un Design System?
➔ Aiuta a rendere coerenti i componenti tra loro;
➔ Aiuta a strutturare il percorso di sviluppo;

5
Componenti
+
Drupal
=
SDC
Single Directory Components (SDC)
L’implementazione utilizzata nel core di Drupal per lo
sviluppo di componenti.
Singola directory presente in un modulo o in un tema che
contiene tutto il necessario per rappresentare e
visualizzare un componente: HTML (twig), CSS / JS.
Storia:
➔ Modulo contrib dal 2022;
➔ Integrato nel core come modulo sperimentale v. 10.1
(giugno 2023);
➔ Stabile core v. 10.3 (giugno 2024);

6
E prima?
CORE
➔ Macro e librerie;
MODULI CONTRIB:
➔ UI Pattern 1.x;
➔ Single File components;
➔ Components!;
➔ Component Libraries: Components;
Avere SDC nel core di Drupal permetterà di avere un
supporto più ampio da parte della community!

7
Nessuna card e nessun pulsante
verranno maltrattati oggi.

8
SDC è
pronto?
Raccontiamo la storia di un progetto
complesso e di come abbiamo messo
alla prova SDC.

9
Il nostro
progetto
➔ Piattaforma editoriale con costruzione
delle singole pagine a “elementi”;
➔ Ogni elemento deve avere varianti (colori,
layout) editoriali;
➔ Elementi annidati;
➔ Design system ben deﬁnito, serve un
tool per documentare;
➔ Possibilità di riutilizzare il Design
System;
➔ Lighthouse approved;

10
Tema è l’insieme dei files che definiscono l’aspetto e lo
stile visivo di un’applicazione Drupal.
Organizzazione dispersiva:
➔ Markup - templates;
➔ Style / JS - CSS / SCSS / DIST…;
➔ Assets grafici - images;
Problemi:
➔ Sviluppo a componenti risulta complesso;
➔ Difficile da mantenere;
➔ Rischio di duplicare;
Organizzare!

11
SDC ci obbliga ad organizzare i componenti in directory
contenenti tutto il necessario per deﬁnire quell’elemento.
Contiene o richiama ciò che serve:
➔ Creazione automatica libreria (ﬁle CSS / JS);
➔ Utilizzare librerie esterne (libraryOverrides);
Tutto ciò che riguarda un determinato componente viene
gestito in un unico luogo (Principio di Singola
responsabilità).
Quella “directory” nel nome

12
Solo dove
servono
Non può essere tutto suddiviso a componenti!
Problema: come utilizzare elementi comuni necessari nei
componenti?

13
Il nostro
approccio
occorre rispondere alla domanda dove va utilizzato?
➔ Elementi BASE (styleguide: colori, font…)
➔ Elementi GLOBALI (griglia)
➔ Elementi SPECIFICI (componenti)
Suddivisione rigorosa tra questi elementi!

14
Organizzazione di un tema Drupal con SDC
BASE
SPECIFICI
GLOBALI

15
Il Design System potrebbe richiedere pattern di componenti simili tra loro.
Duplicare rischia di essere la strada più facile!
SDC ci aiuta:
➔ ﬁle *.component.yml permette di dichiarare le proprietà;
➔ le proprietà possono essere varianti (colori, dimensioni, layout);
➔ WIP: idea di proprietà speciﬁca: Add component variants to SDC;
➔ le varianti di aspetto possono essere gestite editorialmente;
Varianti, non duplicati!

18
Performance SDC carica le proprie librerie solo quando un elemento
è in pagina.
➔ Suddivisione rigorosa degli assets;
➔ Evitare duplicati;
➔ Richiamare librerie esterne solo dove richiesto;
Possiamo evitare codice CSS/JS inutilizzato!

19
Documenta!
“Questo nuovo progetto lo documentiamo meglio…”
Richiesto un sistema per
➔ Documentare visivamente il Design System;
➔ Esplorare i singoli componenti;
➔ Veriﬁcare come si adatta cambiando il contenuto;
Un regalo per il tuo futuro

20
Strumento open source per costruire,
testare e documentare componenti UI in
modo isolato.
➔ Permette di vedere i singoli elementi
in isolamento (storie);
➔ Possibile esplorare i vari stati e
varianti di ciascun componente;
➔ Addons di base (Controls, Viewport,
Background, Measure) e Centinaia di
Addons aggiuntivi (accessibilità, test
regressione);
Storybook

21
Perché ci
piace
➔ Flessibile nell'organizzazione delle storie;
➔ Personalizzabile, anche nell’aspetto;
➔ Integrazione con Drupal - modulo dedicato;
➔ Integrato con SDC - ogni componente può avere (o
non avere) una sua storia;

22
Tutto è pronto…
TECNOLOGIA ORGANIZZAZIONE DOCUMENTAZIONE
SDC Gestione asset Storybook

23
… si parte!
Costruiamo ciò che ci
serve per fare data
entry
Entità Drupal SDC
Ogni SDC rappresenta
un’entità di Drupal
Storybook
Il risultato lo portiamo
su Storybook
(That’s the way I like it)

24
Non funziona!
➔ Organizzare SDC in base alle entità di
Drupal;
➔ Rappresentare su Storybook la
complessità delle entità di Drupal;
➔ La documentazione rischia di essere
posticipata;
➔ Difﬁcile rendere il Design System
riutilizzabile;

25
Raro esemplare di Drupalis frontendus developerus intento nella risoluzione di un problema.

26
Cos’è
Storybook? Storybook is a frontend workshop for building UI
components and pages in isolation. It helps you
DEVELOP and share hard-to-reach states and edge
cases without needing to run your whole app.
Thousands of teams use it for UI development, testing,
and documentation. It's open source and free.
https://storybook.js.org/docs
Un passo indietro

27
… si ri-parte!
Design System SDC Storybook
(That’s the way I’ll like it)
Drupal

28
L’analisi del Design System ci dice quali sono i
componenti necessari;
SDC ci permette di trasformare in codice il Design
System
Le proprietà di SDC ci obbligano a deﬁnire quali sono i
dati che ci servono e come ci servono:
➔ Titolo = stringa;
➔ Variante = booleano;
➔ Link (titolo, url, target) = array;
Ci serve un tool di sviluppo!
Design
System
SDC Storybook Drupal

29
Non solo documentazione!
Ogni storia può simulare l’utilizzo di un determinato
componente fornendo i dati necessari:
➔ Le singole storie ci permettono lo sviluppo dei
componenti in isolamento;
➔ Sfruttiamo gli addons (Controls, Viewport,
Background, Measure);
➔ Unica o più storie per gestire varianti e
annidamenti;
➔ Facile test al variare dei contenuti;
Design
System

30
Qualsiasi entità può essere la struttura dati di un SDC,
basta rispettare le proprietà.
Design
System

31
Vantaggi
Parallelizzare / anticipare / validare
➔ Frontend e theming può essere
parallelizzato e/o asincrono;
➔ Storybook può essere uno step di
validazione;
Portabilità / scalabilità
➔ Gli elementi del Design System
diventano oggetti;
➔ Un tema di Drupal può diventare un
base theme estendibile;
➔ Modiﬁche e nuovi componenti
disponibili ovunque;
Frontend indipendente dal CMS
➔ Il frontend è sviluppato in modo
autonomo, senza dipendenze dalle
entità di Drupal;
➔ Diversi tipi di entità possono essere
rappresentate dallo stesso SDC;

32
➔ Partito come sperimentale, diversi cambiamenti;
➔ Poca documentazione;
➔ Integrazione con Storybook non sempre
performante;
Non è stato sempre facile…

33
È complicato astrarre le entità di Drupal!
Non è stato sempre facile…

34
SDC piace
proprio a
tutti…
ATTENZIONE
La prossima slide contiene del codice PHP.
Si sconsiglia la visione ad un pubblico più sensibile.

In fase di sviluppo di logica potrebbe
essere necessario rigenerare
componenti (es. Ajax callback)
➔ Aggiungere HTML
direttamente nel codice;
➔ Duplicazione codice, prono
errori;
➔ Difﬁcile manutenzione!
35
Backend
// Dati per l'avviso
$type = 'warning';
$title = 'Attenzione!';
$message = 'Questo è un messaggio di avviso importante.';
// Genera il markup HTML
$output = '<div class="alert alert-' .
htmlspecialchars($type) . '">';
$output .= '<strong>' . htmlspecialchars($title) .
'</strong> ' . htmlspecialchars($message);
$output .= '</div>';
// Stampa l'avviso
print $output;

36
➔ SDC permette di richiamare
un componente in un render
array;
➔ Non serve scrivere markup;
➔ Facilmente riutilizzabile e
mantenibile;
Documentazione:
https://www.drupal.org/docs/develop/theming-drupal/
using-single-directory-components/using-your-new-
single-directory-component#s-using-your-compone
nt-through-a-render-array
SDC API
$render_array = [
'#type' => 'component',
'#component' => 'sdc_demo:alert',
'#props' => [
'type' = 'warning';
'title' = 'Attenzione!';
'message' = 'Questo è un messaggio di avviso
importante.';
],
];
BACKEND APPROVED!

37
La famiglia
cresce
➔ SDC Display - Permette ai Site Builders di utilizzare i
componenti dal Display delle entità;
➔ SDC Block - Permette di inserire un componente
tramite i blocchi (core block layout, layout builder)
➔ SDC Styleguide - Fornisce un'interfaccia rapida per
testare i componenti single-directory senza creare
contenuti sul sito.
Modules that extend Single-Directory Components

40
Docs:
➔ Using Single-Directory Components
Articoli:
➔ SDC in Drupal core
➔ Component-Based Design Using Single Directory Components (SDC) in
Drupal
➔ Modules that extend Single-Directory Components
➔ Your Drupal Site Needs a Storybook Design System
➔ The New Storybook Module for Drupal
Links utili

41
Chapter 1 - Setting Up a Local Environment
…
Chapter 3 - How Drupal Renders an HTML Page
Chapter 4 - Mapping the Design to Drupal Components
…
Chapter 11 - Single Directory Components
…
Chapter 15 - Building a Decoupled Frontend
Learn more
Una lettura interessante

Siamo una tech company di engineers,
developers e designers, capace di
accompagnare passo passo i clienti
nell’era CLOUD NATIVE,
con un approccio agile e pragmatico.
Ci impegniamo per l’OPEN SOURCE
e ne abbracciamo la ﬁlosoﬁa nelle nostre
pratiche interne.
TECNOLOGIA,
STRATEGIA E METODO
42

�ݺ�ߣ

Talks on my machine: Drupal, Storybook e SDC

More Related Content

Talks on my machine: Drupal, Storybook e SDC