Ya estamos de vuelta con nuestro tutorial para desarrollar en Gutenberg. La semana pasada empezamos un proyecto que añadía un bloque de mapas en nuestro WordPress. En aquella primera entrada definimos cuáles eran los requisitos que nuestro plugin tiene que cumplir y dejamos listo el esqueleto del que acabará siendo el producto final, partiendo del fantástico plugin boilerplate que hemos creado en Nelio.
Hoy llega la segunda parte del tutorial sobre cómo crear el bloque de mapas. En esta entrada veremos cómo añadir un mapa de Google Maps dentro del editor de WordPress y cómo implementar una interfaz de usuario que nos permita manipular su comportamiento.
Un vistazo al estado actual del proyecto…
En el estado actual del proyecto tenemos un sencillo bloque llamado Demo en packages/blocks/demo/. Este pequeño bloque es el que viene de ejemplo en el plugin boilerplate del que hemos partido y tiene la siguiente pinta:
Pero claro, nosotros no queremos un bloque con un corazón y algo de texto, ¿verdad? Lo que nosotros queremos hacer es algo así:
Es decir, queremos un bloque donde se vea un mapa de Google con un posible marcador. ¿Cómo podemos pasar del bloque de ejemplo original que tenía nuestro boilerplate a este otro bloque más potente? Pues eso es lo que vamos a responder hoy mismo
Pero antes de ello vamos a dedicar un par de minutos a explicar de dónde venimos. Si eres capaz de entender cómo está funcionando el bloque de Demo, lo demás será pan comido.
Entendiendo el bloque de ejemplo…
Toda la chicha del bloque de Demo del que partimos está, como te decía, en packages/blocks/demo/. Allí hay los estilos del bloque, su icono y varios ficheros con el código que implementa su funcionamiento. Veamos los ficheros más importantes.
Por un lado, está el fichero principal index.js. Este fichero exporta tres variables: el nombre del bloque (name), la definición del bloque (settings) y los estilos que admite el bloque (styles). Estas tres variables son las que se usan en packages/blocks/index.js para registrar el bloque en Gutenberg (con registerBlockType) y que esté disponible para usarse.
Este fichero principal, pues, sirve de punto de entrada para entender el bloque que estamos creando. En el objeto de ajustes (settings), vemos tres propiedades importantes: attributes, edit y save. Cada una de estas propiedades está definida en su propio fichero JavaScript con igual nombre, así que comentemos rápidamente qué hay en cada uno de ellos:
- El fichero
attributes.jsdefine todas aquellas propiedades de nuestro bloque que son dinámicas y que, por lo tanto, queremos que el usuario pueda modificar. En el caso del bloque de Demo, el único atributo que hay es el texto que ha escrito el usuario, pero el bloque de mapa tendrá muchas más opciones: las coordenadas del centro del mapa, el nivel de zoom que queremos aplicar, si hay que mostrar ciertos botones, etc. - El fichero
edit.jses el que define cómo se visualiza el bloque en el editor de WordPress y qué ajustes se ofrecen al usuario (tanto en la barra de herramientas como en la barra lateral de ajustes del bloque). En el caso de Demo, la edición incluye simplemente el componenteRichTextde WordPress para escribir el contenido. Como veremos, el bloque de mapas será más complejo e incluirá también ajustes adicionales. - Finalmente, el fichero
save.jsdefine el método que convertirá el bloque que estábamos editando en el HTML que deberá renderizarse en el front-end. De nuevo, en Demo vemos que esta función simplemente guarda el contenido de unRichTextusandoRichText.Content, pero podría ser cualquier otra cosa (tal y como veremos la semana que viene en la tercera y última entrada de este tutorial).
Creación del bloque de mapas basándonos en el bloque de ejemplo incluido en el plugin boilerplate
Una vez entendido exactamente cómo funciona el bloque que tenemos ahora mismo de demostración, ¿cómo creamos el nuestro? Pues muy fácil: tal y como nos contaba Toni hace unos días, duplicamos el directorio packages/blocks/demo/ en packages/blocks/nelio-maps/ y empezamos a modificar todo lo que sea necesario.
Ya te he dicho que lo primero que habrá que modificar será el fichero attributes.js. Ahí definiremos todas las propiedades que queremos que sean parametrizables de nuestro mapa. En la entrada anterior especificamos qué requisitos debería cumplir nuestro plugin y, por lo tanto, esbozábamos qué cosas se tienen que poder manipular. Pues bien, echando un vistazo al attributes.js resultante verás qué cosas se pueden tocar del bloque de mapas que vamos a crear. Es algo tan sencillo que no merece la pena dedicarle más líneas.
El siguiente punto a modificar es todo lo que concierne a la edición del bloque en Gutenberg. Para ello, debemos meternos en el fichero edit.js e ir tirando del hilo. Si lo miras con detenimiento, verás que no es mucho más complicado que lo que teníamos en el bloque Demo.
Lo más importante está en el método render del bloque (línea 33), donde recuperamos los atributos del objeto this.props que el bloque necesita para funcionar y donde acabamos renderizando toda la interfaz. Fíjate que la interfaz consta de tres partes:
- Una barra de herramientas ToolbarControls (línea 66), que sacamos de un fichero llamado toolbar.js y que veremos más adelante.
- Los ajustes de bloque que aparecen en la barra lateral del editor (línea 68), que encontramos en un componente llamado Inspector que definimos en inspector.js.
- El contenido del bloque en si, que tiene dos estados:
- Si no tengo una API key de Google Maps disponible, mostramos un aviso al usuario (línea 122).
- Si disponemos de dicha clave, mostramos el mapa en si con el objeto
MapBlock(línea 83) y lo acompañamos (a) de un marcadorMarker(línea 97), que únicamente está visible si el marcador está activado, y (b) de undiv(línea 104) con la información adicional sobre el marcador.
Google Maps como componente React
Está claro que si queremos meter un mapa de Google en nuestro editor, deberemos usar algún componente que nos permita usar la API de mapas de Google Maps. Teniendo en cuenta que Gutenberg está creado usando React, lo más lógico es buscar si existe un componente React de Google Maps. ¡Y existe, claro que sí!
Tal y como puedes leer en la documentación del proyecto, lo primero que tenemos que hacer para poder usar dicho componente es añadirlo a nuestro proyecto. Esto lo conseguimos instalando y añadiendo la dependencia a nuestro plugin:
npm install react-google-maps --save-devlo cual añade una nueva entrada en nuestro package.json.
Nelio A/B Testing
Me sorprendió mucho la calidad del plugin, lo fácil que fue configurarlo y el increíble soporte que me dio Nelio. Recomiendo encarecidamente usar Nelio A/B Testing.
Josette Millar
Cómo crear un componente de WordPress que encapsule un componente React
Si seguimos mirando la documentación de este componente React para Google Maps, veremos que nos recomiendan encapsular el componente GoogleMap en un componente propio. Una vez esté encapsulado, deberemos usar este componente propio en nuestro plugin.
Para ello, lo único que hacemos es crear un componente llamado MapBlock en su propio fichero map-block.js (por aquello de tenerlo todo bien ordenadito) siguiendo exactamente los pasos que nos indica la documentación. Ni más, ni menos.
Cómo añadir ajustes de bloque en la barra lateral de WordPress
Ahora que ya tenemos un mapa, es hora de poder configurar cómo deberá verse y comportarse el mapa en el front-end. Para ello, deberemos añadir varias secciones de ajustes en la barra lateral de Gutenberg. Como ya te he avanzado, esto lo conseguimos con un componente que hemos llamado Inspector y que hemos definido en el fichero inspector.js.
Si echas un vistazo a este fichero, verás que se sigue el mismo patrón de siempre: estamos definiendo un componente Component con un método render. Este método se queda con los atributos de this.props que le son relevantes y devuelve el JSX con todos los controles. En este caso en concreto, devuelve un InspectorControls (esto le indica a WordPress que este contenido va a la barra lateral) con varias secciones PanelBody. Veamos cada sección en detalle.
Ajustes básicos del mapa
El primer PanelBody que encontramos (línea 47) no tiene título title y, por lo tanto, aparece siempre como una sección que no se puede cerrar:
La sección define un par de controles de rango RangeControl, cuyo resultado puedes ver en la captura anterior. Estos dos controles nos permiten modificar el alto del mapa y el nivel de zoom del mismo.
Otra sección interesante y sencilla es la que encontramos en la línea 121. Aquí añadimos unas cuantas opciones para activar o desactivar los botones que deberán mostrarse en el mapa cuando éste se visualice en el front-end:
Para ello, simplemente tenemos que usar el componente por defecto de WordPress CheckboxControl.
Cómo añadir una sección personalizada de estilos para nuestro mapa
Otra sección interesante de nuestro bloque es la sección de estilo (línea 68). Puedes ver el resultado final en la siguiente captura:
Se trata de una sección especial porque el componente que usamos (MapStyles) no es algo que exista en WordPress por defecto, sino que lo hemos creado a drede para la ocasión. Tal y como puedes ver en el enlace anterior, se trata de un compontente que carga un conjunto de estilos predefinidos en un componente de tipo ImagePicker (el cual, por cierto, tampoco existe por defecto en WordPress; puedes encontrarlo en packages/components/image-picker/) .
Cuando el usuario selecciona alguno de los estilos incluidos en ImagePicker, el componente MapStyles invoca la función onChange que le hayan pasado (fíjate en la línea 76 de inspector.js) pasando dos valores: el nombre del estilo seleccionado y el JSON asociado.
Finalmente, fíjate que una de las opciones que incluye MapStyles es el «estilo personalizado»:
Cuando se selecciona, el componente renderiza un cuadro de texto adicional (línea 45) para que el usuario pueda meter su propio estilo en formato JSON. Porque, por si no lo sabías, los mapas de Google Maps se pueden personalizar una barbaridad.
Cómo añadir un marcador a nuestro mapa
La siguiente sección que tenemos es la que controla nuestro marcador (línea 81). Esta sección nos permite mostrar u ocultar el marcador del mapa (línea 86) y, cuando está activo, nos da algunos ajustes adicionales:
Como ves, aparece un cuadro de búsqueda para buscar ubicaciones en Google Maps (el cual hemos implementado, de nuevo, con un componente personalizado llamado AddressSearch) y la posibilidad de mostrar u ocultar el bloque de texto en el que meter información adicional sobre el marcador.
Por cierto, fíjate que este componente para buscar ubicaciones en Google se basa en un componente llamado StandaloneSearchBox, el cual también forma parte del proyecto React que hemos añadido a nuestro plugin para usar el mapa en primer lugar. ¡Qué gustazo da reaprovechar el trabajo de otros!
Cómo configurar la barra de herramientas de un bloque
Lo último que nos queda por explicar hoy es la barra de herramientas. Si has entendido como funciona la barra lateral, la barra de herramientas es una chorrada.
La barra de herramientas de nuestro plugin está representada por el componente ToolbarControls definido en toolbar.js. Aquí sencillamente añadimos un componente para definir la alineación del bloque (BlockAlignmentToolbar, en la línea 42), un par de desplegables para centrar el mapa (línea 50) y/o modificar la ubicación del marcador (línea 79) y un par de botones extra para cambiar la ubicación del cuadro de texto en el que podemos meter información sobre el marcador (líneas 107 y 120).
Resumiendo
Hoy hemos visto cómo crear toda la interfaz de edición del bloque de mapas. Como ves, se trata de un proceso que, si bien puede resultar ligeramente costoso en tiempo, cualquiera con ganas puede aprender. Al final, el secreto está en partir de un código de ejemplo que esté bien organizado e ir construyendo la interfaz poco a poco, reaprovechando los componentes que ofrece WordPress, los componentes que ya existen o creando los tuyos propios.
Nos vemos la semana que viene con la última entrega de este tutorial, donde veremos cómo guardar nuestro mapa y cómo visualizarlo en el front-end de la web.
Imagen destacada de rawpixel en Unsplash.
Deja una respuesta