Volver al indice

Capítulo 3: Overlays

En este capítulo vamos a ver una serie de objetos llamados ”Overlay” tome la decisión de llamarlos por su nombre en ingles, porque no me gusta la traduccion a español que vendría siendo algo como “Superposiciones”. Para ser sincero no me gusta nada como suena, así que de ahora en adelante en el libro los llamaremos “overlays”

¿ Qué son los overlays ? La mejor respuesta a esta pregunta, es que nos da google en su API :

”Los overlays son objetos del mapa que están vinculados a coordenadas de latitud y longitud, por lo que se mueven al arrastrar el mapa o aplicar el zoom sobre él. Los overlays son los objetos que ‘añades’ al mapa para designar puntos, líneas, áreas o grupos de objetos.”

En resumen los overlays son objetos que podemos incluir en el mapa, para localizar puntos de interés geográficamente. Después de todo para eso es que sirven un mapa no?

A continuación veremos los distintos overlays que podemos usar.

Overlay : Marker.

El overlay marker es el objeto básico para localizar un punto en el mapa, dependiendo de la versión de Google Maps el icono de un marker puede variar. Al momento de escribir este libro el icono predeterminado es este :

Si revisamos la documentación de Google Maps vemos que podemos crear un overlay marker usando la clase google.maps.Marker, que recibe como parámetro un objeto donde tienen que estar definidas las opciones de nuestro marker. Entre todas las opciones que tenemos para escoger, estas son las más importantes:

position : Es la posición en el mapa donde queremos localizar nuestro marker y recibe como parámetro un objeto latLng.

map (opcional) : Es el mapa en el cual queremos que aparezca nuestro marker, ya que en una aplicación web podemos tener más de un mapa cargado. Una cosa importante aquí es que si no especificamos el mapa, se creará el marker pero no aparecera en ningun mapa.

Para los ejemplos siguientes usaremos los archivos de practica numero “3”, en el cual tenemos a nuestra disposición un botón llamado ”click me”, para ejecutar nuestro código. Recuerda copiar y pegar los códigos de ejemplo en el evento click del botón.

Primero crearemos un marker con un click en el botón.

$('#actionButton').on('click',function() {
    var marker = new google.maps.Marker({
        position: new google.maps.LatLng(-34.397, 150.644),
        title : "Hola soy el marcador",
        map: map
    });
});

Como puedes ver usamos la clase “google.maps.Marker” para crear nuestro maker y estamos pasando como parámetro un objeto con 3 propiedades básicas para ver nuestro marker.

Para la propiedad “position”: se ha creado un objeto latLng, que representa la posición geográfica a señalar.
Para la propiedad ”map”: pasamos nuestra variable global map.
La propiedad “title” es un tooltip que aparece cuando el cursor del mouse esta sobre el marker, muy útil para mostrar alguna información relevante.

Si das click en el botón, aparecerá el marker en el mapa.

Cambiando el icono del marker

Si por alguna razón quieres cambiar el icono de tu marcador, puedes hacerlo usando la propiedad llamada “icon”, donde puedes usar la url de alguna imagen.

Por ejemplo:

$('#actionButton').on('click',function() {
   var urlImg = 'http://gmaps-samples.googlecode.com/svn/trunk/markers/green/blank.png';
   var marker = new google.maps.Marker({
           position: new google.maps.LatLng(-34.397, 150.644),
        title : "Hola soy el marcador",
        icon:urlImg,
        map: map
   });
});

Como puedes ver solo hemos pasado una URL, que fue guardada en la variable “urlImg” a la propiedad “icon”, que acepta una URL de imagen válida para el icono del overlay marker.

Existen sitios web donde puedes encontrar iconos para tus overlay marker, algunos son :

En el link numero 2 puedes encontrar como configurar iconos con texto y color, construyendo una URL con los parámetros descritos en la documentación. Por ejemplo la siguiente URL crea un pin rojo con una letra A:

https://chart.googleapis.com/chart?chst=d_map_pin_letter&chld=A%7CFF0000%7C000000

El API Google Maps ofrece algunos símbolos integrados en la API que se pueden mostrar en overlays marker o polyline. Los símbolos predeterminados incluyen un círculo y dos tipos de flechas. Ejemplo :

$('#actionButton').on('click',function() {
    var arrow = {
        path: google.maps.SymbolPath.FORWARD_OPEN_ARROW,
        scale: 5
    };
   var marker = new google.maps.Marker({
          position: new google.maps.LatLng(-34.397, 150.644),
        title : "Hola soy el marcador",
        icon: arrow ,
        map: map
   });
});

Para usar estas formas, tenemos que crear un objeto “google.maps.Symbol”. Con la propiedad “scale” controlas el tamaño del símbolo y en la propiedad “path” pasamos una de las constantes de “google.maps.SymbolPath” de las siguientes:

