## Guida all'utilizzo delle funzioni cartografiche

### Introduzione

In guigen per utilizzare le funzionalità cartografiche è disponibile il widget MapView, grazie al quale è possibile presentare dati geografici e interagire con essi.

Le funzionalità a disposizione sono descritte nella scheda del widget MapView. In sintesi sono:

1. Visualizzazione di mappe (*)
2. Zoom e Pan interattivi
3. Esecuzione di logiche applicative a fronte di un click dell'utente su un punto della mappa (con la possibilità di utilizzare le coordinate del punto cliccato nella logica)
4. Riposizionamento della porzione visualizzata della mappa impostando le coordinate da Business Logic
5. Cambio dello sfondo (es. Satelite / Mappa)
6. Visualizzazione di geometrie su uno strato (layer) "acetato" sovrapposto alla mappa
7. Editing di geometrie sulla mappa o da Business Logic su layer "acetato" sovrapposto alla mappa

(*) attualmente sono utilizzabili solo le mappe fornite dalla piattaforma cartografica GREASE utilizzata in CSI-Piemonte.

Il widget MapView si appoggia, come strutture dati, ad un insieme di tipi specifici che sono definiti nel modello di libreria greaseTNS.guigen che contiene il TypeNamespace greasemapfacade.

### Funzialità base: Visualizzazione, Zoom e Pan

Per visualizzare una mappa è sufficiente utilizzare un widget MapView. E' necessario eseguire i seguenti passi:

1. Creare un WidgetPanel all' interno del pannello in cui è necessario visualizzata la mappa, tenendo conto che:
   - non è possibile inserire altri widget nel WidgetsPanel che contiene un MapView
   - occorre progettare la schermata tenendo conto dell'ingombro della mappa
2. Inserire il widget MapView nel WidgetPanel
3. Impostare i seguenti attributi del widget MapView:
   1. MapId e NumLevels: i valori devono essere forniti da chi si occupa dei servizi cartografici GIS
   2. Enable Enrichment deve essere impostato a true (il widget MapView è totalmente basato su javascript)
   3. DataType deve essere impostato con il Complex Type greasemapfacade::MappaWeb (vedere sezione sul binding per ulteriori informazioni)
4. Creare un ApplicationData di tipo greasemapfacade::MappaWeb, con durata USER_SESSION o SAME_PAGE; questo dato applicativo conterrà le informazioni di base sullo stato della mappa, quali ad esempio le coordinate correnti dell'envelope visualizzato, ed è utilizzato principalmente in modo trasparente dal framework cartografico.
5. Aggiungere un databinding al MapView e associarlo all' ApplicationData appena creato
6. Modellare tre oggetti MapEnvelope (startEnvelopeSpec, scaleEnvelopeSpec, maxEnvelopeSpec) come figli del nodo MapView e impostare i Point forniti da chi fornisce il servizio cartografico. Queste informazioni sono utilizzate per l'inizializzazione della mappa (envelope iniziale, chge definisce la porzione di mappa visualizzata; envelope massimo che si può raggiungere con la funzionalità di zoom out; granularità dei salti nelle operazioni di zoom)
7. Modellare, a fronte degli eventi impliciti di onInit (inizializzazione una-tantum della schermata, al primo ingresso nella schermata) o onEnter (ogni ingresso nella schermata) in modo che venga eseguuito un ExecCommand che dovrà occuparsi dell' inizializzazione dell' ApplicationData all' ingresso della schermata (ad esempio: preparaMappa).

Dopo aver lanciato il generatore dovremo inizializzare nel metodo preparaMappa l'appdata definito in precedenza invocando l'adapter al servizio cartografico, che è un bean di spring automaticamente generato a fronte della modellazione del widget MapView.

            ...
            mappa = mapAdapterMYMAPPA.getMap();
            theModel.setAppDatamappa1(mappa);
            ...

### Evento al click su un punto della mappa

Per abilitare questa funzionalità è necessario:

1. inserire un EventHandler con EventType CLICK
2. modellare un ExecCommand (con methodName che ad esempio vale onMapClick); è importante fare in modo che uno gei suoi OUTCOME esegua un RefreshViewCommand, pena il non funzionamento della logica.

Nella regione protetta corrispondente al metodo onMapClick è necessario poi implementare le necessarie logiche di business, sfruttando le coordinate del click (che sono disponibili nelle proprietà xclick, yclick dell'ApplicatonData associato al widget MapView).

### Riposizionamento programmatico della mappa (impostando le coordinate da Business Logic)

Nela caso in cui i requisiti richiedano un posizionamento da programma della porzione di mappa visibile (ad esempio per centrare una specifica area) è possibile farlo semplicemente impostando da logica le coordinate dell'envelope da visualizzare.

Per utilizzare questa funzionalità è necessario modellare un ExecCommand (con methodName che vale ad esempio moveMap). Il metodo moveMap deve:

- valorizzare le coordinate dell'envelope destinazione (quiello su cui si vuole riposizionare la mappa)
- impostare a true la property useCurrentEnvelope (per fare in modo che al successivo render della mappa vengano utilizzate tali coordinate.