#howtodev - Diagrammi con mermaidjs - Introduzione

MermaidJS è una libreria Javascript per la creazione di diagrammi tramite linguaggio di formattazione. È integrato in alcuni software ed è facile da utilizzare.

Ecco una guida sull’utilizzo base.

Definizione

MermaidJS consente di creare, tramite un linguaggio di markup, grafici di diverso tipo: UML, di MANAGMENT, flowchart etc…

Essendo un approccio di tipo WYSIWYM (Ovvero What you see is what you mean) consente facilmente di ottenere risultati ottimali senza quella frustazione tipica dei software GUI in cui si passa il tempo a spostare archi e riquadri fino ad ottenere soluzioni soddisfacenti.

Obiettivi

L’articolo affronterà i seguenti argomenti:

• Installazione di mermaidJS
• Uso base
• Tipologia di diagrammi
• Flow Chart

Prerequisiti

All’interno dell’articolo si troveranno riferimenti a NPM, sarebbe quindi meglio conoscere lo strumento prima di continuare l’articolo.

Installazione

Esistono vari modi di utilizzare mermaidJS. Il più comune è sicuramente quello di utilizzarlo tramite la comoda interfaccia web ufficiale che consente anche di vedere le modifiche in tempo reale.

Esistono anche alcuni editor GUI come Typora che lo includono come funzionalità aggiuntiva.

Ma essendo una libreria Javascript può essere utilizzato anche attraverso codice o con un client dedicato.

Installare mermaid-cli

Il modo migliore per interagire in locale con mermaid è proprio quello di usare il client. Per installarlo utilizzare npm:

npm install --global mermaid.cli

Utilizzo mermaid.cli

Va poi utilizzato tramite la linea di comando. Per generare un diagramma basta scrivere:

mmdc -i nomefileinput -o nomefileoutput.png 

Dove nomefileinput è il codice sorgente scritto con il markup di mermaidjs, nomefileoutput è il nome dell’immagine dove finirà il grafico.

Ci sono anche diverse opzioni molto utili, ad esempio i temi :

-t <theme>

I temi sono default, forest, dark e neutral

O semplicemente il colore del background

-b <colore>

il colore potete scriverlo in esadecimale con # prima oppure in inglese come se fosse un foglio di stile.

Si possono impostare impostare larghezza ed altezza dell’output così:

-w <width>
-H <height>

Facendo un esempio completo, per creare un grafico con background nero, tema dark, dimensione 400x400 il comando sarà:

mmdc -b '#000000' -t dark -w 400 -H 400 -i nomefileinput -o nomefileoutput.png

Tipologie di diagrammi

Mermaid supporta tantissimi tipi di diagrammi, ed essendo ancora pienamente supportato e aggiornato, aumentano ogni anno.

Quelli supportati dal framework al momento sono:

• Flowchart
• Sequence Diagram
• Class Diagram
• State Diagram
• Entity Relationship Diagram
• User Journey
• Gantt
• Pie Chart
• Quadrant Chart
• Requirement Diagram
• Gitgraph (Git) Diagram
• C4 Diagram
• Mindmaps
• Timeline
• ZenUM
• Sankey
• XY Chart
• Block Diagram
• Packet
• Architecture

Maggiori dettagli nella documentazione ufficiale.

Non tutti i grafici son supportati dai client che utilizzano il framework, consultare quindi le documentazioni dei vari progetti per avere dettagli della versione supportata.

Sintassi base

Generalmente tutti i diagrammi son introdotti dal nome sulla prima riga, a seguire ogni altra riga, con un livello di indentazione in più.

Flow Chart

Uno dei tipi più comuni e semplici di diagrammi: può rappresentare un flusso di istruzioni, di idee, la descrizione di algoritmo etc…

Un flowchart è introdotto su mermaid da:

flowchart LR

LR rappresenta la direzione del grafico (ovvero left to right in questo caso), può essere sostituito da TB. Ogni combinazione di lettere (BT e RL). A seguire si possono effettuare i vari collegamenti tra i box.

Per creare un box basta scriverne il nome:

flowchart LR
	A

Per assegnare un nome diverso dall’etichetta basta scriverne il nome tra parentesi quadre:

flowchart LR
    A[Un box qualunque]

Per creare un collegamento tra due box, collegarli con una freccia: -->

flowchart LR
    A[Un box qualunque] --> B

Continuando si possono creare vere e proprie catene:

flowchart LR
    A[Un box qualunque] --> B
	B-->C
	C-->D
	C-->A
	F-->B

Il risultato sarà

Se manca lo spazio verticale (nel caso di diagrammi LR e RL) automaticamente i box vengono disposti su seconda riga.

Altre forme

Un diagramma di flusso può essere fatto da diversi blocchi con diverse forme. Ognuna delle quali ha differenti significati (blocco condizionale, blocco sorgente dati, input/output etc…).

Per disegnare tramite mermaid altre forme basta scrivere, dopo l’identificativo, il simbolo che lo rappresenta.

Attività semplice

Per un blocco attività semplice (rettangolare), come si è già visto si utilizzano le parentesi quadre [], ma anche semplicemente scrivendo il nome, se non contiene caratteri particolari o spazi, per impostazioni predefinita diventa un blocco rettangolare:

flowchart TB
    A["blocco attività"]
	SecondoBlocco

Blocco di partenza/fine

I blocchi rettangolari con gli angoli arrotondati utilizzati in genere all’inizio e alla fine del flusso, in mermaid si utilizzano le parentesi tonde () per identificarlo

flowchart TB
    A("blocco fine/inizio")

Blocco delle decisioni

Per diramare una decisione si può utilizzare un blocco a forma di rombo, tramite le parentesi graffe {}:

flowchart TB
    A{"blocco decisionale"}

Blocco input/output

I blocchi che identificano l’ingresso di una variabile o l’uscita possono essere identificati da parallelogramma, che nel framework son identificati da parentesi quadre e caratteri slash inversi, al cui interno va poi messo il testo del blocco [\ \]:

flowchart TB
    A[\variabile input o output\]

Si può anche invertire la direzione del parallelepipedo utilizzando il carattere slash normale [/ /]

flowchart TB
    A[/variabile input o output/]

Database

Per indicare una sorgente dati si usa un icona cilindrica, che rappresenta appunto il database.
Allo scopo, scrivere il testo tra parentesi quadre e poi tonde [()]

flowchart LR
    id1[(Database)]

Altre forme

Mermaid supporta moltre altre forme, come il cerchio, trapezzoidi e altro: maggiori informazioni sulla documentazione ufficiale

Testo nel collegamento

Si può inserire un testo nella freccia che collega un box ad un altro, per farlo scrivere del testo tra due segni - e altri due:

flowchart TB
    A --"testo collegamento"-->B

Sotto-grafico

Si può racchiudere una porzione di diagramma a parte, un vero e proprio sotto-diagramma, che può avere una direzione diversa ad esempio, un nome a se stante ed essere collegato ad altri.

Per crearlo scrivere subgraph NOME e su nuova linea scrivere i collegamenti, terminare con end:

flowchart LR
	subgraph sottoD1
		A-->B
	end
	C-->sottoD1
	D-->A

Per cambiare direzione nel sottografico la prima istruzione deve essere direction seguita dalla direzione:

flowchart LR
	subgraph sottoD1
        direction TB
		A
        B
        A-->B
	end
	C-->sottoD1

NOTA BENE:

Ricordarsi che comunque mermaid aggiusta la direzione e la posizione dei blocchi per ottimizzarli, quindi il sottografo potrebbe anche seguire una direzione diversa

Cambio di stile

Si può sistemare lo stile e aggiungere classi utilizzando la parola chiave style seguito dallo stile: purtroppo non è uno stile nella sintassi standard di css:

• fill rappresenta il colore di sfondo.
• stroke rappresenta il colore della freccia.
• color rappresenta il colore nel testo.
• stroke-dasharray serve a creare un bordo frastagliato, prende in ingresso due o più numeri, il primo indica la lunghezza del segmento il secondo la distanza tra un segmento ed un altro, se si continua con altri numeri si possono indicare lunghezze diverse.
• stroke-width indica quanto ogni segmento è spesso.

Ecco un esempio:

flowchart LR
	A-->B
    C-->B
    D-->A
    style A fill:#000,color:#FFF
    style C fill:#FFF,stroke:#F00
    style B stroke-dasharray: 3 5

Si può inserire anche una classe. Dopo un identificativo di blocco inserire tre volte i due punti ::: e quindi il nome della classe, si può quindi definire dopo la classe scrivendo classDef nomeclasse style

Ecco un esempio:

flowchart LR
	A:::verde-->B
    C-->B
    D-->A
    classDef verde fill:#0F0, color:#666, stroke: #666