Nombre	Descripción	Ejemplo
google.maps.SymbolPath.CIRCLE	Un círculo
google.maps.SymbolPath.BACKWARD_CLOSED_ARROW	Una flecha que señala hacia atrás y que está cerrada en todos sus lados
google.maps.SymbolPath.FORWARD_CLOSED_ARROW	Una flecha que señala hacia delante y que está cerrada en todos sus lados
google.maps.SymbolPath.BACKWARD_OPEN_ARROW	Una flecha que señala hacia atrás y que está abierta por un lado
google.maps.SymbolPath.FORWARD_OPEN_ARROW	Una flecha que señala hacia delante y que está abierta por un lado

Agregar una Infowindow

Ok ahora que hemos agregado un punto de interés en nuestro mapa usando un overlay maker, seria de mucha ayuda para nuestros usuarios, mostrar más información que solamente su posición.

Para esto usaremos las Infowindows, que son una especie de globo que aparece sobre el marker, mostrando alguna información relevante. En dependencia de la versión de Google Maps, el estilo de la infowindow puede variar, al momento de escribir este libro es estilo es el siguiente:

Para crear un objeto infowindows usamos la clase google.maps.InfoWindow, que según la API recibe un objeto, donde tienen que estar definidas sus opciones. Entre estas opciones la más importante es :

content (content:string|Node) : El valor que asignamos a esta propiedad será el contenido que mostrará la infowindows, puede ser texto plano o HTML. Lo que significa que puedes insertar videos o imagenes en tu infowindows. Para crear una infowindows solo necesitamos hacer una instancia de su clase. Por ejemplo :

var infowindow = new google.maps.InfoWindow({
content : 'Hola soy una infowindows'
});

Con esto hemos creado nuestro objeto infowindows, que mostrará el texto “Hola soy una infowindows”, pero no aparecerá en nuestro mapa aun. Lo que haremos, es que se muestre cuando el usuario haga click en nuestro overlay marker, para lograr esto necesitamos vincular un evento click a nuestro marker.

Crear eventos

Nosotros podemos agregar eventos sobre casi cualquier objeto que hayamos creado, cuando hablo de eventos me refiero a acciones, que nosotros queremos realizar cuando el usuario hace click sobre algún elemento del mapa . Por ejemplo ejecutar algún método que nosotros queramos.

Para crear eventos en Google Maps, usamos la clase “google.maps.event” con la cual podemos vincular cualquier evento del mouse que nosotros queramos. Esta clase tiene distintos métodos estáticos que podemos usar, pero los más importantes son :

addListener(instance:Object, eventName:string, handler:Function) : Vincula un evento al cual se ejecutará cada vez que ocurra.

addListenerOnce(instance:Object, eventName:string, handler:Function) : Vincula un evento solo una única vez , después será removido.

Estos 2 metodos reciben 3 parámetros :

El objeto al cual se vinculara el evento.
El evento que queremos usar.
El método que queremos ejecutar, cuando el evento sea realizado.

Ahora vamos hacer un ejercicio usando esta clase . Por ejemplo, hasta ahora hemos usado el evento READY de jquery para ejecutar nuestro código, pero esto no es aconsejable cuando queremos ejecutar algún código referente a nuestro mapa, por que el evento READY solamente se ejecuta cuando la página web está cargada .

El problema con esto, es que el mapa se carga por medio de AJAX. Lo que indica que no sabemos en qué momento el mapa esta totalmente cargado y listo. Si nosotros intentamos ejecutar algun codigo y el mapa no esta cargado todavía, seguramente tendremos algún error.

La mejor manera que abordar este problema, es usar un evento que nos indique cuando el mapa esta totalmente cargado y listo. Para esto usamos la clase google.maps.event . Si abrimos el archivo de ejemplo de la carpeta número “4” y ejecutamos el archivo “index.html”, podremos ver como una ventana nos muestra el mensaje “El mapa esta cargado” . Ahora analicemos un poco el código del archivo “googlemaps.js”:

//document ready wait until the page is loaded
$(document).ready(function() {
    //obj with option
    var mapOptions = {
        center: new google.maps.LatLng(-34.397, 150.644),
        zoom: 10,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    };
    //create a instance
    map = new google.maps.Map(document.getElementById("map"), mapOptions);
    // trigger when map is load
    google.maps.event.addListenerOnce(map, 'idle', function(){
        alert ('El mapa esta cargado');
    });
});

