Vintage Globe, de Artem Bali

Bienvenido a la tercera y última entrada sobre la creación de un plugin de mapas para Gutenberg. La entrada de la semana pasada fue bastante densa y vimos un montón de cosas variadas: qué atributos tiene nuestro bloque, cómo insertar un mapa usando un componente de React, cómo usar componentes de WordPress o incluso crear nuestros propios componentes para definir la interfaz de usuario, etc.

Hoy toca algo más sencillo pero no por ello menos importante: veremos cómo renderizar el mapa de Google Maps en el front-end. Para ello, analizaremos el último fichero que nos quedó pendiente del bloque nelio-maps que creamos en la entrada anterior y realizaremos las modificaciones pertinentes al plugin para que todo funcione. También aprovecharé esta última entrada para comentar algún punto que quizás haya quedado poco claro hasta ahora.

Cómo guardar nuestro bloque de mapas para visualizarlo en el front-end

Para conseguir visualizar el mapa en el front-end, lo primero que tenemos que hacer es definir el HTML que queremos que se renderice allí. En un bloque de Gutenberg, esto lo conseguimos definiendo el método save de la función registerBlockType. Tal y como ya te adelanté en la entrada anterior, este método lo tienes definido en el fichero save.js dentro de packages/blocks/nelio-maps/.

De nuevo, estamos ante una función extremadamente sencilla de entender:

  • De la línea 7 a la 25 extraemos todos los atributos que son relevantes para nuestro bloque. Es decir, todos los atributos que habíamos definido en attributes.js y que sirven para parametrizar la apariencia del mapa.
  • En la línea 41 abrimos el div que servirá de contenedor para el mapa en si y el posible fragmento de texto con información sobre el marcador.
  • En la línea 47 encontramos el div que debe mostrar el mapa. Fíjate en algo muy interesante: este div incluye el objeto attributesen su definición. Esto quiere decir que todas las propiedades que incluye attributes (por ejemplo, 'data-lat': lat de la línea 34) se renderizarán como atributos HTML (es decir, suponiendo que la variable lat vale 2.48171, aparecerá en el HTML final como data-lat="2.48171").
  • En la línea 49 se añade un pequeño div que contiene las coordenadas del marcador.
  • En la línea 59 se vuelca el contenido del RichText que habíamos definido en edit.js.

Es decir, en esencia el método save sirve para representar en HTML todos los valores que son relevantes para renderizar el mapa en el front-end. ¿Cuál es el problema? Que si vamos al front-end, lo único que veremos es esto:

Captura de pantalla donde debería verse un mapa y no se ve
Captura de pantalla donde debería verse un mapa y no se ve. ¿Qué está pasando?

Un bloque en blanco sin ningún tipo de mapa y en el que sólo vemos el contenido del RichText. ¿Qué ha pasado?

Cómo modificar el plugin para renderizar un mapa de Google Maps creado con nuestro bloque Gutenberg

Para poder visualizar el mapa de Google en el front-end es necesario que carguemos la librería de mapas de Google junto con un componente propio que «construya» el mapa con esa librería. Esto es extremadamente sencillo y si has desarrollado alguna vez para WordPress, deberías saber cómo hacerlo.

Lo primero que deberemos hacer es crear un script que sepa construir un mapa de Google usando los datos que hemos puesto en el HTML. Este script lo tienes en assets/src/js/public/public.js. Fíjate cómo funciona:

  • En la línea 9 buscamos todos los nodos que contengan un mapa de los nuestros (filtrando por una de las clases que hemos incluido en el método save) y, para cada uno de ellos, llamamos al método initGoogleMap.
  • Este método se apoya en dos funciones para hacer su trabajo. Por un lado, extrae las coordenadas de un posible marcador con la función extractMarkerPositionIfAny de la línea 55 y, por otro, extrae todas las propiedades del mapa (coordenadas para centrarlo, el nivel de zoom, qué botones tiene activos, etc ) con la función extractMapOptions de la línea 26. Date cuenta de que ambas funciones se dedican, sencillamente, a leer los valores de los atributos data-algo que habíamos metido en el método save.
  • Finalmente, creamos un mapa (línea 18) y le añadimos un marcador (línea 21) usando las clases Map y Marker, respectivamente, que nos proporciona la librería de mapas de Google.

Una vez tenemos este mapa, sólo debemos realizar dos cambios adicionales a nuestro proyecto:

Una vez realizados todos estos cambios, este es el resultado final:

