# 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.