From ad1bef8d7e994e1e4ed85157590ffb85952e9367 Mon Sep 17 00:00:00 2001 From: Pier Paolo MAMMI Date: Thu, 3 Sep 2026 14:46:49 +0200 Subject: [PATCH] add README --- README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..51c8453 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# ElixForms Moduli + +Repository per l'archiviazione e il versionamento dei moduli ElixForms dell'Università di Parma. + +Il progetto automatizza l'esportazione dei moduli dalla console ElixForms e affianca a ogni file `.elx` una rappresentazione testuale dei suoi contenuti. In questo modo configurazioni, form, traduzioni e validazioni possono essere consultate e confrontate tramite Git senza dover analizzare direttamente il file di export completo. + +## Prerequisiti + +L'ambiente operativo previsto è Windows. Prima dell'installazione sono necessari: + +- Git; +- PowerShell 7.4 o successivo, disponibile tramite il comando `pwsh`; +- Node.js 20 o successivo, con `npm` disponibile nel `PATH`; +- Google Chrome, utilizzato in modalità headless per l'esportazione; +- accesso di rete alla console ElixForms UniPR e credenziali abilitate al backoffice. + +## Installazione e preparazione + +Clonare il repository e posizionarsi nella sua directory: + +```powershell +git clone https://gitea.unipr.it/elixForms/elixforms-moduli.git +cd elixforms-moduli +``` + +Avviare quindi la preparazione dell'ambiente: + +```powershell +.\setup-environment.bat +``` + +Lo script: + +1. richiede i valori mancanti per `ELIXFORMS_USERNAME`, `ELIXFORMS_PASSWORD` ed `ELIXFORMS_MODULE_TAG`; +2. salva la configurazione locale nel file `.env` in radice; +3. installa con `npm` le dipendenze degli strumenti presenti in `tools/extract-elx`, `tools/playwright` e `tools/selenium`. + +Il file `.env` è escluso da Git e non deve essere aggiunto al repository, perché contiene credenziali. `ELIXFORMS_MODULE_TAG` completa la configurazione richiesta dagli strumenti di automazione; i launcher di esportazione sostituiscono questo valore, solo per l'esecuzione corrente, con il tag ricevuto come argomento o inserito interattivamente. + +Per modificare successivamente la configurazione è possibile aggiornare `.env` oppure eseguire di nuovo `setup-environment.bat` dopo aver svuotato il valore interessato. + +## Utilizzo + +### Esportare ed estrarre un modulo + +Il comando principale esegue l'intero flusso per un tag ElixForms: + +```powershell +.\export-and-extract-elx.bat NOME_TAG_MODULO +``` + +Se il tag non viene specificato, il launcher lo richiede in modo interattivo. Il risultato viene salvato in: + +```text +src/NOME_TAG_MODULO/ +├── elxforms_.elx +└── elxforms__internals/ +``` + +È consigliabile controllare con `git diff` sia il file `.elx` sia la directory `_internals` prima di creare un commit. + +### Comandi disponibili + +| Comando | Funzione | +| --- | --- | +| `export-and-extract-elx.bat ` | Esporta il modulo e ne rigenera subito i contenuti estratti. | +| `export-elx.bat ` | Esporta soltanto il file `.elx` dalla console. | +| `extract-elx-internals.bat ` | Rigenera `_internals` per il modulo indicato. | +| `extract-elx-internals-last-updated.bat` | Estrae il file `.elx` modificato più di recente sotto `src`. | +| `extract-elx-internals-all.bat` | Rigenera i contenuti estratti di tutti i file `.elx` sotto `src`. | +| `convert-url-to-elix.bat ` | Converte un URL nel formato richiesto dalle chiamate remote/autocomplete di ElixForms. | + +I comandi che accettano un argomento possono essere avviati anche senza parametri; in tal caso ne richiedono il valore da tastiera. + +## Struttura del repository + +```text +. +├── src/ # Moduli esportati e relative rappresentazioni estratte +├── scripts/ # Orchestrazione PowerShell e funzioni condivise +├── tools/ +│ ├── extract-elx/ # Scomposizione del JSON .elx +│ ├── selenium/ # Automazione dell'export dalla console +│ └── playwright/ # Implementazione alternativa dell'automazione +├── .env.template # Elenco delle variabili di configurazione +├── setup-environment.bat # Preparazione iniziale +└── *.bat # Comandi operativi eseguibili da Windows +``` + +Ogni sottodirectory immediata di `src` identifica normalmente un modulo tramite il suo tag. Al suo interno si trovano l'export originale e la directory derivata con suffisso `_internals`. + +## Funzionamento tecnico + +### Esportazione dalla console ElixForms + +I file `.bat` si posizionano nella radice del repository e delegano il lavoro agli script PowerShell in `scripts`. Le funzioni condivise sono raccolte in `scripts/elx-tools-module.psm1`. + +Durante l'esportazione, PowerShell legge le credenziali da `.env`, applica il tag ricevuto dal comando e avvia lo strumento Selenium con le variabili d'ambiente necessarie. Selenium apre Chrome in modalità headless e svolge queste operazioni: + +1. accede al backoffice ElixForms UniPR; +2. cerca il modulo tramite il tag; +3. apre la funzione di esportazione e include i dati di protocollo; +4. scarica il file `elxforms_.elx`; +5. sposta il file da `tools/selenium/downloads` a `src/`. + +Se la directory del tag non esiste, viene creata automaticamente. La ricerca usa il primo risultato restituito dalla console: è quindi importante utilizzare un tag completo e non ambiguo. + +Il percorso richiamato dai launcher usa Selenium. In `tools/playwright` è mantenuta anche un'implementazione alternativa dello stesso flusso, non collegata ai comandi `.bat` principali. + +### Estrazione dei contenuti `.elx` + +Un file `.elx` è un documento JSON che contiene, nelle proprietà di primo livello, molte parti eterogenee del modulo. Lo strumento Node.js `tools/extract-elx/extract-elx.js` lo scompone in una directory omonima con suffisso `_internals`. + +Per ciascuna proprietà radice: + +- le stringhe XML sono riconosciute e formattate in file `.xml`; +- le altre stringhe sono salvate come `.txt`; +- gli oggetti sono serializzati come JSON indentato; +- gli array producono un indice e un file separato per ogni elemento; +- eventuali frammenti XML contenuti negli oggetti vengono estratti anche in file dedicati. + +Per alcune collezioni, tra cui step, tab, schemi, validazioni e traduzioni, i nomi dei file derivano da identificatori funzionali contenuti nei dati. Gli elementi vengono inoltre ordinati quando è disponibile una chiave significativa. Questi accorgimenti mantengono stabile l'output tra due esportazioni e rendono i diff Git più leggibili. + +Ogni estrazione genera anche: + +- `_manifest.json`, con tipo e numero di file prodotti per ciascuna proprietà; +- `crc32.txt`, con il checksum CRC32 del file `.elx` sorgente; +- file `index.*` che rappresentano valori singoli o descrivono il contenuto delle collezioni. + +Gli script PowerShell richiamano l'estrattore con l'opzione `--clean`: la directory `_internals` esistente viene eliminata e ricreata a partire dal file `.elx`. Di conseguenza, non deve contenere modifiche manuali da preservare; la sorgente autorevole resta l'export `.elx` ottenuto dalla console. + +### Conversione degli URL + +`convert-url-to-elix.bat` trasforma un URL assoluto nel formato usato dai servizi remoti ElixForms. Il dominio e il percorso vengono normalizzati secondo la convenzione della piattaforma, mentre i parametri di query vengono conservati, nello stesso ordine, nell'oggetto JSON restituito dal comando.