Editor dello scenario¶

L'editor dello scenario è lo strumento per creare e modificare scenari. Uno scenario è l'insieme di nodi (che l'utente nel Navigator vede come schede) e di collegamenti fra i nodi (che l'utente nel Navigator vede come i tasti di scelta all'interno delle schede). Gli scenari sono salvati come file JSON. L'editor dello scenario ha due modalità, quella di edit in cui gli elementi sono visualizzabili come blocchi editabili oppure come mappa navigabile.

Modalità Edit¶

L'interfaccia è divisa in due parti.

Colonna di sinistra¶

La colonna di sinistra è dedicata alla gestione delle operazioni generali e dello scenario aperto. È possibile nasconderla cliccando sul pulsante con la freccia (◀) sul suo bordo destro, per avere più spazio per l'area di editing. Per riaprirla, cliccare sul pulsante con la freccia (▶).

Nella parte alta mostra una riga con i tasti per:

• New: creare un nuovo scenario
• Open: aprire uno scenario esistente
• Save: salvare lo scenario corrente come file JSON
• Map: attivare la visualizzazione della mappa

I nomi dei tasti sono nell'inglese di default, ma possono essere personalizzati tramite Settings.

Sotto la riga dei tasti compare l'elenco dei nodi che fanno parte dello scenario aperto: solo il nodo Start se si sta partendo con un nuovo scenario, una lista completa se si è già avanti con la creazione o se si apre uno scenario esistente.

Ogni nodo nella lista mostra:

• il titolo (estratto dal contenuto)
• l'identificativo tecnico
• badge informativi: livello e posizione (es. L2-P1), START per il nodo iniziale, END per i nodi terminali

Area di editing¶

La parte destra è dedicata all'editing del nodo selezionato.

La riga in alto contiene:

• sulla sinistra: il nome del file dello scenario e il totale dei nodi. Per un nuovo scenario compare "New scenario", il nome cambia automaticamente dopo il salvataggio
• sulla destra: il pulsante Settings per i metadati e le traduzioni

Sotto la riga di intestazione compaiono i blocchi che definiscono il nodo:

• Node: gestione dell'identificativo del nodo
• Content: il contenuto testuale
• Level: per modificare il livello di default definito dal sistema
• Choices: le scelte disponibili all'utente
• Resources: gli allegati e risorse collegate

Node¶

Il blocco Node gestisce l'identificativo del nodo. Contiene:

• Rename: apre un campo per modificare l'identificativo. L'ID deve essere univoco nell'intero scenario e può contenere solo lettere, numeri e underscore
• DELETE: elimina l'intero nodo dallo scenario. Non è disponibile per il nodo START. Prima di eliminare, il sistema chiede conferma

Level¶

Il blocco Level controlla la posizione del nodo nella gerarchia logica. Per default, i livelli sono calcolati automaticamente usando il percorso più breve dal nodo iniziale (algoritmo BFS). Il nodo start è livello 1, i suoi figli diretti sono livello 2, e così via.

Tuttavia, in scenari complessi con percorsi multipli verso lo stesso nodo, il calcolo automatico potrebbe non riflettere la struttura logica intesa. In questi casi, puoi impostare un override esplicito del livello.

Elementi della sezione Level:

• Override Level: campo numerico per impostare un livello esplicito (lasciare vuoto per il calcolo automatico)
• Indicatore di stato: mostra se il livello è "Explicit" (impostato manualmente) o "Auto-calculated"
• Reset to Auto: pulsante per rimuovere il livello esplicito e tornare al calcolo automatico

Quando usare l'override manuale del livello:

• Quando un nodo è raggiungibile tramite percorsi multipli di lunghezze diverse
• Per assicurare la corretta colorazione dei loop (i loop collegano a nodi antenati)
• Per controllare il posizionamento verticale nella vista mappa
• Per definire una gerarchia semantica indipendente dai percorsi di connessione

Esempio: Se il nodo "assemblaggio" è raggiungibile sia direttamente da "start" (1 passo) sia dopo tre nodi di preparazione (4 passi), il calcolo automatico assegna livello 2. Impostando il livello esplicito 5 lo posiziona correttamente dopo le preparazioni e assicura che i loop siano colorati correttamente.

Content¶

Il blocco Content contiene il testo che l'utente vedrà nella scheda del Navigator.

L'area di testo è ridimensionabile verticalmente: trascinare la maniglia arancione sotto la textarea per espandere o ridurre lo spazio di editing.

Il contenuto usa una sintassi Markdown semplificata:

Choices¶

Il blocco Choices definisce le scelte disponibili all'utente, cioè i pulsanti che permettono di procedere nel percorso.

Nella lista delle scelte già inserite è possibile cambiare la sequenza agendo sulle frecce su/giù sulla destra. Sempre a destra si trova il tasto REMOVE per cancellare la choice. Cliccando sul tasto + Add Choice che si trova sotto la lista si aggiunge una nuova scelta con due campi obbligatori:

• Button Text: il testo che appare sul pulsante
• Target Node: il nodo di destinazione, selezionabile da un menu a tendina che elenca tutti i nodi esistenti

Il menu Target Node include anche l'opzione + Create new node che apre un popup per creare direttamente un nuovo nodo destinazione.

Il popup include:

• Node ID: identificativo univoco per il nuovo nodo
• Node content: il contenuto markdown
• Level: il livello del nodo nella gerarchia (default: livello padre + 1, modificabile)

Indicatori visivi di stato:

• bordo grigio: scelta appena creata, non ancora compilata
• bordo ambra con "? unsaved": modifiche non salvate
• bordo verde con "?": scelta completa e salvata
• bordo rosso: errori di validazione

Il pulsante Save Choice salva la scelta solo se entrambi i campi sono compilati. Il pulsante REMOVE elimina la scelta.

Un nodo può avere più scelte che portano a nodi diversi. È possibile creare loop collegando un nodo a uno dei suoi antenati.

Resources¶

Il blocco Resources permette di allegare risorse esterne al nodo.

Cliccando su + Add Resource si aggiunge una risorsa con tre campi obbligatori:

• Type: il tipo di risorsa
  • Link: collegamento a una pagina web
  • Download: documento scaricabile (deve essere accessibile via URL)
  • Video: video YouTube (usare il link di condivisione)
• URL: l'indirizzo della risorsa, può essere sia un link web sia un url relativo ad una risorsa locale. In questo caso conviene definire una sottocartella in cui raccogliere gli elementi, l'url potrebbe essere "docs/elemento1.pdf
• Label: la descrizione che appare all'utente nel Navigator

Gli indicatori visivi di stato funzionano come per le Choices. Il pulsante Save Resource salva solo se tutti i campi sono compilati.

Settings: metadati e traduzioni¶

Il pulsante Settings apre un pannello per configurare i metadati dello scenario e le etichette dell'interfaccia.

Metadati:

• Title: il nome dello scenario, visibile nell'intestazione del Navigator
• Description: descrizione breve (opzionale)
• Author: nome dell'autore (opzionale)

UI Labels: permette di tradurre o personalizzare tutte le etichette dell'interfaccia utente (step, restart, endOfPath, resources, viewMap, back, download, openLink, watchVideo).

Il file JSON¶

Uno scenario viene salvato come file JSON strutturato in tre sezioni:

• meta: i metadati (title, description, author)
• translations: le etichette personalizzate
• startNode: l'identificativo del nodo di partenza
• nodes: l'oggetto contenente tutti i nodi con i loro contenuti, scelte e risorse

Salvataggio¶

Il pulsante Save genera un file JSON. Non c'è salvataggio automatico: salvare regolarmente durante il lavoro.

Validazione automatica: al momento del salvataggio, l'editor controlla choice e risorse incomplete. Se una choice non ha testo o target, oppure una risorsa manca di tipo, URL o etichetta si apre un popup che segnala gli elementi incompleti e chiede conferma per il salvataggio. Questo previene la comparsa di pulsanti vuoti o risorse non funzionanti nel Navigator.

Prevenzione duplicati: quando si aggiunge una choice, i nodi già collegati da altre choice dello stesso nodo non appaiono più nella lista dei target disponibili. Questo evita di creare involontariamente collegamenti duplicati verso lo stesso nodo.

Nella barra di stato in basso è sempre visibile lo stato:

• "● Unsaved" (arancione): ci sono modifiche non salvate
• "✓ Saved" (verde): tutto salvato

Modalità Mappa¶

La modalità mappa mostra lo scenario come un albero visuale.

Ogni nodo mostra il suo identificativo e il titolo. I collegamenti tra nodi rappresentano le scelte disponibili, le frecce indicano la direzione del percorso. Il layout automatico dispone i nodi su livelli in base alla loro gerarchia logica, con il nodo iniziale in alto e i rami che si espandono verso il basso. Con un doppio click su un nodo si apre la scheda di edit di quel nodo. Il tasto rosso in alto a destra, con la X, chiude la vista mappa per tornare all'edit.

Una volta ottenuta la disposizione desiderata dei nodi lo scenario deve essere esplicitamente salvato con la funzione Save dell'editor.

Codice colori dei bordi:

• verde: nodo di partenza (START)
• arancione: nodo terminale (END)
• rosso: nodo orfano, non raggiungibile
• viola: nodo selezionato
• rosa: nodi multi-selezionati

Colori delle connessioni indicano la relazione logica tra i nodi:

• Grigio: connessione in avanti (verso un nodo discendente)
• Arancione: connessione loop (verso un nodo antenato)
• Viola: connessione stesso livello (verso un nodo sullo stesso livello)

I colori delle connessioni sono basati sulla gerarchia logica (livelli dei nodi), non sulla posizione visiva. Questo significa che i colori non cambiano anche se riposiziondo i nodi.

Canvas dinamico: l'area bianca della mappa si espande automaticamente quando trascini un nodo oltre il bordo destro o inferiore. Questo permette di gestire scenari di qualsiasi dimensione senza limiti fissi.

Strumenti di posizionamento nodi¶

La vista mappa include potenti strumenti per organizzare il layout dello scenario:

Spostamento dei nodi: tenendo premuto CTRL (o CMD su macOS) è possibile trascinare i nodi per personalizzare il layout. Le posizioni si agganciano automaticamente a una griglia di 20px per layout puliti e allineati. Il pulsante "Auto Layout" ripristina il posizionamento automatico, allineando i nodi sullo stesso livello

Modalità Node repositioning: tenendo premuto SHIFT e selezionando un nodo si attiva la modalità Node repositioning con funzionalità per il posizionamento ordinato dei nodi. In questa modalità viene attivata una toolbar nella cornice superiore.

Cliccando sui nodi è possibile aggiungerli o rimuoverli da una selezione multipla, i nodi multi-selezionati mostrano un bordo rosa. I tasti funzionali nella toolbar:

• Select Level: dopo avere selezionato un nodo seleziona tutti i nodi allo stesso livello gerarchico
• Align H: selezionando almeno 2 nodi allinea i nodi selezionati orizzontalmente (stessa coordinata Y)
• Align V: selezionando almeno 2 nodi allinea i nodi selezionati verticalmente (stessa coordinata X)
• Distrib H: selezionando almeno 3 nodi distribuisce con spaziatura orizzontale uniforme
• Distrib V: selezionando almeno 3 nodi distribuisce con spaziatura verticale uniforme
• ✕: deseleziona i nodi selezionati e chiude la modalità node repositioning

Workflow tipico per uniformare la spaziatura dei nodi:

1. Clicca su un nodo qualsiasi al livello che vuoi organizzare
2. Clicca su "Select Level" per selezionare tutti i nodi a quel livello
3. Clicca su "Distrib H" o "Distrib V" per distribuirli uniformemente
4. Salva lo scenario per preservare le posizioni