## Guigen - Cartridges disponibili

In questo capitolo sono descritte le carucce (cartridge) di generazione disponibili.

Nota [1]: dalla versione 3.2 il parametro portal, che era presente dalla prima versione di guigen, è soppiantato dalla coppia di parametri templateName e templateVersion. Pertanto i progetti che utilizzavano l'impostazione portal="neutral" dovranno eliminare tale parametro e sostiutuirlo con la coppia di parametri:

- templateName="neutral"
- templateVersion="v1" (la "v" è minuscola)

In pratica portal="neutral" equivale a templateName="neutral" + templateVersion="v1". Per i dettagli circa i possibili valori dei nuovi parametri vedere sotto.

Nota [2]: la property `guigen.clientLibs.enableAutoServicePack` che permetteva di scegliere se abilitare o meno la possibilità di recepire automaticamente (ovvero senza dover aggiornare il plugin + rigenerare + rideployare) i fix critici apportati alle librerie JS successivamente alla data di pubblicazione del plugin, a partire dalla versione 3.2.0 di guigen non è più disponibile. Di conseguenza tutte le librerie che prevedono tale modalità (ad oggi "extjscsienricher" e "jqcsienricher") saranno sempre referenziate con la versione "latest" (es. "jqcsienricher/1.1.latest"). Eventuali impostazioni di tale property verranno semplicemente ignorate.

### cartuccia di verifica dei modelli

La cartuccia `it/csi/mddtools/guigen/workflow/guigenCheck.mwe` serve per effettuare il check semantico dei vari sotto-modelli e prevede i seguenti parametri:

parametro | descrizione | esempio | obbl/opz
model | percorso del file del modello guigen, a partire dalla root del workspace eclipse | `myprod.mdd/src/model/myprod/mycomp/myapp.guigen` | obbl
templateName | codice del template da utilizzare per generare il codice. sostituisce il vecchio parametro "portal". I valori possibili sono: neutral: nuova cartuccia con xhtml o html5 "universale" | `neutral` | obbl
templateVersion | a partire dallo stesso template (templateName) permette di creare delle versioni parzialmente diversificate. Di seguito i valori possibili, per ciascun valore di templateName: per il template neutral: v1: corrisponde alla classica cartuccia che si specificava nelle versioni precedenti tramite il parametro portal=neutral. Permette di generare codice xhtml o html5 arricchito con javascript (jquery o extjs) destinato ad un utilizzo di PC desktop o laptop, senza supporto specifico di dispositivi di immissione touch v2: corrisponde ad una variante della cartuccia neutral. Permette di generare codice html5 arricchito con javascript (solo jquery) destinato ad un utilizzo di PC desktop o laptop, o tablet, con supporto specifico di dispositivi di immissione touch (cosiddetta cartuccia "touch friendly") | `v1` | obbl

Esempio:

    <cartridge file="it/csi/mddtools/guigen/workflow/guigenCheck.mwe"
      model="myprod.mdd/src/model/myprod/mycomp/myapp.guigen"
      templateName="neutral"
      templateVersion="v1"
    />

### cartuccia di generazione prototipo di user interface

La cartuccia `it/csi/mddtools/guigen/workflow/guigenPrototype.mwe` serve per effettuare la generazione di un prototipo navigabile della user interface modellata. Il prototipo cos� ottenuto è permette di verificare:

- la struttura dei singoli ContentPanel in termini di widget, contenimento di pannelli, layout
- la logica di user interaction:
  - navigazione tra schermate a fronte di azioni utente (menu, pulsanti, eventi speciali)
  - attivazione di tab/step di wizard, multipanel
  - abilitazione/disabilitazione di widget
  - visibilità/invisibilità di widget

Il generatore produce un progetto Web Static Project da importare in eclipse oppure da visualizzare in un normale browser.

parametro | descrizione | esempio | obbl/opz
model | percorso del file del modello principale guigen, a partire dalla root del workspace eclipse | `myprod.mdd/src/model/myprod/mycomp/myapp.guigen` | obbl
targetProjectName | nome del progetto java nel quale si desidera generare il prototipo. deve appartenere allo stesso workspace del progetto generatore. Attenzione: deve essere un progetto differente da quello di generazione dell'applicazione effettiva. | `mycomp.prototype` | obbl

Esempio:

    <cartridge file="it/csi/mddtools/guigen/workflow/guigenPrototype.mwe"
      model="myprod.mdd/src/model/myprod/mycomp/myapp.guigen"
      targetProjectName="mycomp.prototype"
    />

Applicare prima le cartucce di check su tutti i modelli singolarmente, e poi applicare la cartuccia di generazione del prototipo.

### cartuccia di generazione completa dell'applicazione (modalità J2EE application)

La cartuccia `it/csi/mddtools/guigen/workflow/struts2Basic.mwe` serve per effettuare la generazione completa dell'applicazione, e prevede i seguenti parametri:

