add README

2026-09-03 14:46:49 +02:00
parent 73d4e01c26
commit ad1bef8d7e
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.