Mapa de Google con el plugin Nelio Maps en el front-end
Captura de pantalla de un mapa de Google con el plugin Nelio Maps en el front-end.

Sé lo que estás pensando: ¿por qué, en lugar de hacer todo esto a mano, no utilizamos el componente React de mapas de Google que habíamos usado en edit.js? A fin de cuentas, internamente hace lo mismo que acabamos de hacer nosotros a mano, pero nos ahorra un montón de trabajo, ¿no?

Efectivamente, usando el componente React que vimos en la entrada anterior no tendríamos que hacer todo esto, pero hay un precio a pagar. Para poder usarlo, deberíamos cargar también las librerías de React en el front-end, con lo que añadiríamos a nuestra web una carga y un peso innecesarios.

Detalles pendientes

Para finalizar la entrada de hoy, me gustaría explicar brevemente un par de aspectos que, si se dejan en el tintero, pueden confundir ligeramente.

La API Key de Google Maps

Para poder usar Google Maps necesitas tener una API key. Cómo conseguirla es algo que Antonio nos explicó hace unos días. Ahora bien, ¿cómo la usamos?

Una opción sería meter nuestra API key dentro del propio plugin, hardcoded. Si el plugin sólo lo vas a usar tú, es una solución sencilla y te ahorras complicarte la vida. Pero si quieres distribuir tu plugin a usuarios reales es una muy mala idea, porque no todos los servicios de Google son gratis. En algunos hay que pagar y, si mucha gente accede a un servicio de Google con la misma API key (la tuya), llegará un punto en que te llegue una factura inesperada.

¿Qué hacer en estos casos? La idea es muy sencilla: basta con añadir una opción de configuración en el plugin para que la gente introduzca su propia API key.

En nuestro caso, si añades un mapa sin API key, verás el siguiente mensaje de aviso:

Mensaje de aviso cuando no hay una API key disponible
Mensaje de aviso que se muestra al usuario cuando no hay una API key disponible.

instándote a que añadas la API key.

Normalmente, cuando tu plugin tiene ajustes propios, se recomienda crear una página de configuración para poderlos manipular. Pero para el plugin que hemos creado en este tutorial me parecía una complicación innecesaria, así que he optado por una solución alternativa.

En WordPress hay una página de opciones en /wp-admin/options.php con la siguiente pinta:

Opción para meter la API key
Cómo añadir la API key desde los ajustes de WordPress.

Se trata de una especie de «interfaz bonita» para editar (casi) todas las opciones que se han registrado en WordPress y están en la tabla wp_options. Así pues, lo único que tiene que hacer nuestro plugin es asegurarse de que dicha opción existe siempre en la base de datos (aunque su valor sea el string vacío) y ya tendremos una «interfaz bonita» para que el usuario pegue su API key.

Para conseguirlo, enganchánte al hook init de WordPress (mira la línea 73 de este commit) con una función (línea 134) que siempre actualice tu opción a su valor. Cuando la opción no existe, el valor que se pone es el valor por defecto (en nuestro caso, el string vacío). Cuando la opción sí existe, el valor que intentamos «actualizar» es el que ya teníamos y WordPress sencillamente no hace nada con la instrucción. Un pequeño hack, ¡fácil y sencillo!

En resumen

En esta entrada hemos superado la última barrera que nos quedaba por superar en nuestro proyecto: cómo guardar el mapa y cómo conseguir que se visualice en el front-end. Para conseguirlo, únicamente necesitamos un div con toda la información relevante sobre el mapa (su centro, opciones de visualización de los botones, el marcador, etc) y un pequeño script para reconstruirlo en el front-end. También hemos resuelto algunos puntos que (creo) habían quedado en el aire en las entradas anteriores.

Espero que este tutorial te haya gustado y te sirva como ejemplo para emprender tus propios proyectos. Como puedes ver, si partes de una buena base como la que hemos creado en Nelio con el boilerplate para desarrollo Gutenberg, es muchísimo más sencillo que tus ideas se materialicen en proyectos reales.

Si tienes cualquier duda, escríbenos en la sección de comentarios. ¡Un saludo y mucha suerte!

Imagen destacada de Artem Bali en Unsplash.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

He leído y acepto la política de privacidad de Nelio Software

Tus datos personales se almacenarán en SiteGround y serán usados por Nelio Software con el único objetivo de publicar tu comentario aquí. Con el envío de este comentario, nos das el consentimiento expreso para ello. Escríbenos para acceder, rectificar, limitar o eliminar tus datos personales.