Un selettore layer per OpenLayers 3

Il passaggio da OpenLayers 2 a OpenLayers 3 (OL3) avvenuto nel 2014, ha comportato delle differenze molto marcate tra le due versioni; non a caso è stato cambiato il major number della release! In pratica, il modello costruttivo di questa libreria JavaScript è stato profondamente aggiornato, facendo largo uso di WebGL e  molte delle sue API e delle sue classi sono state ridefinite; addirittura alcune presenti nella precedente versione 2 sono  scomparse. La conseguenza è che codice scritto per OpenLayers 2 nel 99% dei casi non funziona più con OpenLayer 3 e il suo riadattamento non è sempre così semplice; a volte conviene riscriverlo ex-novo.

Tra le classi molto usate,  ma non più riproposte nella nuova OL3, c’è il selettore layer (layer-switcher) di una mappa: il controllo che permette di selezionare quale mappa-base visualizzare come sfondo  (se ci sono più opzioni) e/o gli altri layers (overlays) su di essa rappresentati.

layer-switcher OL2

In OL2 questo era immediatamente realizzabile con il controllo OpenLayers.Control.LayerSwitcher(), ma un suo equivalente, al momento, non esiste più in OL3. Infatti gli sviluppatori di  OpenLayers, hanno preferito dare priorità all’aggiornamento di altre caratteristiche più sostanziali, come per esempio il rendering dei dati vettoriali e il supporto del 3D, trascurando altri aspetti più legati alla UI (User Interface) e lasciando che questi vengano implementati al di fuori del core del linguaggio, almeno nella prima fase di OL3.

E infatti così è successo. Molti controlli mancanti in OL3 sono stati sviluppati da terzi e alcuni sono diventati così diffusi che in pratica vengono spesso inclusi come librerie aggiuntive. E questo vale anche per il selettore layer.

Il layerswitcher di Matt Walker

Tra le diverse proposte open-source presenti in rete, qui vi  presento uno di quelli usati, tanto che potrebbe essere incluso nel core delle prossime release di OL3; si tratta del layer-switcher proposto  da Matt Walker, che è disponibile (documentazione, codice ed esempi) al seguente indirizzo: github.com/walkermatt/ol3-layerswitcher.
Vediamo allora come si usa e come si può adattare alle nostre esigenze.

La prima cosa da fare è andare nella sua pagina github  prima indicata e scaricare lo “zip” che contiene degli esempi e la libreria del layerswitcher. La libreria viene periodicamente aggiornata, quindi magari vi conviene di dargli una controllata di tanto in tanto, per vedere se sono usciti degli aggiornamenti.
walkermatt_layerswitch_github

Spacchettiamo lo zip e apriamo la cartella ol3-layerswitcher-master; qui troviamo innanzitutto il file README.md che contiene una descrizione minima del controllo e di come va usato e poi la cartella src che contiene i files fondamentali da includere nei nostri progetti per usare questo layerswitcher, cioè:

  • ol3-layerswitcher.js che definisce la classe (è una extend della classe ol.control.Control) con le sue proprietà ed i suoi metodi;
  • ol3-layerswitcher.css che ne definisce lo stile.

ol3-layerswitcher-master

Allora per usare questo controllo, nella nostra pagina web, oltre ai riferimenti al core di OL3 (.js e .css) dobbiamo indicare anche quelli con il percorso relativo di questi due files. Se per esempio, la posizione relativa è quella qui raffigurata:

ol3_exa_files

dentro il  file layerswitcher_esempio.html  scriveremo :

I gruppi di layer

Il funzionamento di questo controllo si basa sui gruppi di layer, cioè sulla classe di OL3 ol.Layer.Group. In genere si crea un gruppo per le mappe di base (basemap) e un gruppo per i layer vettoriali (overlays) oppure, se abbiamo una sola mappa di base, solo il gruppo dei vettori . In generale,  possiamo anche fare più di due gruppi e organizzare i layers a nostro piacimento.

