Add README (#2 )

Reviewed-on: #2
2026-09-03 14:58:52 +02:00
1 changed files with 134 additions and 0 deletions
@@ -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_<ID>.elx
+└── elxforms_<ID>_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 <TAG>` | Esporta il modulo e ne rigenera subito i contenuti estratti. |
+| `export-elx.bat <TAG>` | Esporta soltanto il file `.elx` dalla console. |
+| `extract-elx-internals.bat <TAG>` | 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 <URL_ASSOLUTO>` | 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_<ID>.elx`;
+5. sposta il file da `tools/selenium/downloads` a `src/<TAG>`.
+
+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.