Vai al contenuto

Installazione e avvio

Questa sezione dettaglia i requisiti e le procedure per far funzionare ChoiceMap sul proprio computer.

Requisiti

ChoiceMap ha requisiti minimi. Serve un browser moderno (Chrome, Firefox, Safari, Edge nelle versioni recenti) e Python per avviare il server locale.

Python è necessario solo per lo sviluppo locale. Una volta pubblicato su un server web, gli utenti finali non hanno bisogno di Python: accedono direttamente dal browser.

Su Windows, Python potrebbe non essere preinstallato. Si può scaricare da python.org o installare tramite Microsoft Store. Per verificare se è presente, aprire il Prompt dei comandi e digitare python --version. Se compare un numero di versione (3.x), Python è installato.

Su Mac, Python è tipicamente già presente. Su Linux, è quasi sempre disponibile di default.

Scaricare il pacchetto

Il pacchetto completo è disponibile come file ZIP dalla pagina GitHub del progetto, nella sezione Releases. Il download include:

  • choicemap.html - il Navigator
  • scenario-editor.html - l'editor per creare scenari
  • theme-editor.html - l'editor per personalizzare i temi
  • config.json - file di configurazione
  • defaults.json - valori predefiniti condivisi
  • theme.json - tema predefinito
  • scenario-sample.json - scenario di esempio narrativo
  • scenario-quiz.json - esempio di quiz
  • scenario-workflow.json - esempio di workflow
  • Script batch per Windows
  • Cartella docs/ per risorse scaricabili

Estrarre lo ZIP in una cartella a scelta. Il percorso non deve contenere caratteri speciali o spazi per evitare problemi con alcuni sistemi.

Avvio su Windows

Il modo più semplice su Windows è usare gli script batch inclusi.

Fare doppio clic su start-navigator.bat per avviare il server e aprire il Navigator nel browser predefinito. Lo script avvia un server sulla porta 8000.

Fare doppio clic su start-scenario-editor.bat per aprire direttamente lo Scenario Editor.

Fare doppio clic su start-theme-editor.bat per aprire il Theme Editor.

Se compare un errore che indica che Python non è trovato, è necessario installarlo o aggiungerlo al PATH di sistema.

Gli script creano un server che resta attivo finché la finestra del terminale è aperta. Chiudendo la finestra si ferma il server.

Avvio manuale

Se si preferisce non usare gli script o si è su Mac/Linux, l'avvio manuale richiede pochi comandi.

Aprire un terminale nella cartella del progetto. Su Windows si può fare clic destro tenendo premuto Shift e selezionare "Apri finestra PowerShell qui" o "Apri nel terminale".

Eseguire il comando:

python -m http.server 8000

Il terminale mostra un messaggio come "Serving HTTP on 0.0.0.0 port 8000". Il server è attivo.

Aprire il browser e navigare agli indirizzi:

  • Navigator: http://localhost:8000/choicemap.html
  • Scenario Editor: http://localhost:8000/scenario-editor.html
  • Theme Editor: http://localhost:8000/theme-editor.html

Per fermare il server, tornare al terminale e premere Ctrl+C.

Perché serve un server

Aprendo i file HTML direttamente (doppio clic o trascinando nel browser), il Navigator non funziona. Appare una schermata vuota o un errore.

Il motivo è una restrizione di sicurezza dei browser. Quando un file HTML viene aperto dal filesystem locale (URL che inizia con file://), il browser impedisce di caricare altri file come i JSON degli scenari. È una protezione contro script malevoli.

Il server locale aggira questa limitazione servendo i file tramite HTTP (URL che inizia con http://). È lo stesso protocollo usato dai siti web, quindi il browser permette il caricamento.

Questa limitazione esiste solo in locale. Una volta pubblicato su un server web (GitHub Pages, hosting aziendale), tutto funziona normalmente.

Porte e conflitti

Il server usa di default la porta 8000. Se quella porta è già occupata da un altro programma, appare un errore.

Per usare una porta diversa:

python -m http.server 8080

Ricordare di aggiornare l'indirizzo nel browser: http://localhost:8080/choicemap.html.

Struttura delle cartelle

Non è necessario mantenere tutti i file nella stessa cartella, ma semplifica la gestione. La struttura consigliata è:

choicemap/
├── choicemap.html
├── scenario-editor.html
├── theme-editor.html
├── config.json
├── defaults.json
├── theme.json
├── scenario-mio-progetto.json
├── theme-azienda.json
└── docs/
    └── (file PDF, risorse)

Se si preferisce organizzare diversamente, ad esempio mettendo i file JSON in una sottocartella, è necessario aggiornare i percorsi in config.json.