Facciamo un semplice esempio, in cui rappresentiamo una mappa con due possibili basemap e tre layer vettoriali (qui usiamo tre file .geoJSON); queste sono le loro definizioni :

Notiamo che per le mappe base, abbiamo impostato la proprietà type: base, cosa  necessaria per il corretto funzionamento del layerswitcher, altrimenti la mappa viene considerata un overlay e, anche se compare nel selettore, non viene visualizzata correttamente. Inoltre  abbiamo impostato la proprietà visible : true solo per una (noi abbiamo scelto la OSM); il motivo è evidente:  essendo delle mappe opache, possono essere visualizzate una per volta. Allora  scegliamo quale vogliamo sia quella visibile di default all’apertura della pagina web.

Per i tutti i layers abbiamo definito un title: questo ci serve perchè è la descrizione  che verrà visualizzata nel selettore layer; quindi scriviamolo in modo sintetico ma che sia comprensibile per l’utente.

Ora definiamoci i due gruppi, facendo attenzione all’ordine con cui, dentro ciascun gruppo, scriviamo i layers, perché essi verranno visualizzati (nel layerswitcher) nell’ordine inverso. Così come abbiamo fatto per il layers, anche per ciascun gruppo definiamo un title che  è la descrizione con cui apparirà nel selettore.

A questo punto possiamo definire il nostro controllo layerswitcher e visualizzarlo nella mappa.
Notiamo come non sia necessario indicare quali layer esso deve includere, perché vengono considerati i gruppi-layer che abbiamo precedentemente definito. L’unica proprietà (facoltativa) che abbiamo definito è “tipLabel“:  la legenda che compare se si clicca sopra il controllo (tooltip).
L’ultima riga di codice (layerSwitcher.showPanel()) serve per scegliere se visualizzare il selettore appena si carica la pagina con la mappa.

Fatto! L’istantanea di cosa viene fuori è la seguente:

OL3 layerswitcher

dove nella reale visualizzazione, il pannello del layerswitcher compare/scompare spostandosi col mouse sopra il bottone in alto a destra. Se volete vedere l’esempio funzionante e l’intero codice OL3 che lo realizza (con la funzione “vedi sorgente pagina” del vostro browser) cliccate qui: esempio 1 OL3 layerswitch .

Organizziamo i layers

Allora, definire come i layers vengono visualizzati nel selettore è molto semplice: basta organizzare i gruppi e i loro layers scrivendoli nell’ordine che vogliamo. A tal proposito ricordiamo nuovamente che, i gruppi e i layers vengono elencati nel pannello del selettore, nell’ordine inverso a quello con cui li scriviamo. Poi con i rispettivi title decidiamo la didascalia che li descrive.

E’ bene precisare anche che i gruppi, vengono resi graficamente sulla mappa, nell’ordine in cui sono scritti nel codice. Questo vuol dire che, il gruppo delle basemaps va sempre scritto prima di quello dei layers che deve essere presentati in trasparenza su di esso; altrimenti le basemaps, che sono opache, coprono  gli altri layers e quindi impediscono di vederli. Per capirci meglio, scrivere nel seguente modo è sbagliato :

Un’altra cosa che possiamo fare è definire dei gruppi annidati.
Come esempio, qui  creiamo un sottogruppo delle basemaps fornite dal provider Stamen :

Il risultato sarà il seguente:

OL3 layerswitcher

Modifichiamo il CSS

Se abbiamo dimestichezza con il CSS, possiamo modificare a nostro piacimento l’aspetto grafico di questo selettore layer, intervenendo sul file ol3-layerswitcher.css.
Per esempio possiamo modificare i caratteri (font, colore, stile, dimensioni,…) delle scritte al suo interno (sia gruppi che layers) aggiungendo le relative proprietà nella classe .layer-switcher ul; per esempio :

