elixforms-moduli/README.md

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:

git clone https://gitea.unipr.it/elixForms/elixforms-moduli.git
cd elixforms-moduli

Avviare quindi la preparazione dell'ambiente:

.\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:

.\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:

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

.
├── 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.