Como podemos ver, lo nuevo en nuestro código es el uso de google.maps.event.addListenerOnce(). Al cual estamos pasamos los 3 parámetros requeridos : el objeto , el evento y el método a ejecutar. En este caso el segundo parámetro es el evento llamado “idle” este es un evento del objeto mapa. El cual nos indica cuando el mapa esta listo, recuerda que este método de esta clase solo se ejecutará una única vez. Si consultamos la API podemos ver muchos más eventos del objeto mapa que veremos más adelante.

Desde ahora en adelante, usaremos este evento para ejecutar todo nuestros códigos de ejemplo ya que es la manera adecuada de asegurarnos que el mapa esta listo.

En el siguiente enlace podrás ver todos los eventos que pueden ser ejecutados en el objeto “google.maps.Map” en acción : All events map.

Crear evento en el marker

Ahora que sabemos como crear eventos , podemos proceder a crear el evento click en nuestro marker.

google.maps.event.addListenerOnce(map, 'idle', function() {
   var marker = new google.maps.Marker({
       position: new google.maps.LatLng(-34.397, 150.644),
       title : "Hola soy el marcador",
       map: map
   });
   // Adding a click event to the marker
   google.maps.event.addListener(marker, 'click', function() {
       alert('click en el marker');
   });
});

Si copias y pegas este codigo en nuestro archivo de ejemplo número “4”, podrás ver cómo al hacer click en el overlay marker, ahora aparece una ventana que dice “click en el marker”. Como puedes ver estamos pasando los 3 parámetros necesarios : el objeto al que queremos vincular el evento , el evento que queremos escuchar “click” y el método que queremos ejecutar cuando este evento sea realizado.

Ahora que tenemos nuestro evento click en nuestro marker, podemos proceder a abrir nuestra infowindows sobre el overlay marker de la siguiente manera:

var infowindow = new google.maps.InfoWindow({
       content : 'Hola soy una infowindows'
});
google.maps.event.addListenerOnce(map, 'idle', function() {
   var marker = new google.maps.Marker({
        position: new google.maps.LatLng(-34.397, 150.644),
        title : "Hola soy el marcador",
        map: map
   });

   // Adding a click event to the marker
   google.maps.event.addListener(marker, 'click', function() {
        infowindow.open(map, marker);
   });
});

Como puedes ver estamos usando el método ”open” del objeto infowindow, el cual lo hace aparecer en el mapa y recibe 2 parametros, el primero es el objeto mapa donde aparecer (en caso de que tengas más de un mapa en tu web), el segundo es un objeto sobre el cual aparecerá la infowindow en nuestro caso estamos usando nuestro overlay marker.

Infowindow contenido HTML

La propiedad “content” del objeto infowindow, puede tomar contenido HTML en formato cadena para mostrar cualquier información que tu quieras por ejemplo un video de youtube.

Si copias y pegas este codigo en nuestro archivo de ejemplo, podrás ver que al hacer click sobre el overlay marker, ahora la infowindow muestra un video de youtube. De esta manera puedes mostrar imágenes , tablas y cualquier otro contenido HTML. Un tip en este punto es que para controlar el tamaño de la infowindow debes de hacerlo por medio de CSS asignando una clase o ID al elemento HTML.

Usando la clase google.maps.event.trigger puedes abrir la info windows mediante codigo, si asi lo prefieres. Por ejemplo

google.maps.event.trigger(marker, 'click');

Cambiado el icono del maker con eventos

En el siguiente ejemplo vamos a cambiar el icono del overlay marker, cuando ocurra lo siguiente : Cuando el usuario coloque el cursor del mouse sobre el overlay y cuando haga click sobre el overlay.

google.maps.event.addListenerOnce(map, 'idle', function() {
     var marker = new google.maps.Marker({
        position: new google.maps.LatLng(-34.397, 150.644),
        title : "Hola soy el marcador",
        map: map,
        icon : 'http://gmaps-samples.googlecode.com/svn/trunk/markers/green/blank.png'
     });

     google.maps.event.addListener(marker, 'mouseover', function() {    marker.setIcon('http://gmaps-samples.googlecode.com/svn/trunk/markers/orange/blank.png');
     });

    google.maps.event.addListener(marker, 'mouseout', function() { marker.setIcon('http://gmaps-samples.googlecode.com/svn/trunk/markers/green/blank.png');
    });

    google.maps.event.addListener(marker, 'click', function() {         marker.setIcon('http://gmaps-samples.googlecode.com/svn/trunk/markers/circular/yellowcirclemarker.png');
    });

});

Si copias y pegas este codigo, podras ver como el icono del overlay marker cambia cuando situamos el cursor sobre el y cuando hacemos click . Algunos otros eventos que puedes usar de la API de Google Maps son:

click
dblclick
mouseup
mousedown
mouseover
mouseout

Viviendo el presente por que es lo unico que podemos controlar

jueves, 14 de enero de 2016

Libro Google maps Javascript - Capítulo 3: Overlays