Struttura dei contenuti¶

Questa sezione descrive l'architettura dei file e il formato JSON che compone uno scenario. La conoscenza di questa struttura non è necessaria per usare lo Scenario Editor, ma è utile per modifiche avanzate, debugging, o per generare scenari programmaticamente.

Architettura dei file¶

ChoiceMap separa nettamente il framework (codice) dai contenuti (dati). I file HTML contengono l'applicazione e non vanno modificati; tutte le personalizzazioni avvengono tramite file JSON.

File HTML (framework)¶

I tre file HTML sono applicazioni complete che non richiedono modifiche:

Questi file caricano React e Tailwind CSS da CDN e leggono i contenuti dai file JSON. Non è necessario (né consigliato) modificarli.

config.json (il regista)¶

Il file config.json è il punto di ingresso che dice al Navigator cosa caricare:

{
    "scenario": "scenario-mio-progetto.json",
    "theme": "theme.json",
    "showCredits": true
}

Cambiando il valore di scenario e ricaricando il Navigator, si passa a uno scenario diverso senza modificare altro. Lo stesso per theme.

defaults.json (valori predefiniti)¶

Contiene tutti i valori di default per il tema: colori, font, configurazione del branding. È il "tema base" da cui partono tutti gli altri.

{
    "brand": {
        "name": "",
        "logo": "",
        "website": ""
    },
    "colors": {
        "background": "#ffffff",
        "text": "#1f2937",
        "accent": "#6366f1"
    }
}

Questo file non va modificato. Per personalizzare l'aspetto, si crea un file tema separato.

theme.json (personalizzazioni)¶

Il file tema contiene solo le personalizzazioni rispetto ai default. Il Navigator legge prima defaults.json, poi sovrascrive con i valori presenti in theme.json.

Se theme.json contiene solo il logo aziendale, tutti gli altri valori (colori, font) vengono presi da defaults.json:

{
    "brand": {
        "name": "Azienda XYZ",
        "logo": "images/logo.png"
    }
}

Questo approccio permette di creare temi minimali che specificano solo ciò che cambia.

shared-styles.css (solo per gli editor)¶

Contiene stili CSS condivisi tra Scenario Editor e Theme Editor. Non viene usato dal Navigator e non serve includerlo quando si pubblica uno scenario per gli utenti finali.

Il file scenario¶

Ogni scenario è un file JSON con una struttura ben definita:

{
    "meta": {
        "title": "Titolo dello scenario",
        "description": "Descrizione opzionale",
        "author": "Nome autore"
    },
    "translations": {
        "step": "Passo",
        "restart": "Ricomincia",
        "endOfPath": "Fine del percorso",
        "resources": "Risorse",
        "viewMap": "Vedi mappa",
        "mapOf": "Mappa di",
        "back": "Indietro",
        "download": "Scarica",
        "openLink": "Apri",
        "watchVideo": "Guarda"
    },
    "startNode": "start",
    "nodes": {
        "start": {
            "content": "# Benvenuto\n\nContenuto in **Markdown**.",
            "level": 1,
            "position": { "x": 0, "y": 0 },
            "choices": [
                { "text": "Prima opzione", "next": "nodo_a" },
                { "text": "Seconda opzione", "next": "nodo_b" }
            ],
            "resources": []
        }
    }
}

Sezione meta¶

La sezione meta contiene le informazioni descrittive dello scenario.

Sezione translations¶

Definisce le etichette dell'interfaccia, permettendo di localizzare lo scenario in qualsiasi lingua.

Per un quiz, si potrebbe usare "Domanda" invece di "Passo" e "Riprova" invece di "Ricomincia".

Campo startNode¶

Indica quale nodo è il punto di partenza dello scenario. Il valore deve corrispondere a una chiave presente nell'oggetto nodes.

Tipicamente si usa "start" per convenzione, ma può essere qualsiasi identificativo valido.

Sezione nodes¶

Un oggetto dove ogni chiave è l'identificativo di un nodo e il valore contiene i dati del nodo.

Identificativo del nodo: la chiave di ogni nodo è il suo ID univoco, usato internamente per i collegamenti. Convenzioni consigliate: - Solo lettere minuscole, numeri e underscore - Nomi descrittivi ma brevi: intro, domanda_1, risposta_ok - Evitare spazi e caratteri speciali

Struttura completa di un nodo:

"nome_nodo": {
    "content": "# Titolo\n\nContenuto in **Markdown**.",
    "level": 1,
    "position": { "x": 0, "y": 0 },
    "choices": [
        { "text": "Testo del pulsante", "next": "id_nodo_destinazione" }
    ],
    "resources": []
}

Contenuto del nodo: il campo content contiene il testo in formato Markdown. Per la sintassi supportata, vedi Content.

Per andare a capo nel JSON, usare \n:

"content": "Prima riga\n\nSeconda riga dopo uno spazio"

Livello del nodo: il campo level definisce la posizione gerarchica del nodo nell'albero. Se omesso, viene calcolato automaticamente in base alla distanza dal nodo di partenza. L'override manuale è utile per controllare la colorazione dei loop nella mappa: le connessioni verso nodi di livello inferiore sono colorate in arancione (loop), quelle verso lo stesso livello in viola, quelle verso livelli superiori in grigio (avanzamento).

Posizione del nodo: il campo position memorizza le coordinate x e y del nodo nella visualizzazione mappa. Se impostato a { "x": 0, "y": 0 } (valore placeholder), al salvataggio le coordinate vengono calcolate automaticamente dall'algoritmo di auto-layout. Se l'utente sposta manualmente un nodo nella mappa, le nuove coordinate vengono salvate e preservate.

Scelte del nodo: il campo choices è un array di oggetti che definiscono i pulsanti di scelta:

"choices": [
    { "text": "Testo del pulsante", "next": "id_nodo_destinazione" }
]

• text: quello che l'utente legge sul pulsante
• next: l'identificativo del nodo di destinazione

Un nodo senza scelte (array vuoto []) è un nodo finale.

Risorse del nodo: il campo resources è opzionale e definisce allegati:

"resources": [
    { "type": "download", "label": "Scarica il PDF", "url": "docs/guida.pdf" },
    { "type": "link", "label": "Approfondisci", "url": "https://esempio.com" },
    { "type": "video", "label": "Video tutorial", "url": "https://youtube.com/watch?v=..." }
]

Validazione¶

Il Navigator mostra errori se qualcosa non funziona nei file JSON. Errori comuni:

• JSON malformato (virgole mancanti, virgolette non chiuse)
• startNode che punta a un nodo inesistente
• Scelte che puntano a nodi inesistenti
• Sezione translations mancante o incompleta

Lo Scenario Editor genera sempre JSON valido, ma modifiche manuali possono introdurre errori. In caso di problemi, verificare la sintassi con un validatore JSON online.