Se invece vogliamo modificare solo le scritte dei gruppi, dobbiamo scrivere nella classe .layer-switcher li.group > label; per esempio:

Ancora, possiamo variare la grafica del pannellino, intervenendo sulla classe .layer-switcher .panel; così, per esempio, possiamo cambiare il colore dello sfondo e/o del bordo:

Consideriamo comunque che è bene lasciare il file ol3-layerswitcher.css inalterato, perché esso possa essere usato indifferentemente per diverse applicazioni. E invece è preferibile scrivere un  file .css  per ciascuna applicazione, modificando solo le classi e le proprietà (dell’originale ol3-layerswitcher.css) che servono, per ottenere l’aspetto grafico per quella applicazione. Quindi se per esempio chiamo questo file  miostile_layerswitcher.css, scriveremo :

Scroll verticale

Un’altra modifica utile che possiamo fare, consiste nel fissare l’altezza massima (in pixel) che può avere il selettore. Di default esso si allunga automaticamente per contenere tutti i  gruppi/layers in esso presenti; ma ciò può essere fastidioso se l’elenco è molto lungo! Per cambiare questa impostazione, basta scrivere qual’è la sua altezza massima nella classe .layer-switcher.shown  del CSS:

In questo modo il selettore, superata l’altezza da noi fissata, mostrerà automaticamente una barra di scorrimento verticale che ci permette di di visualizzare tutte le opzioni (layers) in elenco.

ol3_laysw_fig3

Ecco un altro esempio, con un layerswitcher di aspetto grafico personalizzato (anche con scroll verticale) e con la presenza di sottogruppi: esempio 2 OL3 layerswitcher.

Aggiungere layers in seguito

Può succedere che, dopo aver definito i gruppi di layers da mostrare nel layerswitcher, sia necessario aggiungerne altri in un secondo momento. Mi spiego meglio: questo non significa che ci serve farlo, perché ce ne eravamo dimenticati! In questi casi infatti basta banalmente rivedere il codice JS e ridefinire i gruppi (in ol.layer.Group(..)) inserendo il layer che ci era sfuggito.

L’esigenza è di altro tipo, ovvero può succedere che l’aggiunta del layer debba essere fatta in un altro momento di esecuzione del codice (successivo alla definizione dei gruppi per il layerswitcher) perché si è verificato un certo evento o una certa condizione. In altre parole è corretto che il layerswitcher abbia inizialmente un certo contenuto e poi successivamente debba variare (aggiungendo uno o più layer) per qualche motivo.

Per effettuare questa operazione usiamo il metodo getLayers() dell’oggetto ol.layer.Group ed il metodo push() della più generale classe ol.Collection (a cui l’oggetto ol.layer.Group appartiene).

Vediamo un esempio in cui supponiamo di avere definito inizialmente un  gruppo “overlays” con due layers (strade, edifici):

quindi il layerswitcher, fino a questo momento, mostra un gruppo “Overlays” con due sole opzioni/layers.

Ora supponiamo che a un certo punto (… perchè è successo qualcosa) vogliamo aggiungere a questo gruppo un nuovo layer  “fontanelle”:

quando verrà eseguita questa parte di codice, vedremo che nel gruppo “Overlays” del layerswitcher compare la terza opzione/layers. In questo  esempio 3 OL3 layerswitcher  potete vederne il funzionamento e notare che, quando per la prima volta appare il layerswitcher (appena la pagina web viene caricata) nel gruppo “Overlays” compaiono solo due opzioni, poi non appena si clicca dovunque sulla mappa, da quel momento in poi nel  layerswitcher compare anche la terza opzione.

Si può usare lo stesso metodo, anche per aggiungere successivamente  un nuovo gruppo (inizialmente non presente). In questo caso bisogna definire già da subito il gruppo, lasciandolo però “vuoto” (privo di layers). Quando poi vogliamo che compaia nel layerswitcher, basta aggiungere in esso uno o più layers. Qui un esempio di codice su come fare:

 

condividi: