135 lines
7.0 KiB
Markdown
135 lines
7.0 KiB
Markdown
# 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.
|