parametro | descrizione | esempio | obbl/opz
model | percorso del file del modello principale guigen, a partire dalla root del workspace eclipse | `myprod.mdd/src/model/myprod/mycomp/myapp.guigen` | obbl
templateName | codice del template da utilizzare per generare il codice. sostituisce il vecchio parametro "portal". I valori possibili sono: neutral: nuova cartuccia con xhtml o html5 "universale" | `neutral` | obbl
templateVersion | a partire dallo stesso template (templateName) permette di creare delle versioni parzialmente diversificate. Di seguito i valori possibili, per ciascun valore di templateName: per il template neutral: v1: corrisponde alla classica cartuccia che si specificava nelle versioni precedenti tramite il parametro portal=neutral. Permette di generare codice xhtml o html5 arricchito con javascript (jquery o extjs) destinato ad un utilizzo di PC desktop o laptop, senza supporto specifico di dispositivi di immissione touch v2: corrisponde ad una variante della cartuccia neutral. Permette di generare codice html5 arricchito con javascript (solo jquery) destinato ad un utilizzo di PC desktop o laptop, o tablet, con supporto specifico di dispositivi di immissione touch (cosiddetta cartuccia "touch friendly") | `v1` | obbl
targetProjectName | nome del progetto java nel quale si desidera generare l'applicazione. deve appartenere allo stesso workspace del progetto generatore | `mycomp` | obbl
jsPlatform | codice della piattaforma javascript d autilizzare per gli arricchimenti client-side. Poò valere: "jquery" = framework basato su JQuery, valido con templateName=neutral in qualsiasi versione "extjs" = framework basato su Sencha ExtJS 3.4 (deprecato e valido per templateName=neutral ma solo con versione "v1") | `jquery` | obbl
propertiesFile | percorso di un file di properties che può essere utilizzato per pilotare alcuni aspetti della generazione. Per un dettaglio delle properties supportate vedere più avanti | `src/workflow/myprod/mycomp/workflow.properties` | opz
useExternalDaoBeans | (dalla v.1.5) se impostato a true non viene generato il file dao-beans.xml, permettendo così di utilizzare il file generato da datagen. Il valore di default è: false | `true` | opz
extra-xpt | percorso di un file di template Xpand da utilizzare per: la configurazione dei template custom per la generazione full-code degli ExecCommand la configurazione di eventuali override di template esistenti . Nota: questa è una feature avanzata. | `template::myprod::mycomp::customTemplates.xpt` | opz

Esempio:

    <cartridge file="it/csi/mddtools/guigen/workflow/struts2Basic.mwe"
      model="myprod.mdd/src/model/myprod/mycomp/myapp.guigen"
      targetProjectName="mycomp"
      templateName="neutral"
      templateVersion="v1"
      propertiesFile="src/workflow/myprod/mycomp/workflow.properties"
    />

In un workflow completo è necessario applicare prima le cartucce di check su tutti i modelli singolarmente, e poi applicare la cartuccia di generazione.

E' disponibile anche una variante di questa cartuccia che permette di generare solo singoli moduli: `it/csi/mddtools/guigen/workflow/struts2BasicSingleModule.mwe`
Questa cartuccia permette di rigenerare solo una parte dell'applicazione (un'insieme ben definito di ApplicationModule) allo scopo di diminuire i tempi di generazione a fronte di modelli molto complessi. L'elenco degli ApplicationModule da rigenerare è gestita in un file di properties tramite la proprietà `generate-appmodules`. Occorre tenere presente che:

- questa cartuccia non deve essere utilizzata per generazioni che diano origine ad una baseline (di test o collaudo o esercizio), poichè vi � il rischio di mettere in baseline (o nel relativo tag SVN) una versione di codice generato non coerente con il modello (in caso di errori nella configurazione della lista di ApplicationModule
- se si utilizza questa cartuccia è necessario assicurarsi che la lista di ApplicationModule configurati contenga tutti gli ApplicationModule modificati nel modello

### cartuccia di generazione completa dell'applicazione (modalità J2EE Portlet/liferay)

La cartuccia `it/csi/mddtools/guigen/workflow/liferaystruts2.mwe` serve per effettuare la generazione completa dell'applicazione in modalità portlet, in modo che possa essere deployata nel portlet container liferay. I parametri e le modalità di utilizzo sono quelli previsti dalla cartuccia `struts2Basic`.

### Properties supportate

Il generatore GUIGEN supporta le seguenti properties

property | descrizione | esempio | cartuccia
`guigen.remoteresources` | scopo: serve per scegliere se generare header e footer come risorse interne all' applicativo (valore=false) oppure se reperirle come risorsa remota tramite remote-include (valore=true). default: false | false | struts2Basic.mwe e struts2BasicSingleModule.mwe con portal="neutral"
`guigen.enableEnrichmentsByDefault` | scopo: se impostato a true e se nel TargetPlatform del modello principale è impostato l'utilizzo delle funzioni ricche vengono abilitati di default gli arricchimenti per i widget per i quali non sia esplicitamente impostato a false la proprietà enableEnrichments; nel caso invece in cui questo parametro sia impostato a false, il valore di default di abilitazione arricchimenti è false. default: false | true | struts2Basic.mwe e struts2BasicSingleModule.mwe con portal="neutral", webres.mwe
`generate-appmodules` | scopo: serve per la generazione parziale. Se non impostata vengono generati tutti gli ApplicationModule. Se è impostata con una lista dei nomi di ApplicationModule vengono generati solo tali ApplicationModule. default: false | `modulo1,modulo2` | struts2BasicSingleModule.mwe
`guigen.fileUpload.maximumFileSize` | scopo: serve per impostare la dimensione massima (in byte) per il widget fileUpload. Se la property non viene specificata, Struts2 utilizza il default di 2Mb. Agisce come limite per il singolo file e non è differenziabile all'interno dell'applicazione. default: null | `4000000 (circa 3.8 Mb)` | struts2Basic.mwe e struts2BasicSingleModule.mwe
`guigen.fileUpload.totalMaximumFileSize` | scopo: serve per impostare la dimensione massima totale (in byte) per il widget fileUpload, nel caso di upload di file multipli . Se la property non viene specificata, si utilizza il default di 4524288 bytes, circa 4.3Mb. Agisce come limite per la dimensione totale dell'upload in una stessa schermata. default: null | `4000000 (circa 3.8 Mb)` | struts2Basic.mwe e struts2BasicSingleModule.mwe
`guigen.javaPackageOrganizationName` | scopo: serve per impostare un differente prefisso per i package java. se non impostato il prefisso di default è quello standard CSIPiemonte, ovvero it.csi. default: null | `com.acme` | struts2Basic.mwe e struts2BasicSingleModule.mwe
`guigen.ivyRepositoryHost` | scopo: serve per impostare un differente host come repository per ivy. Se non impostato l'host di default è quello standard CSIPiemonte, ovvero repart.csi.it. default: null | `myrepository.acme.com` | struts2Basic.mwe e struts2BasicSingleModule.mwe
`guigen.spring.autowire` | scopo: serve per impostare una differente strategia di autowire nello strato spring rispetto al default che è autodetect. default: autodetect | `vedere documentazione di spring` | struts2Basic.mwe e struts2BasicSingleModule.mwe
`guigen.html.mode` | scopo: serve per scegliere se renderizzare HTML dichiarato come xhtml (default) o html5. default: xhtml | `la modalità html5 è stata introdotta per permettere l'introduzione nel codice dei widget/panel user defined di elementi tipici di HTML5 (es. canvas).` | struts2Basic.mwe e struts2BasicSingleModule.mwe
`guigen.javac.encoding` | scopo: se impostato permette di utilizzare un particolare encoding in fase di compilazione java. default:(non impostato) |  | struts2Basic.mwe e struts2BasicSingleModule.mwe
`guigen.overridden.tar.filename.prefix` | scopo: se impostato permette di personalizzare il prefisso (prima del codice versione) del nome del file TAR. Se non impostato il prefisso è "${componente}srv". default:(non impostato) |  | struts2Basic.mwe e struts2BasicSingleModule.mwe

### Setup di plugin contenenti frammenti di modello

Per poter utilizzare nel proprio modello dei frammenti di modello (es. PanelDef, o TypeNamespace) contenuti in un plugin di estensione, è necessario configurare opportunamente il workflow di generazione, per fare in modo che il runtime di generazione riesca a risolvere i riferimenti a tali frammenti (che dovranno essere effettuati nei modelli tramite la sintassi `platform:/plugin/...`). A tale scopo è disponibile un componente da utilizzare nel file di workflow, prima delle componenti di check/generazione. Di seguito si riporta un esempio di utilizzo.

      <bean class="it.csi.mddtools.guigen.workflow.component.GuigenExtensionSetup" >
        <pluginName value="thirdpartyplugin" />
        <pluginVersion value="1.0.0.001" />
        <fragmentPath value="model/pdefplugin/pdefplugin/mypdef.guigen"/>
        <fragmentPath value="model/pdefplugin/pdefplugin/cartridge_1.xmi"/>
      </bean>

Dove:

- `pluginName` è il nome del plugin che contiene i frammenti da integrare
- `pluginVersion` è il codice completo di versione del plugin che contiene i frammenti da integrare
- `fragmentPath` contiene il percorso (relativo all'alberatura del plugin) di ciascun frammento da integrare

L'esempio in questione ad esempio permette di mappare i due frammenti con URI:

- `platform:/plugin/thirdparthyplugin/model/pdefplugin/pdefplugin/mypdef.guigen`
- `platform:/plugin/thirdparthyplugin/model/pdefplugin/pdefplugin/cartridge_1.xmi`

Per poter utilizzare questo componente di setup è necessario, inoltre, impostare la system property `eclipse.home` nella configurazione di lancio del workflow: