## Guigen - Per iniziare

Questa mini-guida ha l'obiettivo di illustrare i passi necessari per impostare un progetto di generazione guigen. Si dà per scontata la corretta installazione del bundle eclipse-galileo e dei plugin mddtools e la dimestichezza con le funzionalità di base dell'IDE eclipse.

La struttura di un workspace tipicamente è costituita da:

1. un progetto generatore (tecnologia mdd)
2. un progetto target, contenente il progetto java che realizza l'applicativo vero e proprio (tecnologia j2ee)

Il flusso di lavoro tipico dello sviluppo in modalità mdd è costituito dai seguenti passi:

1. modellazione dell'applicazione, ottenuta editando i file di modello nel progetto generatore;
2. generazione del progetto target a partire dai file di modello
3. completamento del progetto target mediante codifica manuale nelle regioni protette
4. build del progetto target, deploy, test
5. ritorno al passo (1) se è necessario modificare caratteristiche modellabili dell'applicazione (es. correggere una label, aggiungere un widget, etc..) oppure al passo (3) se è necessario apportare delle correzioni alla logica di business scritta nelle regioni protette

E' importante notare che, affinchè questo flusso iterativo unidirezionale (round trip) vada a buon fine è necessario prestare molta attenzione a non modificare manualmente porzioni di codice generato non contenute in regioni protette: in caso contrario le modifiche apportate manualmente in aree non consentite sono irrimediabilmente perse alla rigenerazione successiva. Generalmente questa limitazione non costituisce un problema in quanto la struttura del codice generato è stata pensata appositamente con l'obiettivo di concentrare le aree di intervento manuale allo stretto indispensabile. Viceversa, una modifica arbitraria al di fuori delle regioni protette può compromettere il funzionamento dell'applicativo.

In sintesi i passi da compiere al fine di predisporre un progetto guigen sono i seguenti:

1. impostare il progetto generatore
   1. creare un progetto generatore (tecnologia mdd)
   2. aggiungere le dipendenze dei plugin mddtools
   3. creare la struttura delle directory destinate a contenere i modelli e gli script di generazione
2. creare i modelli dell'applicazione
   1. importare nel progetto i modelli comuni (commonTNS.guigen e commonAppdata.guigen)
   2. creare il modello principale dell'applicativo impostando le informazioni principali
   3. creare il modello di un AppModule dove sarà inserito il ContentPanel destinato ad essere la home page dell'applicativo
   4. creare una home page minimale
3. impostare il progetto java target
4. impostare il workflow di generazione
5. eseguire la generazione
6. configurare, compilare e deployare il progetto generato

E' possibile scaricare i sorgenti completi del progetto generatore e del progetto generato qui

### impostare il progetto generatore

#### creare un progetto generatore (tecnologia mdd)

Per creare il progetto generatore è necessario utilizzare l'apposito wizard per progetti Xpand, che si attiva selezionando in Eclipse la voce di menu:

`[File] -> [New] -> [Other...] -> [Xpand] -> [Xpand Project]`

Inserendo nel campo `[Project name]` il nome del progetto generatore, che solitamente è costituito da:

`<cod_prodotto>mdd`.

occorre inoltre, nella sezione Meta Models, lasciare selezionata l'opzione `Use workspace defaults`.

Sarà generata una struttura simile a quella riportata in figura (nell'esempio il codice prodotto utilizzato è myprod

).

#### aggiungere le dipendenze dei plugin mddtools

Per aggiungere al progetto generatore le dipendenze necessarie è necessario agire nella apposita schermata alla quale si accede tramite doppio click sul file `META-INF/MANIFEST.MF`

I plugin da aggiungere sono:

- `guigen`
- `guigen.editor`

Al termine dell'operazione la schermata apparirà come in figura:

#### creare la struttura delle directory del progetto generatore

Predisporre la struttura di folder del progetto generatore secondo lo schema rappresentato in figura:

Come si può notare sotto la cartella `src` sono definite due cartelle:

- `model`: contiene i modelli dell'intero prodotto
- `workflow`: contiene gli script del workflow di generazione dell'intero prodotto

Entrambe le cartelle sono ulteriormente strutturate secondo la struttura del prodotto, ovvero con una sottodirectory per ogni componente di rilascio prevista dal prodotto. Questa strutturazione permette di avere un unico progetto generatore che può generare uno o più componenti di prodotto.

### creare i modelli dell'applicazione

Una volta predisposta la struttura del progetto il passo successivo è rappresentato dalla creazioen dei modelli che descrivono l'applicazione.

#### importare nel progetto i modelli comuni

Il primo passo da compiere è rappresentato dalla creazione dei due file di libreria `commonTNS.guigen` e `commonAppdata.guigen`. E' importante notare che questi file sono condivisibili da più di un modello di applicazione guigen: per questo motivo è consigliabile posizionare i file nella cartella dei modelli relativa al prodotto e non nella cartella relativa al componente web.

Per creare i due file in questione è necessario utilizzare un apposito wizard, che si attiva selezionando da eclipse la voce di menu:

`[File] -> [new...] -> [other...]`

E selezionando tra i wizard disponibili il wizard "Librerie standard per modelli GUIGEN", disponibile nella cartella "guigen wizards".

A questo punto è necessario impostare nel campo `[container]` il percorso del folder dei modelli comuni a tutto il prodotto (nell'esempio: `myprodmdd/src/model/myprod`). Il wizard terminerà e saranno creati i due file di libreria.

#### creare il modello principale dell'applicativo

Il modello principale dell'applicativo deve essere creato tramite l'apposito wizard, che si attiva selezionando da eclipse la voce di menu: `[File] -> [new...] -> [other...]`

E selezionando tra i wizard disponibili il wizard "Guigen model(modello principale GUIModel)", disponibile nella cartella "guigen wizards".

Nella prima schermata del wizard è necessario impostare il percorso della cartella dove deve essere creato il file che, essendo un file specifico del componente web, è rappresentato dalla cartella omonima (nell'esempio: `mycomp`) e il nome del file stesso, che deve essere nel formato `<cod_componente>.guigen`.

Nella seconda schermata è impostato il Tipo Modello GUIModel, corrispondente alla classe dell'elemento che deve essere creato come root del modello.

Nella terza schermata è necessario inserire le informazioni identificative del componente, ovvero:

- codice anaprod del prodotto (tutti caratteri minuscoli)
- versione del prodotto
- codice anaprod del componente (tutti caratteri minuscoli)
- versione del componente

Nella quarta schermata è necessario inserire alcune informazioni generali dell' applicativo, ovvero:

- Dati Header per Configurazione Portale (vedere documentazione della classe Header):
  - Codice Applicativo come codificato sul portale
  - Codice Canale all' interno del portale
  - Link Canale ossia il link alla home page del canale temantico
  - Nome Applicativo ossia il nome descrittivo dell'applicazione
  - Noma Canale ossia il nome descrittivo del canale tematico
- Configurazione piattoforma di deploy (TargetPlatform): scegliere se si desidera generare un applicazione web deployabile sotto Weblogic 9.2 (codice WLS92) oppure sotto JBoss 43 (codice JBoss43)
- Abilitazione Arricchimenti

Nella quinta schermata è necessario inserire la posizione della cartella nella quale sono stati creati i due file di libreria `commonTNS.guigen` e `commonAppdata.guigen`.

Al termine dell'esecuzione del wizard sarà creato lo scheletro del modello dell'applicazione, che referenzierà i due file di libreria.

#### creare il modello di un AppModule

Il passo successivo è rappresentato dalla creazione di un AppModule destinato a contenere la home page dell'applicativo. Per fare ciò è necessario creare un apposito file di modello tramite il wizard "Guigen model(moduli specifici da associare al modello principale)", disponibile nella cartella "guigen wizards", che si attiva selezionando da eclipse la voce di menu

`[File] -> [new...] -> [other...]`

in alternativa è attivabile dal menu contestuale sul modello principale (in questo modo verrà creata in automatico l'associazione tra modello principale e il nuovo AppModule)

`[new...] -> [other...]`

Nella prima schermata del wizard è necessario impostare il percorso della cartella dove deve essere creato il file.

Nella seconda schermata è necessario selezionare nella combo `Tipo Modello` l'elemento AppModule e definire il nome. Supponiamo che tale AppModule si chiami home.

Nella terza schermata sarà richiesto di specificare il path del modello principale in cui dovrà essere referenziato il nuovo AppModule. Quindi sul modello principale il modulo home appena creato verrà aggiunto nell' elenco dei moduli esterni (ext modules) del nodo ApplicationArea.

Al termine dell'esecuzione del wizard verrà aperto l'editor del file di modello appena creato.

#### creare una home page minimale

E' ora necessario modellare la home page all'interno dell'AppModule home. Per semplicità nell'esempio si creerà un pannello senza widget (vuoto) con layout verticale.

Per modellare la home-page è necessario eseguire i seguenti passi:

1. creare un nuovo ContentPanel nell'AppModule, selezionando il nodo AppModule nell'albero dell'editor strutturato e azionando con il tasto destro del mouse la voce `[new child]->[content panel]`
2. impostare l'attributo name del content panel tramite la finestra delle properties (utilizzare, ad esempio, il nome cpHome)
3. creare il FormPanel principale, selezionando il nodo relativo al ContentPanel nell'albero dell'editor strutturato e azionando con il tasto destro del mouse la voce `[new child]->[form panel]`
4. impostare l'attributo name del nuovo FormPanel ad esempio a pMain, e l'attributo label ad esempio a "Pagina iniziale dell'applicativo"
5. impostare il layout verticale del FormPanel selezionando il nodo corrispondente nell'albero dell'editor strutturato e azionando con il tasto destro del mouse la voce `[new child]->[vertical flow panel layout]`
6. salvare il modello

A questo punto il modello della home page dovrebbe apparire come nella figura seguente:

Per referenziare la home page nel modello principale dell'applicativo è necessario impostare l'attributo home page dell'elemento ApplicationArea in modo che punti al ContentPanel home, selezionandolo tramite la apposita lista di selezione Al termine delle operazioni il modello principale apparirà come nella figura seguente:

A questo punto il modello (seppur molto semplice) è pronto per una prima generazione.

### impostare il progetto java target

Il progetto java che sarà generato è un comune progetto java che rispecchia gli standard di alberatura e build. Di conseguenza è sufficiente creare un nuovo Java Project in eclipse, nello stesso workspace nel quale è presente il progetto generatore. Il nome del progetto java, secondo gli standard, dovrà corrispondere al nome del componente di prodotto corrispondente (nell'esempio: mycomp). A completamento dell'operazione di creazione si consiglia di:

- impostare la cartella di output (default output folder) in modo che punti alla directory `build/classes` (come previsto da standard)
- impostare la cartella dei sorgenti java in modo che punti alla directory `src/java`, come previsto da standard

Al termine dell'operazione l'alberatura del workspace dovrebbe risultare come rappresentato nella figura seguente:

### impostare il workflow di generazione

Il processo di generazione è comandato da un workflow di generazione descritto da un apposito script di workflow MWE. Questo engine di generazione permette di costruire workflow anche molto sofisticati. Il minimo workflow necessario deve prevedere alcuni passi:

1. la verifica dei singoli modelli
2. la generazione del modello principale

Per creare lo script di generazione è necessario posizionare il mouse sulla cartella relativa al componente mycomp all'interno della cartella `src/workflow`e, tramite tasto destro, azionare il wizard di creazione di un nuovo file `Workflow file`: `[New] -> [Other] -> [Modeling Workflow Engine] -> [Workflow File]`

A questo punto è sufficiente copiare il seguente snippet di codice (avendo cura di modificare se necessario i puntamenti ai file di modello o il nome del progetto target):

        	<?xml version="1.0"?>
        	<workflow>

        	<!-- test del modulo "home" -->
        	<cartridge file="it/csi/mddtools/guigen/workflow/guigenCheck.mwe"
    			model="myprodmdd/src/model/myprod/mycomp/modules/home_module.guigen"
    			portal="neutral"
        	/>

        	<!-- test del modello principale -->
        	<cartridge file="it/csi/mddtools/guigen/workflow/guigenCheck.mwe"
    			model="myprodmdd/src/model/myprod/mycomp/mycomp.guigen"
    			portal="neutral"
        	/>

        	<!-- generazione del codice -->
        	<cartridge file="it/csi/mddtools/guigen/workflow/struts2Basic.mwe"
    			model="myprodmdd/src/model/myprod/mycomp/mycomp.guigen"
    			targetProjectName="mycomp"
    			portal="neutral"
        	/>
        	</workflow>

Come si può notare nel workflow sono richiamate due cartridge fornite con il plugin guigen:

- guigenCheck.mwe: permette la verifica semantica del modello
- struts2Basic.mwe: genera l'applicazione in tecnologia struts2 + spring

Nel caso il progetto sia costituito da più modelli di quelli presenti nell'esempio la cartuccia guigenChack.mwe deve essere richiamata su tutti i singoli modelli. Non è infatti sufficiente richiamare la verifica sul modello principale. Nell'esempio non &egravE; necessario, in quanto non sono state apportate modifiche alla struttura iniziale, ma anche il file contenente il modello di sicurezza (securityModel.guigen) dovrebbe essere soggetto a check.

Riguardo all'ultima cartridge configurata, ovvero quella di generazione, è ancora importante spiegare il significato dell'attributo portal: a seconda del valore di questo attributo verrà generato codice coerente con gli standard dei vari portali. I valori ammessi sono descritti nella tabella seguente:

valore | descrizione | gestione risorse grafiche
sisp | generazione view coerente con gli standard del sito "sistema piemonte" | le risorse grafiche sono mantenute sul web server del sito, header e footer sono incluse tramite remote include
intranetrp | generazione view coerente con gli standard del sito intranet della regione piemonte | le risorse grafiche sono contenute nel pacchetto applicativo, header e footer sono incluse nel pacchetto
rupar | generazione view coerente con gli standard del sito "rupar piemonte" (vecchia versione) | le risorse grafiche sono mantenute sul web server del sito, header e footer sono incluse tramite remote include
newrupar | generazione view coerente con gli standard del sito "rupar piemonte" (nuova versione) | le risorse grafiche sono mantenute sul web server del sito, header e footer sono incluse tramite remote include
neutral | generazione view indipendente dal portale di installazione (xhtml "universale") | le risorse grafiche sono contenute nel pacchetto applicativo, header e footer sono incluse nel pacchetto

Nell'esempio, per semplicità, la geenrazione è stata configurata per utilizzare la cartuccia neutral: in questo modo non sarà necessario avere a disposizione le risorse statiche dell' applicativo. Per un utilizzo in un progetto reale occorre verificare quale sia la "cartuccia" di geenrazione più adatta. Poichè la cartuccia neutral necessita di risorse grafiche (immagini/css) all' interno del pacchetto, è necessario includere nell'alberatura web uno skin adeguato. Per le esercitazioni/prove è sufficiente utilizzare lo skin "graybox" (non stilizzato) disponibile nello zip ris_neutral_graybox.zip: è sufficiente scompattare l'archivio, dopo la generazione del progetto, ed inserire la cartella `ris` all'interno della cartella `src/web/<nome_componente>`.

### eseguire la generazione

Per eseguire il workflow definito al passo precedente è sufficiente selezionare il file .mwe e, tramite tasto destro, azionare l'esecuzione (`[Run As] -> [MWE Workflow]`). Se i check e la generazione hanno successo la console presenterà il messaggio:
`INFO WorkflowRunner - workflow completed in ... ms!`
più eventuali warning.

Nel caso invece in cui vi siano degli errori nel modello, la console li presenterà al termine dell'esecuzione. Se ad esempio ci si scordasse di impostare la home page, nella console apparirebbe un messaggio simile al seguente:
`ERROR WorkflowRunner - Deve essere definito il content panel di homePage: [guigen::ApplicationArea, null] [it.csi.mddtools.guigen.impl.ApplicationAreaImpl@e3c624]`
In questo caso sarebbe necessario correggere gli errori sul modello e rilanciare la generazione.

Se la generazione ha avuto buon esito nel progetto target compariranno le risorse generate, ovvero:

- i sorgenti delle pagine JSP che costituiscono la view dell'applicazione
- i sorgenti java delle action struts2 che realizzano lo strato di controller e i bean spring che realizzano la business logic
- i file di configurazione j2ee
- i file di build del progetto

Il progetto mycomp dovrebbe dunque presentare un'alberatura simile a quella rappresentata in figura:

### configurare, compilare e deployare il progetto generato

Il progetto generato da guigen è un progetto standard CSI importato in un workspace eclipse: di conseguenza le operazioni di build/deploy del progetto sono quelle standard che si effettuerebbero con un progetto java generato manualmente. Come si può notare il progetto così generato presenta degli errori di compilazione in eclipse: ciò è dovuto alla ovvia mancanza delle librerie da cui dipendono i sorgenti java. Al fine di ottenere un progetto che compili senza errori nell'IDE è necessario dunque scaricare da repart, tramite ivy, tali librerie: questa operazione è realizzabile richiamando il task load-dependencies nello script di ant `build.xml` e, successivamente, impostare tali librerie nel build path. A tale scopo è importante notare che i build standard CSI necessitano dell'estensione per ivy 2.0. La configurazione di ANT in eclipse esula dagli obiettivi di questo tutorial.

TIP: è consigliabile, dopo ogni rigenerazione effettuare un clean del progetto target.

Prima di poter effettuare il build del progetto è necessario configurare le properties di configurazione del target di build: per far ciò è necessario creare i file di configurazione relativi ai target desiderati (es. `dev.properties`) a partire dal file `target_template_file.properties` e configurare i valori delle property necessarie. L'insieme delle property che sarà configurare variano a seconda degli elementi di modellazione inseriti, ad esempio a seconda del tipo di autenticazione/SSO previsto o a seconda della cartuccia di layout utilizzata.

A questo punto è possibile effettuare il build del progetto e installare il pacchetto generato nell'application server destinato ad ospitarlo. Per testare l'applicativo sarà sufficiente puntare da un browser alla root del contesto web (che ha lo stesso nome del componente, nell'esempio http://<hostname:port>/mycomp).

Il risultato atteso è quello rappresentato nella figura seguente.