Aggiungere Google Maps ad una pagina web

In questo tutorial vedremo come incorporare il celebre servizio Google Maps ad una pagina web. Il codice è allineato alle seconda versione della API di Google Maps.

Prima di iniziare

Il servizio è disponibile gratuitamente ma occorre avere una API Key, ovvero un codice alfanumerico che identifica univocamente l'URL (o una sottopagina di questo URL) che andrà ad utilizzare le mappe.

È possibile richiedere una API Key tramite la pagina Sign up for the Google Maps API, indicando l'indirizzo per il quale si ha intenzione utilizzare il servizio (per es. http://www.deelan.com/) e cliccare Generate API Key. Verrà generata una stringa di lettere e numeri piuttosto lunga, è consigliabile tenerla a portata di mouse, ci servirà a breve.

Inserire il codice HTML

Il codice HTML che occorre inserire nella pagina si riduce ad un elemento div che funge da segnaposto per la mappa. All'interno del div è stato inserito un avviso nel caso il codice di Javascript non possa essere eseguito. 

<div id="map">
  Your browser doesn't support Google Maps or Javascript is turned off.
</div>

Inserire il codice Javascript

Copiamo nell'elemento head della pagina la linea seguente. 

<script src="http://maps.google.com/maps?file=api&v=2&key=API-KEY-QUI" type="text/javascript"></script>

La dicitura API-KEY-QUI va sostituita con la API Key vera e propria. Questo blocco script che punta al sito di Google ha il compito di importare nella pagina tutto il codice Javascript necessario per gestire le mappe.

Il secondo blocco di Javascript da aggiungere è quello che verrà intergrato più avanti con le istruzioni per personalizzare la mappa. Per il momento la funzione showMap si limita a creare la mappa, centrarla su Roma e impostare uno zoom di fattore cinque utilizzando il metodo GMap2.setCenter (doc). 

<script type="text/javascript">
    //<![CDATA[
    function showMap()
    {
        if (GBrowserIsCompatible()) {
            
            // Ottiene l'elemento della pagina chiamato "map" (il DIV) 
            //   e crea la mappa utilizzandolo come contenitore.
            var map = new GMap2(document.getElementById("map"));                
            
            // Aggiunge dei controlli per lo zoom e lo spostamento 
            map.addControl(new GSmallMapControl());	            
            
            // Centra la mappa su Roma, con uno zoom di 5 
            map.setCenter(new GLatLng(41.896655,12.495918), 5);
        }
    }
    //]]>
</script>

A questo punto è naturale chiedersi dove siano stati reperiti i valori di latitudine 41.896655 e longitudine 12.495918 di Roma. Sia Google Earth che Google Maps permettono di ricavare tali coordinate.

Utilizzando Google Maps il procendimento è il seguente: una volta individuato il punto nella mappa che ci interessa doppiocliccamoci sopra, la mappa verrà centrata sul punto cliccato ed il link mostrato in Collegamento a questa pagina avrà un indirizzo simile a http://maps.google.com/maps?f=...ll=41.896655,12.495918...om=1. Il valore del parametro ll sono le coordinate che quali date in pasto all'oggetto GLatLng (doc) e di seguito al già citato GMap2.setCenter centreranno la mappa sul punto desiderato.

L'ultimo passaggio consiste nell'istruire il browser su cosa fare durante il caricamento e lo "scaricamento" della pagina. Aggiungiamo quindi a body i due attributi onload e unload. Il primo si occuperà di chiamare la nostra funzione showMap, il secondo invocherà la funzione GUnload di Google Maps quando il browser lascia la pagina che contiene la mappa. 

<body onload="showMap();" onunload="GUnload()">

Ora non ci resta che ricaricare la pagina e gustarci il frutto del nostro lavoro. Se tutto è andato per il verso giusto dovrebbe apparire nella pagina una mappa simile a questa.

Aggiunta di un marker

Vediamo ora come aggiungere un marker per individure un punto sulla mappa e associarci una descrizione.

Innanzi tutto all'interno di showMap scriviamo una funzione di utilità chiamata createMarker. Questa raggruppa il codice necessario per creare un nuovo oggetto GMarker (doc) e associare a questo un handler per l'evento click. Visto che vogliamo appaia una descrizione quando il marker viene cliccato nell'handler invocheremo il metodo GMarker.openInfoWindowHtml, passandogli del testo tramite la variabile description. 

function showMap()
{
    if (GBrowserIsCompatible()) {
        
        // codice di setCenter, ecc.
    
        // Crea un nuovo marker nel punto specificato 
        //   con una descrizione HTML associata
        function createMarker(point, description) {
          var marker = new GMarker(point);
          GEvent.addListener(marker, "click", function() {
            marker.openInfoWindowHtml(description);
          });
          return marker;
        }
    }
}

Ora non ci resta che chiamare la funzione createMarker, passandogli coordinate e descrizione per il nostro marker. Il codice seguente va inserito dopo il corpo di createMarker ma sempre all'interno di showMap. 

function showMap()
{
    if (GBrowserIsCompatible()) {
        
        // codice di setCenter, ecc.        
        // codice di createMarker
        
        map.addOverlay(
            createMarker(new GLatLng(41.896655,12.495918), "<b>Roma</b>, Italia")
        );       
    }
}

Il codice crea una mappa simile a questa. Come si può constatare il marker è cliccabile e la descrizione viene interpreata dal browser come codice HTML.

Si possono creare quanti marker si desideri, è sufficiente chiamare createMarker con delle nuove coordinate e di seguito Gmap2.addOverlay per aggiungere il nuovo oggetto alla mappa.

Conclusione

Siamo arrivati alla fine di questo tutorial ma siamo solo all'inizio dell'esplorazione di Google Maps. Le possibilità di utilizzo e personalizzazione del servizio sono pressoché illimitate ma è evidente che per utilizzi più spinti è richiesta una buona conoscenza di Javascript e delle classi documentate.

Riferimenti

— Andrea Peltrin, Giugno 2006.