Desarrollo Gutenberg con ejemplos: Google Maps (parte 3)

Publicada en WordPress.

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.

FlojaNo está malBienMuy bien¡Impecable! (Ninguna valoración todavía)
Cargando…

Desarrollo Gutenberg con ejemplos: Google Maps (parte 2)

Publicada en WordPress.

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:

Bloque de demo que nuestro boilerplate incluye por defecto en el editor de bloques.
Bloque de demo que nuestro boilerplate incluye por defecto en el editor de bloques.

Pero claro, nosotros no queremos un bloque con un corazón y algo de texto, ¿verdad? Lo que nosotros queremos hacer es algo así:

Captura de pantalla de Nelio Maps
Captura de pantalla del bloque de mapas de Nelio Maps.

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.js define 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.js es 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 componente RichText de 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.js define 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 un RichText usando RichText.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:

  1. Una barra de herramientas ToolbarControls (línea 66), que sacamos de un fichero llamado toolbar.js y que veremos más adelante.
  2. 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.
  3. El contenido del bloque en si, que tiene dos estados:
    1. Si no tengo una API key de Google Maps disponible, mostramos un aviso al usuario (línea 122).
    2. Si disponemos de dicha clave, mostramos el mapa en si con el objeto MapBlock (línea 83) y lo acompañamos (a) de un marcador Marker (línea 97), que únicamente está visible si el marcador está activado, y (b) de un div (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-dev

lo cual añade una nueva entrada en nuestro package.json.

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:

Ajustes básicos del mapa de Nelio
Ajustes básicos del bloque de mapas de Nelio Maps. Escoge el tamaño y el nivel de zoom con estos dos selectores.

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:

Botones del mapa
Configura qué botones del mapa estarán visibles 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:

Estilos de Google Maps
Puedes cambiar la apariencia del mapa usando la sección de Estilos en la configuración del bloque.

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»:

Estilo personalizado de mapa en Nelio Maps
Además de los 5 estilos por defecto incluidos en el bloque, existe la posibilidad de añadir tu propio estilo del mapa usando un JSON.

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:

Cómo añadir un marcador al mapa
El bloque permite añadir un marcador al mapa para así señalizar algún punto en concreto del mismo.

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.

Barra de herramientas de Nelio Maps
La barra de herramientas ofrece un acceso rápido a las opciones más importantes del mapa de Nelio Maps.

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).

Búsqueda de ubicaciones integrada en WordPress
Con la búsqueda de ubicaciones integrada, puedes buscar cualquier negocio o dirección sin salir del editor de bloques.

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.

FlojaNo está malBienMuy bien¡Impecable! (Ninguna valoración todavía)
Cargando…

Desarrollo Gutenberg con ejemplos: Google Maps (parte 1)

Publicada en WordPress.

No sé si te has enterado, pero hace unos días publicamos un nuevo plugin en el directorio de plugins de WordPress.org: Nelio Maps. Tal y como el nombre desvela, se trata de un plugin de mapas que añade un nuevo tipo de bloque en el editor de WordPress. Con él, podemos añadir fácilmente un mapa de Google en nuestras página o entradas. Te dejo con una captura del plugin en cuestión:

El plugin Nelio Maps permite insertar y personalizar un mapa de Google a tus páginas o entradas WordPress.

Nelio Maps es uno de nuestros primeros plugins íntegramente diseñado para Gutenberg. A pesar de ser un plugin relativamente sencillo, se trata de un producto muy útil. Por un lado, porque cualquier usuario que quiera añadir mapas a su web ahora puede hacerlo instalando un plugin sencillo y ligero. Por otro lado, porque cualquier desarrollador que quiera ponerse a desarrollar en Gutenberg ahora tiene un ejemplo real de cómo crear un plugin «desde cero», simplemente leyendo esta entrada.

Como soy consciente de que el desarrollo de un plugin como este no es lo más sencillo del mundo, he organizado este tutorial en tres entradas diferentes. Hoy te explicaré cómo crear el plugin «desde cero» y dejar montado el esqueleto con el que trabajar. En la segunda entrada te explicaré cómo conseguir tener un mapa interactivo en el editor de bloques de WordPress y veremos todos los componentes que he creado para hacer un plugin con un acabado profesional. Y en la tercera y última entrada veremos cómo guardar el mapa en la base de datos y cómo podemos visualizarlo en el front-end de nuestra web.

Definición del tipo de plugin que queremos crear

Puede parecer una perogrullada, pero antes de embarcarnos con cualquier nuevo proyecto, lo primero que debemos realizar es definir qué es lo que queremos conseguir con nuestro proyecto. En función de las funcionalidades que queramos incluir, tendremos unas necesidades u otras. Así que vamos a definir qué tipo de plugin de mapas queremos implementar en este tutorial.

Estos son los requisitos del proyecto:

  1. Queremos poder añadir un mapa (o más de uno) a una página de nuestra web
  2. El mapa tiene que poder centrarse en cualquier punto del globo
    1. O bien arrastrando y soltando el mapa
    2. O bien buscando la ubicación en un cuadro de búsqueda
  3. El tamaño del mapa tiene que poder modificarse, tanto en ancho como en alto
  4. El mapa tiene que poder presentarse con diferentes estilos (en blanco y negro, con una paleta de colores diferente, etc)
  5. El mapa tiene que poder incluir un marcador señalando una ubicación concreta
  6. Si existe un marcador, el mapa tiene que estar acompañado por un cuadro de texto con información adicional sobre dicho marcador.

Ambicioso, ¿verdad? Pues venga, ¡manos a la obra!

Cómo crear nuestro plugin Gutenberg «desde cero»

Si sigues nuestro blog, habrás visto que hace unos días Antonio publicó una entrada explicando cómo crear plugins usando un modelo que hemos creado en Nelio. Si no has leído su entrada, te recomiendo que empieces por ahí, porque nuestro punto de inicio será, precisamente, el plugin boilerplate wp-beb que Antonio explica ahí.

Para empezar nuestro proyecto, lo primero que haremos será realizar una copia de este plugin boilerplate. Para ello, crea un nuevo proyecto en tu cuenta de GitHub y sigue las instrucciones que hay en la ayuda de GitHub para crear una copia de otro repositorio:

git clone --bare https://github.com/avillegasn/wp-beb.git
cd wp-beb.git
git push --mirror https://github.com/tu-usuario/tu-repo.git

Una vez tienes creado el proyecto, sigue las instrucciones del README.md, podrás compilar y ver el resultado del plugin de ejemplo en tu WordPress.

Cómo convertir la copia del plugin boilerplate en nuestro plugin

Tal y como aparece en la propia documentación del plugin boilerplate, lo primero que tenemos que hacer es cambiar el nombre en el código fuente. Es decir, hay que cambiar todas las apariciones de wp-beb (tanto en mayúsculas como en minúsculas, con guiones o con guiones bajos) por el nombre de nuestro plugin (en mi caso, nelio-maps).

Para ello, podemos usar el siguiente script:

en el que obviamente deberás cambiar los nelio maps de las líneas 5, 8, 9 y 10 por el nombre de tu plugin.

Por otro lado, ahora también es un buen momento para cambiar la documentación del plugin. Es decir, por un lado tienes que editar los ficheros README.md y readme.txt para que reflejen el propósito de tu nuevo plugin (sin olvidar hacer una mención al hecho de que estás usando nuestro boilerplate como base, claro). Y, por otro, deberás cambiar el comentario inicial del fichero principal.

Puedes ver cómo realicé todos estos cambios en el primer commit del proyecto Nelio Maps.

Cómo limpiar el proyecto modelo para quedarnos con lo que nos interesa

El plugin boilerplate de Nelio incluye, por defecto, un par de componentes: un nuevo bloque de demo y una extensión en la barra lateral de Gutenberg. Dado que a nosotros nos interesa únicamente crear un bloque (el de mapas), vamos a eliminar todo aquello que nos sobra (la barra lateral de Gutenberg).

Este paso es bastante sencillo, puesto que básicamente se basa en «borrar» cosas innecesarias del plugin. En concreto, deberemos:

  1. Deshacernos de todo el contenido que aparece en la carpeta assets (que es donde se añadía esa barra lateral, su estilo y su icono).
  2. Limpiar el fichero webpack.config.js, puesto que existen un par de reglas que usaban los ficheros de assets que acabamos de cargarnos.
  3. Limpiar el fichero principal del plugin, puesto que encola una hoja de estilos y un fichero JavaScript que ya no existen.

Puedes ver todos los cambios en este commit. Si vuelves a compilar el código, verás que sigue existiendo el bloque llamado Demo, pero ya no está el plugin de Gutenberg que sí teníamos originalmente.

Resumen

En la entrada de hoy hemos visto cómo crear un plugin para Gutenberg. En primer lugar, hemos definido el tipo de proyecto que queremos realizar y hemos identificado qué necesitaremos para llevarlo a cabo. A continuación, hemos visto los pasos necesarios para adaptar el plugin boilerplate de Nelio a un nuevo proyecto. Es decir, hemos visto cómo clonar el proyecto y limpiarlo de polvo y paja.

Nos vemos la semana que viene con la segunda parte de este tutorial, donde modificaremos el bloque de demostración para que realice todas las funciones que hemos descrito al principio de nuestra entrada.

Imagen destacada de Brett Zeck en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (Ninguna valoración todavía)
Cargando…

Las 5 «novedades» de JavaScript que debes conocer para desarrollar en Gutenberg

Publicada en WordPress.

En 2016, el majo de Matt Mullenweg nos dijo:

Voy a poneros deberes: estudiad JavaScript en profundidad (…) porque es el futuro de la web.

Matt Mullenweg (en YouTube)

No sé si le hiciste caso en su día o no, pero está claro que ya no puedes posponerlo más. La llegada a WordPress del editor de bloques ha forzado que muchísimos desarrolladores se pongan las pilas. JavaScript está cogiendo cada vez más peso dentro de WordPress y, si no queremos quedarnos atrás, debemos mejorar nuestras habilidades con este lenguaje.

En el pasado escribí una entrada de toda la potencia que tiene JavaScript a pelo, sin librerías como jQuery. Hoy quiero ir un paso más allá y explicarte algunas de las novedades que hay en las nuevas versiones de JavaScript y que resultan chocantes la primera vez que las ves. Creo que es importante que las conozcas, porque estarán en todos los proyectos JavaScript que veas de ahora en adelante (incluyendo, ¿cómo no?, Gutenberg).

#1 – Destructuración de objetos y arrays

Empecemos por algo sencillo. Supongamos que queremos ver cómo funciona la interfaz de edición de un párrafo en Gutenberg. Para ello, tenemos que ir a estudiar el método edit del bloque correspondiente. En este caso, tenemos que de ese método se encarga un componente llamado ParagraphBlock y la parte que nos interesa es su método render. Pues bien, lo primero que vas a encontrarte en la línea 127 es esto:

¿Qué es todo esto? Bueno, empecemos por algo más fácil. Supongamos que tienes un objeto como el siguiente:

La destructuración de objetos y arrays te permite definir una o más variables del tirón cuyos valores son los atributos del objeto que asignamos. Aquí lo ves con un ejemplo:

Con una sola instrucción, conseguimos recuperar el id, title y content de nuestro post. Y esto es precisamente lo que estaba haciendo Gutenberg en el fragmento que he puesto al principio: recuperar el objeto attributes, la función setAttributes, el atributo isRTL, etc. del objeto this.props.

Un poco más confuso, aunque igualmente interesante, es la posibilidad de extraer atributos de objetos anidados. Es decir, partiendo de un objeto tal que así:

podemos recuperar valores que cuelgan directamente de post o valores que están dentro del atributo author, como id o name.

Si te fijas, cada vez que destructurizamos un objeto, la variable que creamos tiene el mismo nombre que el atributo dentro de dicho objeto. Esto supone algunas complicaciones: ¿qué pasaría si queremos recuperar el id de la entrada y el id del autor de una tirada? En ambos casos tenemos que el atributo se llama id, así que en principio parece que no es posible…

La solución está en los alias:

Es decir, podemos especificar qué atributo queremos recuperar del objeto (por ejemplo, author.id) y cuál es el nombre que queremos dar a la variable que lo contendrá (authorId).

Finalmente, comentarte que la destructuración de objetos es algo que también podemos hacer con arrays:

o que incluso podemos hacer al definir los parámetros de una función. Si sabemos que alguno de los parámetros de la función va a ser un objeto o un array, lo podemos destructurizar en la propia definición de la misma:

#2 – Funciones con flecha

Otro ejemplo bastante habitual. Si echas un vistazo a las leyendas de los bloques imagen de Gutenberg, verás lo siguiente en la línea 693 del método edit:

¿Qué es el value entre paréntesis? ¿Por qué hay una flecha? ¿Qué es eso de setAttributes con llaves dentro? ¡No entiendo nada!

Bueno, vamos a empezar por lo más fácil. Cuando veas una flecha del tipo => tienes que saber que estás delante de una función con flecha, como las que siempre has definido usando function. La sintaxis es prácticamente igual a la de siempre, simplemente cambias la palabra clave function por la flecha =>:

Ahora bien, la ventaja de las funciones con flecha es que se pueden simplificar aún más, haciendo el código más compacto. Por ejemplo, si nuestra función tiene una única instrucción, podemos ahorrarnos las llaves y la palabra clave return, ya que el resultado de evaluar la única instrucción es lo que devolveremos por defecto:

Otra simplificación que podemos realizar son los paréntesis. Si estamos escribiendo una función que tiene un único parámetro, los paréntesis pasan a ser opcionales:

#3 – Operador de propagación y operador de resto

Seguimos explorando el bloque de párrafos y dejándonos maravillar por su sintaxis. Por ejemplo, fíjate en la fiesta que tenemos montada en la línea 64:

¿Qué rayos es esto?

En este caso estamos ante el operador de propagación, es decir, los tres puntos .... El spread operator permite que una expresión sea expandida en situaciones donde se esperan múltiples argumentos (llamadas a funciones) o múltiples elementos (arrays literales).

Vamos a empezar por el ejemplo más sencillo. Supongamos que tenemos un array con un cierto número de elementos y queremos meterlo dentro de otro array. Esto lo podemos conseguir así:

Con él, lo que estamos haciendo es «expandir» (de ahí que el operador, en inglés, se llame spread) los elementos de un array dentro de otro.

De igual forma, podemos realizar esto con objetos:

Ahora bien, fíjate en el siguiente ejemplo (que es una copia del ejemplo de Gutenberg con el que hemos abierto esta sección):

Si estoy expandiendo dos objetos que tienen propiedades en común, el objeto resultante contendrá la unión de propiedades de ambos objetos y, para toda propiedad «repetida», contendrá el valor del objeto de la derecha. Así, por ejemplo, el atributo title que se repite en ambos objetos, contiene el valor del objeto newAttributes, mientras que los demás atributos (author por un lado y words por el otro) aparecen en el resultado con los únicos valores que podrían contener.

#4 – Plantillas de cadena de texto

Otra novedad que tenemos ahora en JavaScript son las plantillas de cadena de texto. Un ejemplo lo podemos ver en el fichero index.js del bloque de párrafos, en la línea 133:

A partir de aquí, podemos complicar las cosas tanto como nos plazca. Fíjate, por ejemplo, en lo que aparece justo a continuación del bloque de párrafos, en la línea 136:

Las plantillas de cadena de texto nos permiten formatear cadenas de texto incrustando valores dinámicos intercalados. Es decir, en lugar de tener que ir concatenando fragmentos de una cadena de texto con variables o expresiones JavaScript, ahora podemos incrustar dichas variables o expresiones en la propia cadena:

¿Qué estaba pasando en el segundo ejemplo? Pues básicamente estamos creando un objeto con propiedades cuyos «nombres» son dinámicos (y algunos de los cuales, por cierto, se generan usando las plantillas de cadena de texto). Veámoslo con un ejemplo más breve:

En lugar de tener que definir el objeto primero y luego ir metiendo las claves y sus valores usando la notación de array, podemos hacerlo todo en el momento de la propia definición del objeto.

#5 – Olvídate de los for y los while

Finalmente, me gustaría cerrar la entrada de hoy con un par de funciones que son muy, muy útiles para trabajar con arrays y con las que deberías estar ya familiarizado. Ambas las podemos encontrar, por ejemplo, en el bloque de columnas de Gutenberg. Efectivamente, estoy hablando de map (por ejemplo, línea 136) y de reduce (línea 119). Vamos a ver para qué sirve cada una de ellas y cómo puedes usarlas.

El método map crea un nuevo array con los resultados de la llamada a la función indicada aplicados a cada uno de sus elementos:

Básicamente, es un método que recorre todos los elementos de un array (lo que viene siendo el for), aplicándoles una función (lo que sería el «cuerpo» del for clásico).

El método reduce es muy parecido al método map, pero en lugar de devolver un array cuyos elementos son el resultado de aplicar una función a los elementos originales, devuelve un único valor. Es decir, se trata de un método que permite aplicar una función a un acumulador y a cada valor de un array (de izquierda a derecha) para reducirlo a un único valor. Por ejemplo:

Resumiendo

Como ves, las nuevas versiones de JavaScript añaden construcciones que permiten escribir código de forma más eficiente y cómoda, pero usando una sintaxis que puede resultar confusa al principio. Espero que la entrada de hoy te haya ayudado a entender qué hay de nuevo en JavaScript y cómo usar sus nuevas estructuras y funciones.

A mí me gusta mucho la forma que está cogiendo JavaScript y me parece que permite escribir código mejor y más legible (una vez lo sabes leer, claro). ¿Tú qué opinas? Después de leer esta entrada, ¿estás ya con ganas de «aprender JavaScript profundamente» de una vez por todas?

Imagen destacada de Ross Findon en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (3 votos, promedio: 5,00 de 5)
Cargando…

Protege tu WordPress ocultando la API REST

Publicada en WordPress.

La API REST de WordPress se introdujo en el core de WordPress a finales de 2016 con la salida de WordPress 4.6. Como todos los cambios grandes que aparecen en la plataforma, la API REST generó controversia en unos e indiferencia en otros.

Es posible incluso que no tengas ni idea de lo que es, pero si tienes una versión actualizada de WordPress (y deberías) que sepas que estás exponiendo muchos aspectos de tu web públicamente mediante la API REST. Tan solo tienes que añadir el fragmento /wp-json/ a continuación de tu nombre de dominio y visitar esta URL para verlo con tus propios ojos.

Es más, haz el ejercicio de visitar las siguientes direcciones web y quizás te sorprenda lo que te encontrarás:

  • tudominio.com/wp-json/wp/v2/users
  • tudominio.com/wp-json/wp/v2/posts

Como resultado de la primera URL tendrás un JSON con los datos de los usuarios de tu web. Fíjate que se incluye el identificador del usuario, algo que tradicionalmente se intenta ocultar por temas de seguridad y prevenir posibles ataques.

En cuanto a la segunda URL, nos muestra una lista con las últimas entradas. No obstante, si tienes contenido protegido que sólo quieres mostrar a ciertos usuarios premium de tu web (si tienes un membership site, por ejemplo), es posible que a través de la API REST tengas el contenido desprotegido.

Veamos cómo podemos evitar situaciones comprometidas siendo más conscientes de lo que públicamente exponemos a través de la API REST de WordPress.

Mostrar la REST API sólo a usuarios registrados

Una solución que podemos implementar para ocultar la API REST de WordPress es evitar que aquellos usuarios que no estén registrados en nuestra web puedan acceder a esta.

Para ocultar la API REST a usuarios no registrados, debemos añadir el siguiente código en nuestro WordPress. Recuerda que lo puedes meter en el archivo functions.php de tu tema o bien hacerte un plugin (mucho mejor opción).

Una vez hayas metido este código en tu WordPress, si ahora intentas acceder a una ruta de la REST API en tu web y no estás logueado, no verás más que un mensaje de error como respuesta. Tus contenidos estarán protegidos.

Mostrar la REST API sólo a usuarios administradores

Ahora imagínate que lo que quieres es que sólo los usuarios con el rol de Administrador en tu WordPress puedan tener acceso a la REST API. En este caso el código que has de utilizar es el siguiente:

Fíjate en que ahora la comprobación la hacemos utilizando la función current_user_can de WordPress. Si quisieras hacer la comprobación con un rol diferente al de administrador, podrías hacer el cambio correspondiente en esta función y listo.

Y si se te ocurre una manera mejor de evitar el acceso a la API REST de WordPress o bien en tu caso lo haces diferente, no dudes en dejarme un comentario más abajo. Siempre es interesante conocer otros puntos de vista ☺️.

Plugins para desactivar la REST API en WordPress

En caso de que quieras hacer cambios más complejos, tienes la posibilidad de utilizar plugins para desactivar la API REST de WordPress.

Hay varios plugins que te permiten desactivar la API REST en WordPress, pero el que te recomiendo es Disable REST API de Dave McHale.

El plugin Disable REST API para WordPress te permite tener un mayor control sobre qué rutas están activas y cuáles no.
El plugin Disable REST API para WordPress te permite tener un mayor control sobre qué rutas están activas y cuáles no.

Por defecto, este plugin ya evita que los usuarios no registrados puedan acceder a la API REST de tu WordPress. Pero además, el plugin Disable REST API te permite seleccionar qué rutas de la API están activas y cuáles quieres desactivar en tu web.

De este modo, controlar qué datos e información es pública en tu web a través de la API REST de WordPress es tremendamente sencillo.

Imagen destacada de Ben Hershey en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (1 votos, promedio: 5,00 de 5)
Cargando…

Mejores prácticas sobre Gutenberg para desarrolladores WordPress que no tuvieron tiempo de aprender JavaScript en profundidad

Publicada en WordPress.

El nuevo editor de bloques de WordPress (también conocido como Gutenberg) es un cambio radical para los desarrolladores acostumbrados a trabajar con PHP.

Si necesitaste aprender JavaScript en profundidad de forma rápida para así actualizar tus plugins y mantener todo funcionando, es posible que te sintieras un poco abrumado.

El desarrollo de bloques representa un gran reto para todos los que no dominamos JavaScript. En esta charla que di en la pasada WordCamp Nordic pude enseñar una serie de buenas prácticas a seguir en el desarrollo con Gutenberg, así como alguno de los errores típicos que debes evitar para que tu código no rompa nada.

Puntos clave

Los argumentos más importantes tratados en la presentación son los siguientes:

  • En 2015 a los desarrolladores de WordPress se les encomienda la misión de aprender JavaScript en profundidad. Se avecinan cambios que harán necesario tener este tipo de conocimientos.
  • En Diciembre de 2018, con el anuncio definitivo de la fecha de salida de WordPress 5.0 y el nuevo editor de bloques (también conocido como Gutenberg), los desarrolladores de plugins han de adaptar sus plugins al nuevo editor. Es en este momento cuando aprender JavaScript en profundidad se convierte en una prioridad.
  • Aprender JavaScript en profundidad implica dominar toda una serie de tecnologías además del propio lenguaje. Transpiladores, compiladores, empaquetadores… Todo esto es complejo y puede asustar al desarrollador más purista de PHP.
  • Hemos desarrollado un boilerplate para facilitar el proceso de adaptación a los desarrolladores WordPress. Este plugin sienta las bases de la programación sobre el editor de bloques incluyendo una configuración inicial completa sobre la que ir avanzando.
  • Lo primero que choca al abrir archivos JavaScript de Gutenberg para intentar entenderlos es su sintaxis moderna. Si no entendemos las construcciones modernas de ESNext, se hace complicado poder entender el código de Gutenberg. Por esto, la recomendación es entender la sintaxis de las construcciones ESNext de JavaScript.
  • Una vez entiendes la sintaxis de JavaScript, el siguiente paso debería ser aprender React. No obstante, WordPress encapsula y oculta React bajo sus propias funciones. Por tanto, en vez de aprender React es mucho más interesante aprender la sintaxis JSX para creación de interfaces de usuario.
  • Gutenberg proporciona un montón de componentes reutilizables para crear interfaces de usuario en JSX. Una buena práctica es utilizar componentes ya existentes, en vez de programar desde cero o reinventar la rueda.
  • La función registerBlockType es la más conocida de Gutenberg. Proporciona la posibilidad de crear nuevos bloques en el editor. Pero hay muchas más funciones que vale la pena investigar.
  • La función registerPlugin te permite añadir un plugin que extiende el editor con una barra lateral en la que añadir los componentes que desees.
  • La función subscribe te permite escuchar los cambios que suceden en el editor de bloques y añadir tus propias funciones que se ejecutan cada vez que ocurre un cambio. Has de ir con cuidado y evitar el código incondicional con esta función para evitar afectar al rendimiento final del editor.
  • Ten cuidado al escribir tu código JavaScript. No estás solo. Tu código puede romper cosas si eres descuidado.
  • En vez de aprender JavaScript en profundidad, aprende Gutenberg superficialmente y empieza a desarrollar más rápido. Luego ya te centrarás en ampliar y profundizar tus conocimientos en aquellas áreas que necesites.
  • No tengas miedo al nuevo editor de bloques ni a JavaScript. Con lo que se explica en esta presentación puedes empezar a desarrollar poco a poco.

Recursos

Los siguientes recursos fueron mencionados durante la presentación o son información adicional útil.

Impacto y feedback

Esto es lo que se dijo en redes sociales sobre la presentación:

Imagen destacada de Jaakko Kemppainen en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (Ninguna valoración todavía)
Cargando…

Modelo de plugin para el desarrollo actual en WordPress

Publicada en WordPress.

El desarrollo en WordPress se está modernizando a pasos agigantados. Si hace unos días te hablé de las tecnologías actuales que ya están presentes en la versión 5 de nuestro gestor de contenidos, hoy toca enseñarte cómo desarrollar plugins para WordPress teniendo en cuenta las posibilidades del nuevo editor de bloques.

Para ello, te voy a describir el modelo o plantilla (boilerplate, en inglés) que estamos utilizando en Nelio para nuestros desarrollos en WordPress con base JavaScript.

Tienes todo el código de nuestro plugin boilerplate para WordPress liberado en GitHub, así que ya no tienes excusa alguna para no modernizarte y ampliar tus horizontes como desarrollador.

WordPress Block Editor Boilerplate

La idea principal de crear un proyecto que sirva de base para la creación de nuevos plugins para WordPress surge de nuestra propia necesidad como desarrolladores de tener una organización de archivos común y estable, además de poder unificar y estandarizar todos nuestros proyectos.

El desarrollo en WordPress ya no es sólo PHP. Dejemos atrás las antiguallas porque es hora de modernizarse.
El desarrollo en WordPress ya no es sólo PHP. Dejemos atrás las antiguallas porque es hora de modernizarse.

Inspirados en el conocido WordPress Plugin Boilerplate, nuestra idea es hacer algo parecido pero centrado en plugins que extiendan el editor de bloques con un stack de desarrollo más moderno utilizando compiladores, transpiladores, empaquetadores y, en definitiva, herramientas de desarrollo comunes hoy en día para proyectos JavaScript.

Instalación y proceso de desarrollo

El modelo de plugin que hemos creado como base se puede descargar directamente desde GitHub y mover al directorio de plugins (/wp-content/plugins/) de tu instalación WordPress.

Si tienes un terminal a mano y estás en el directorio, es tan sencillo como ejecutar el siguiente comando (suponiendo que tienes GIT instalado):

git clone https://github.com/avillegasn/wp-beb.git

Esto descargará la carpeta del plugin con todo el contenido. Tendrás que renombrar tanto esta carpeta como los contenidos para utilizar el nombre que quieras. Por ejemplo, si tu plugin se va a llamar 'mi-ejemplo':

  • renombra los archivos de wp-beb a mi-ejemplo
  • cambia wp-beb por mi-ejemplo
  • cambia wp_beb por mi_ejemplo
  • cambia WP_BEB por MI_EJEMPLO

Una vez has hecho esto, para compilar el plugin y generar el código final tienes que hacer lo siguiente:

npm install && npm run build

Ten en cuenta que previamente necesitarás tener instalados las siguientes herramientas:

Cuando acabe el proceso ya tendrás una nueva carpeta dist con los archivos compilados y ahora ya podrás activar el plugin sin problemas en tu WordPress.

El comando npm install descargará las dependiencias de Node.js y PHP en los directorios node_modules y vendor, respectivamente.

Además del comando anterior, nuestro modelo de plugin proporciona los siguientes comandos adicionales:

  • npm run watchCompila los archivos y repite el proceso automáticamente en cuanto detecta un cambio en los archivos JavaScript y CSS.
  • npm run build Compila y minifica los archivos JS y CSS.
  • npm run lint-php Ejecuta PHP_CodeSniffer en los archivos PHP para detectar errores.
  • npm run lint-php:fix Ejecuta phpcbf para intentar arreglar errores en los archivos PHP.
  • npm run lint-css Ejecuta stylelint en archivos SCSS para detectar errores.
  • npm run lint-css:fix Intenta arreglar errores en archivos SCSS.
  • npm run lint-js Ejecuta eslint en archivos JS para detectar errores.
  • npm run lint-js:fix Intenta arreglar errores en archivos JS.
  • npm run lint Ejecuta un proceso de linting en archivos PHP, SCSS y JS.
  • npm run update:packages Actualiza los paquetes de dependencias de Node.js.

Lo habitual es que ejecutes npm run watch mientas estés desarrollando código para que se vayan compilando los cambios automáticamente. Una vez quieras generar el código final, con npm run build lo tienes hecho.

Contenidos y estructura de archivos

Nuestro WordPress Block Editor Boilerplate incluye los siguientes archivos y directorios:

  • .babelrc. Archivo de configuración de Babel.
  • .editorconfig. Archivo EditorConfig que tu editor de código puede entender para que algunos estilos de formato del código sean consistentes para todos los desarrolladores que participen en el proyecto.
  • .eslintignore. Usado para excluir algunos archivos del proceso de linting de ESLint.
  • .eslintrc. Archivo de configuración de ESLint.
  • .gitattributesArchivo de texto que asigna atributos a rutas de archivo en Git.
  • .gitignore. Usado para excluir ciertos archivos del repositorio.
  • composer.json. Describe las dependencias PHP del proyecto y puede contener también metadatos adicionales.
  • composer.lock. Usado para que los diferentes programadores que participen en el proyecto tengan las mismas versiones de las dependencias PHP.
  • index.php. Sirve para ocultar la estructura de archivos en el servidor.
  • LICENSE.txt. Copia de la licencia GNU GPL v2.
  • package-lock.json. Usado para mantener las mismas versiones de las dependencias NPM para todos los desarrolladores que participen en el proyecto.
  • package.jsonManifest para el proyecto. Repositorio central de la configuración donde encontrarás los nombres de los paquetes requeridos y los comandos que puedes utilizar (y que ya te expliqué antes).
  • phpcs.ruleset.xml. Archivo de configuración de PHP_CodeSniffer.
  • postcss.config.js. Archivo de configuración de PostCSS.
  • README.md. El archivo con la explicación del proyecto e instrucciones adicionales sobre este.
  • readme.txt. Plantilla del típico readme para un plugin WordPress.
  • webpack.config.js. Archivo de configuración para webpack.
  • wp-beb.php. Archivo principal del plugin para WordPress.
  • Directorio assets que contiene el CSS, JS y recursos de imagen.
  • Directorio languages que contiene los archivos de traducción del plugin (i18n).
  • Directorio packages que contiene definiciones de los bloques adicionales que añadimos al editor de bloques de WordPress.

A parte de todo esto, una vez compilas el proyecto aparece el directorio dist con los archivos compilados, el directorio vendor con dependencias y ejecutables para PHP, y el directorio node_modules con dependencias y ejecutables para NPM y JavaScript.

Añadir un nuevo bloque al editor de bloques de WordPress

Lo interesante del WordPress Block Editor Boilerplate que te estoy presentando es la manera de usarlo. Una vez lo tengas descargado y compilado, al activarlo verás que incluye un único bloque Demo en el editor.

Bloque de demo que nuestro boilerplate incluye por defecto en el editor de bloques.
Bloque de demo que nuestro boilerplate incluye por defecto en el editor de bloques.

El bloque de demo incluye dos estilos adicionales al bloque, que no es más que un texto precedido del dashicon de un corazón, como puedes ver en la captura anterior.

El código JavaScript que añade este bloque en el editor lo encontrarás en packages/blocks/demo (míralo aquí). Si quieres eliminarlo, sólo tienes que borrar el directorio demo, borrar su importación y uso en el archivo packages/blocks/index.js y listo.

Además, el código está bien dividido en diferentes archivos, cada uno de estos incluyendo una parte diferente de los parámetros que la función registerBlockType necesita.

Por otro lado, si lo que quieres es añadir un bloque adicional, duplica el directorio packages/blocks/demo y ponle el nombre que quieras para tu bloque. Modifica los archivos JavaScript que hay dentro como desees y recuerda importar el archivo principal del nuevo bloque en packages/blocks/index.js.

Extender el editor de bloques con un plugin

Además del bloque de demo que antes te he comentado, nuestro boilerplate para el editor de bloques incluye la definición de un plugin de Gutenberg.

Ten en cuenta que aunque se llame plugin, no es un plugin de WordPress de los de toda la vida, sino un plugin que extiende el editor de bloques. Sí, un plugin dentro del plugin de WordPress.

Plugin para el editor de bloques que añadimos por defecto.
Plugin para el editor de bloques que añadimos por defecto.

Puedes ver el plugin en la captura de pantalla anterior, situado en la parte derecha. Este plugin se activa haciendo clic en el icono de la parte superior derecha, al lado del botón de publicar.

El plugin incluye un selector de color (para que veas cómo puedes reutilizar de forma sencilla los componentes React que Gutenberg incluye) y un botón para insertar un bloque demo al editor de forma programática (otro caso de uso interesante).

Tienes el código del plugin dentro de assets/src/js/admin (puedes verlo aquí). Concretamente, el archivo plugin.js incluye la llamada registerPlugin y el archivo plugin-component.js define el componente que se encarga de renderizar el selector de color y el botón que te explicaba antes.

De nuevo, puedes modificar este plugin como desees. Incluso borrarlo si así lo quieres. En tal caso, recuerda eliminar el encolado del archivo JavaScript plugin.js que encontrarás en el archivo principal wp-beb.php (ver aquí) así como del correspondiente archivo CSS (aquí).

¡Atrévete a probarlo!

Esperamos que nuestro WordPress Block Editor Boilerplate te ayude a quitarte el miedo y a lanzarte a programar extensiones para el editor de bloques de WordPress de forma sencilla.

Pruébalo y cuéntanos tu experiencia. Estaremos encantados de leer tus comentarios al respecto.

Imagen destacada de Icons8 team en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (1 votos, promedio: 5,00 de 5)
Cargando…

Cómo obtener una API Key de Google Translate

Publicada en WordPress.

Muchos servicios externos que utilizan a su vez la nube de Google te van a pedir una API Key para poder funcionar. Pero, ¿qué es una API Key y cómo la puedes obtener? Pues esto mismo es lo que te voy a explicar ahora mismo.

En el ejemplo que vamos a ver obtendremos una API Key para poder utilizar la API de Google Cloud Translate, pero el proceso es el mismo si, por ejemplo, queremos obtener una API Key para otro servicio de Google Cloud diferente, como podría ser Google Maps.

Empecemos por el principio… Una API Key no es más que una cadena de caracteres que funciona como una clave de uso o licencia de un determinado servicio. En el caso que estamos tratando, una API Key de Google nos permitirá acceder a alguno de los servicios de la nube de Google desde una aplicación externa.

Sin esa clave no podremos hacer llamadas a los servicios de Google de forma autenticada desde una aplicación de terceros, y por tanto no nos funcionará la aplicación que hace uso de esta clave. Ahora que tenemos un poco más claro que es una API Key, veamos cómo obtener una para Google Translate.

Cómo crear una nueva cuenta en Google Cloud Console

Lo primero que necesitas es tener una cuenta en Google Cloud Console y configurar un método de pago en esta. Para ello, sigue estos pasos:

  • Accede a la Consola de la plataforma Google Cloud e inicia sesión o, si aún no tienes una cuenta, regístrate.
  • Abre el menú lateral izquierdo de la consola y selecciona Billing (facturación).
  • Haz clic en el botón New billing account (nueva cuenta de facturación). Ten en cuenta que si ésta no es tu primera cuenta de facturación, primero debes abrir la lista de cuentas de facturación. Para ello, haz clic en el nombre de tu cuenta de facturación existente cerca de la parte superior de la página y, a continuación, en Manage billing accounts (administrar cuentas de facturación).
  • Introduce el nombre de la cuenta de facturación y su información de facturación. Las opciones que verás dependen del país de tu dirección de facturación.
  • Haz clic en Submit and enable billing (enviar y habilitar la facturación).
Pantalla principal de de Google Cloud Console.
Pantalla principal de de Google Cloud Console.

De forma predeterminada, la persona que crea la cuenta de facturación es un administrador de facturación para la cuenta. Cuando ya tengas la cuenta bien creada y la información de facturación lista, ya puedes seguir con los siguientes pasos para obtener la API Key.

Cómo crear un nuevo proyecto en Google Cloud

Ve a la barra superior y en el desplegable podrás ver tus proyectos creados así como crear uno nuevo haciendo clic en el botón New Project:

Pantalla de selección y creación de un nuevo proyecto en Google Cloud.
Pantalla de selección y creación de un nuevo proyecto en Google Cloud.

Ahora lo que tienes que hacer es darle un nombre al nuevo proyecto y crearlo haciendo clic en el botón correspondiente, como puedes ver en la siguiente captura:

Vista de creación de un nuevo proyecto en Google Cloud.
Vista de creación de un nuevo proyecto en Google Cloud.

En este punto ya tienes el proyecto creado y seleccionado, así que sigamos adelante.

Activar la API de Google Translate

Antes de poder usar una API de Google en tu proyecto, lo que hay que hacer es activarla. Ve al menú lateral y selecciona la opción APIs & Services:

Menú de APIs y servicios de Google Cloud.
Menú de APIs y servicios de Google Cloud.

Ahora verás una pantalla con estadísticas sobre las APIs que tienes activadas. Si creaste el proyecto desde cero siguiendo los pasos que ya te he explicado antes, no tendrás datos de uso, como puedes ver:

Dashboard de APIs y servicios de Google Cloud.
Dashboard de APIs y servicios de Google Cloud.

Tienes que hacer clic en el botón superior Enable APIs and services para seguir con el proceso de activación de la API que queramos activar.

Esto nos lleva a un buscador donde hemos de buscar la API de Google Translate, que es la que vamos a activar en este tutorial. Escribe translate en el cuadro de búsqueda y haz clic en el resultado Cloud Translate API.

Vista de búsqueda de APIs para su posterior activación en nuestro proyecto de Google Cloud.
Vista de búsqueda de APIs para su posterior activación en nuestro proyecto de Google Cloud.

Esto nos lleva a una pantalla con la descripción de la API de Cloud Translation, donde hemos de hacer clic en el botón Enable para activar la API en nuestro proyecto:

Antes de poder empezar a utilizar la API de Google Translate en nuestro proyecto hay que activarla en Google Cloud.
Antes de poder empezar a utilizar la API de Google Translate en nuestro proyecto hay que activarla en Google Cloud.

Ya tenemos la API de Google Cloud Translate activada. Ya casi estamos…

Crear una nueva API Key para Google Translate

Después de activar la API, veamos cómo generar una nueva API Key para poder usar este servicio. Tenemos que ir al menú lateral otra vez y seleccionar la opción Credentials:

Menú de gestión de credenciales de Google Cloud Translate.
Menú de gestión de credenciales de Google Cloud Translate.

En esta pantalla veremos un botón con un desplegable y el texto Create credentials. No hagas clic en el botón. Lo que tienes que hacer es abrir el desplegable haciendo clic en la flecha de la derecha del botón y allí seleccionar la opción API Key.

Hay que seleccionar el tipo de credencial API Key para crear una nueva clave para la API de Google Translate.
Hay que seleccionar el tipo de credencial API Key para crear una nueva clave para la API de Google Translate.

Esto crea la nueva API Key. Ya la puedes copiar si quieres, aunque podrás acceder a ella más tarde:

Google Cloud nos proporciona una nueva API Key para poder usar Google Translate con nuestras aplicaciones de terceros.
Google Cloud nos proporciona una nueva API Key para poder usar Google Translate con nuestras aplicaciones de terceros.

Cómo restringir nuestra API Key para proteger y limitar su uso

Para controlar el coste de Google Cloud al usar la API de Google Cloud Translation (o Google Translate, que lo mismo es), podemos hacer dos cosas: restringir desde donde se puede usar la API Key que acabamos de crear, y limitar el uso que podemos hacer del propio servicio.

En la captura de pantalla anterior, si haces clic en el botón Restrict Key irás a la pantalla de restricción de la API Key que hemos creado:

Podemos restringir desde que dominio web podemos utilizar la API Key que acabamos de generar para evitar un mal uso de la misma en caso de pérdida.
Podemos restringir desde qué dominio web podemos utilizar la API Key que acabamos de generar para evitar un mal uso de la misma en caso de pérdida.

Allí puedes seleccionar restringir la API Key por HTTP referrers, que lo que quiere decir es que sólo podrás hacer llamadas a la API de Google Cloud Translate mediante la API Key desde ciertos nombres de dominio.

Has de añadir los nombres de dominio habilitados en el cuadro de texto que aparece al seleccionar la opción HTTP referrers. En nuestro caso, nosotros hemos añadido aquí nuestro nombre de dominio https://neliosoftware.com/*.

Por otro lado, ve al menú API’s & ServicesDashboardCloud Translation APIQuotas y allí encontrarás un cuadro llamado Characters. Allí puedes modificar los límites de uso de la API de Google Cloud Translation y reducirlos, si lo crees necesario.

El precio de Google Cloud Translation API en el momento de escribir esta entrada es de 20 dólares americanos por cada millón de caracteres traducidos, así que haz tus números.

Google Cloud nos permite limitar el uso que hacemos de las APIs para así controlar los consumos máximos que queremos acabar pagando.
Google Cloud nos permite limitar el uso que hacemos de las APIs para así controlar los consumos máximos que queremos acabar pagando.

Pues ahora sí que ya estamos. Ya tienes tu API Key lista para ser usada con la aplicación que quieras. El proceso es un poco engorroso así de primeras, pero tampoco es algo que imposible. ¡Pruébalo y ya me cuentas!

Imagen destacada de Conor Luddy en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (Ninguna valoración todavía)
Cargando…

Cómo contribuir a Gutenberg como desarrollador WordPress

Publicada en Comunidad.

Te gustará más o menos, pero Gutenberg, el editor de bloques de WordPress está aquí para quedarse. Lo bueno que tiene es que al ser código abierto puedes modificarlo como te plazca (si sabes cómo).

Es más, si encuentras un error en el editor que crees que debería solucionarse puedes, o bien reportarlo, o bien intentar solucionarlo tú mismo y subir los cambios para que todos nos beneficiemos de éstos. Con esto estarás contribuyendo a mejorar el proyecto y a que tu buen karma gane enteros.

Bloques más comunes en Gutenberg
Gutenberg maqueta las páginas ofreciendo una colección de bloques. Tenemos párrafos, encabezados, imágenes, galerías…

¿Conoces los pasos a seguir para hacer una contribución al código de Gutenberg? Seguramente la respuesta sea que no. A mí me pasó lo mismo y tuve que investigarlo. Así que te voy a explicar cómo se hace para que te resulte más fácil y rápido entender todo el proceso y puedas contribuir a mejorar Gutenberg (si así lo deseas) con tus aportes como desarrollador.

Hay mucho por hacer y por mejorar, pero está en tu mano poner un granito de arena y ayudar a subsanar aquellos problemas que vayas encontrando con el editor de bloques de Gutenberg.

Pasos para contribuir al desarrollo de Gutenberg

Antes de empezar, voy a suponer que tienes unos mínimos conocimientos de Git y que dispones de una cuenta de GitHub. Si no es el caso, ve a crearte una y mírate este tutorial para que te sea más fácil entender lo que te voy a ir explicando.

Hacer un fork de Gutenberg

Lo primero que has de saber es que el código fuente de Gutenberg se encuentra alojado en GitHub. Concretamente en este repositorio de código. La evolución del proyecto se hace ahí.

Repositorio de GitHub de Gutenberg para WordPress.
Repositorio de GitHub de Gutenberg para WordPress.

En este lugar es donde tienes el código de Gutenberg como plugin para WordPress. Para cada nueva versión del plugin, una vez el código es estable se transfiere a la siguiente versión del core de WordPress. Y así se va avanzando.

De cara a contribuir con código en el repositorio de Gutenberg, lo primero que tenemos que hacer es crear un fork en nuestra cuenta de GitHub. Para ello hacemos clic en el botón Fork que aparece en la parte superior derecha, que puedes ver en la imagen anterior.

Esto creará un repositorio en tu cuenta de GitHub con las mismas características y código que el oficial de la cuenta de WordPress. Pero como está en una cuenta que controlas tú, tendrás acceso para modificar el código y hacer lo que quieras con él. Básicamente, tienes una copia (un fork, vaya).

Clonar el repositorio

Ahora ya tienes tu propio repositorio de Gutenberg conectado con el original. Y necesitas descargarlo en tu ordenador para tener el código disponible en el editor que uses. Para ello ve a un terminal y ejecuta el siguiente comando:

git clone https://github.com/tu-usuario/gutenberg.git

Recuerda sustituir tu-usuario por el nombre de usuario que estés usando en GitHub. Esto creará la carpeta gutenberg en tu ordenador, descargando todo el contenido de tu repositorio de GitHub en local para que puedas empezar a trabajar con él.

Crear una nueva rama

Si entras en el nuevo directorio verás que contiene todo lo que aparece en la rama master del repositorio (o rama principal). No debes tocar esta rama con modificaciones, así que antes de que te lances de cabeza a modificar el código de Gutenberg, veamos cómo crear una rama nueva.

Si no sabes lo que es una rama en Git, te animo a que te leas este artículo. De todos modos, para lo que vamos a hacer sólo necesitas saber que las ramas son la manera de separar las modificaciones que hacemos en el código de un repositorio, para mantener cierto orden.

Si quiero añadir una nueva funcionalidad, crearé una rama nueva cuyo nombre identifique lo que voy a hacer, y entonces desarrollaré la funcionalidad allí. Una vez termine y todo mi código modificado sea estable, puedo fusionar esa rama con la rama principal (master, recuerda) y listo.

Los comandos Git para crear una nueva rama y subirla al repositorio son los siguientes:

git checkout -b fix/clone-block
git push -u origin fix/clone-block

Esto creará la rama fix/clone-block. Recuerda cambiar el nombre de acuerdo a lo que vayas a hacer. Según la guía de Gutenberg, debes utilizar un nombre para tu rama con prefijo y descripción, como: [tipo]/[cambio].

Un buen prefijo suele ser:

  • add/ añadir una nueva funcionalidad
  • try/ funcionalidad experimental, para pruebas
  • update/ actualiza una funcionalidad existente
  • fix/ arregla un problema

Por ejemplo, fix/clone-block indica que vamos a proponer un arreglo en el clonado de bloques.

Añadir los cambios en el código

Ahora sí, ya tienes todo listo para abrir los archivos del repositorio con el editor que más te guste y ponerte a programar. Aunque antes deberías conocer algún detalle más…

Lo primero es que todo el código de Gutenberg sigue una guía de estilo concreta que tú también deberás respetar. Los detalles específicos de cómo se espera que escribas el código los tienes aquí.

Ejemplo de reglas para escribir strings en JavaScript definidas en la guía de estilo de Gutenberg.
Ejemplo de reglas para escribir strings en JavaScript definidas en la guía de estilo de Gutenberg.

Hay reglas para CSS, JavaScript y PHP. No te saltes estas normas o seguramente tendrás problemas para que tu código sea aceptado.

Por si te interesa, en mi caso concreto la modificación que realicé fue utilizar la función lodash.cloneDeep() en los atributos de un bloque cuando lo clonas con wp.blocks.cloneBlock() para que la copia se haga en profundidad y así evitar tener una copia superficial (shallow copy) del bloque que clonamos. Puedes ver los cambios que hice aquí.

Subir los cambios a la nueva rama

Una vez hayas terminado, debes hacer commit de los cambios y subirlos al repositorio. Si has creado archivos nuevos, antes debes añadirlos al control de versiones con el siguiente comando:

git add mi-archivo

Y, ahora sí, toca hacer commit de los cambios con este comando:

git commit -am "Use cloneDeep when cloning a block"

Finalmente, para subir los cambios al repositorio tenemos que hacer uso del siguiente comando:

git push

Con esto si vas al repositorio en GitHub verás tus cambios subidos en la rama que has creado. ¡Perfecto! Ya casi estamos…

Hacer un pull request en el repositorio de Gutenberg

Ya tenemos los cambios hechos y subidos a nuestro repositorio. Ahora lo que tenemos que hacer es avisar de la existencia de nuestra propuesta de cambios a los desarrolladores que se encargan de gestionar el proyecto Gutenberg.

Para que nuestros cambios se discutan y se aprueben (o no) para formar parte de la base de código de Gutenberg necesitamos hacer un pull request.

Un pull request es una petición que el propietario de un fork de un repositorio hace al propietario del repositorio original para que este último incorpore los commits que están en el fork.

Para ello nos vamos a nuestro repositorio fork de Gutenberg y hacemos clic en el botón New pull request. Esto nos lleva a una vista en la que seleccionar la rama que acabamos de subir con nuestros cambios. Así se hará la comparación con la rama principal del repositorio Gutenberg original:

Comparación de la rama master del repositorio oficial con la rama que incluye nuestros cambios en nuestro repositorio fork.
Comparación de la rama master del repositorio oficial con la rama que incluye nuestros cambios en nuestro repositorio fork.

Cuando seleccionamos nuestra rama en el desplegable de la derecha, como ves en la imagen anterior, GitHub nos muestra un resumen de los cambios efectuados en esta rama respecto al repositorio Gutenberg original.

Después de esto tenemos que darle al botón Create pull request. Esto nos llevará a otra vista en la que tendremos que rellenar un texto con la información descriptiva de porqué queremos hacer estos cambios en el repositorio.

Como ves en la siguiente imagen, ya tenemos una plantilla del contenido que nos piden rellenar:

Pantalla en la que rellenamos la información necesaria para crear nuestra pull request en el repositorio de Gutenberg.
Pantalla en la que rellenamos la información necesaria para crear nuestra pull request en el repositorio de Gutenberg.

Básicamente, has de incluir una descripción de tus cambios explicando qué has hecho y el motivo. Indica también si has testeado el código y cómo lo has hecho. Incluso puedes añadir capturas de pantalla si fuera necesario.

No te preocupes si alguna parte de la plantilla no sabes muy bien cómo rellenarla. Las personas que se encargan del repositorio de Gutenberg te ayudarán siempre que seas respetuoso y tu pull request tenga un mínimo de sentido.

Cuando termines, haz clic en el botón Create pull request para que tu pull request se acabe creando oficialmente. Ahora ya sólo te queda esperar a que otros revisores le echen un ojo y eventualmente la aprueben y se fusione tu código en el repositorio oficial.

Ten en cuenta que toda esta revisión puede tardar más o menos tiempo dependiendo de muchos factores. En mi caso finalmente mi pull request se cerró y no prosperó. Pero aprendí un montón en todo el proceso. Y los comentario de los revisores fueron siempre en tono positivo y constructivo. Puedes verlo aquí. Y lo mejor es que persistí con otro tema y finalmente mi código fue aceptado.

Si crees que hay algo en Gutenberg que debe cambiar y te ves con ganas de cambiarlo en el código, ahora ya sabes cómo es el proceso a seguir. Además, todo esto que te he explicado aquí no solo vale para Gutenberg. La mayoría de proyectos de software libre funcionan de forma idéntica (o muy similar).

Atrévete a contribuir. Seguro que aprendes un montón por el camino.

Imagen destacada de Mike Erskine en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (1 votos, promedio: 5,00 de 5)
Cargando…

Recursos para aprender las tecnologías detrás de Gutenberg para WordPress

Publicada en WordPress.

Uno de los mayores retos que tenemos por delante los que nos dedicamos a desarrollar con WordPress es reciclar nuestros conocimientos para adaptarnos al nuevo paradigma de programación que hay detrás del nuevo editor de bloques.

La principal novedad es el cambio en el stack de tecnologías a utilizar. Habitualmente un desarrollador de WordPress estaba acostumbrado a utilizar principalmente PHP, con añadidos en HTML, CSS y JavaScript en menor grado. Ahora la herramienta principal es JavaScript, dejando relegado PHP a ser usado como base para crear la estructura de plugins y temas.

Es posible que pienses que esto no es así y que todavía PHP tiene largo recorrido en WordPress. No te culpo por ello, los cambios siempre cuestan de aceptar. Sin embargo, creo que te equivocas. JavaScript ya no es el futuro de WordPress, sino el presente. Y si quieres mantener tu posición, te va a tocar sí o sí ponerte las pilas.

Aprende JavaScript en profundidad, decían…

Afortunadamente, aunque nos han insistido en que debemos aprender JavaScript en profundidad, yo creo que no es así. Con conocer unos mínimos básicos que cualquier tutorial te puede enseñar es más que suficiente. Lo demás que vas a necesitar para empezar a desarrollar para Gutenberg lo puedes aprender rápidamente gracias a los recursos que te voy a ir dejando a lo largo de este artículo.

Aprende JavaScript

Cuando aprendes un nuevo lenguaje de programación, lo primero que necesitas es conocer y entender su sintaxis. Sólo de esta forma podrás empezar a programar con él. Una vez que tienes esto claro, no hace falta mucho más para empezar a crear.

Libros sobre JavaScript
Cuando quieres aprender JavaScript, no hace falta leerse un manual de más de 1000 páginas… Hay opciones mucho más simples y amenas, a la par que suficientemente completas.

Si nunca antes habías hecho nada con JavaScript, estos son algunos tutoriales en diferentes formatos que te ayudarán a iniciarte:

  • JavaScript Language Basics: curso gratuito en formato vídeo de Zac Gordon.
  • JavaScript 30: aprende creando con un reto cada día durante 30 días de la mano de Wes Bos en este curso gratuito.
  • A re-introduction to JavaScript: breve introducción a JavaScript de la mano de Mozilla.
  • JavaScript For Cats: otra introducción a JavaScript con ciertos toques de humor gatuno.
  • Exercism.io: web gratuita en la que puedes hacer ejercicios en JavaScript y subir tu solución para que un mentor te la evalúe.
  • JSBooks: si eres de los que prefiere aprender con libros, aquí tienes un montón de ellos gratis.

Por el contrario, si ya tienes algo de experiencia utilizando JavaScript, amplía tus conocimientos estudiando conceptos avanzados sobre las funciones, ejecución asíncrona con promises y async/await, y en definitiva, todo aquello relativo a ESNext.

Con una jornada de formación en JavaScript debería ser más que suficiente para adquirir los conocimientos básicos para moverte con soltura en todo lo relativo a lo que necesitarás para desarrollar sobre el editor de bloques de WordPress.

Aprende React y Redux

Además de JavaScript, para desarrollar sobre el editor de bloques de WordPress necesitarás tener ciertas nociones de React y Redux.

Esto es lo que todo el mundo te dirá, pero la verdad es que no es así. Puedes desarrollar para Gutenberg sin tener ni idea de React ni de Redux. Eso sí, si sabes como funcionan y para que se utilizan, pues mejor que mejor.

React y, sobretodo, JSX

De lo que no puedes prescindir es de conocer cómo funciona la sintaxis JSX para crear elementos dentro de React, que utilizaremos para definir la interfaz de nuestros componentes (ya sean bloques de Gutenberg o vistas dentro del editor).

Imagínate que quieres definir la interfaz de los componentes Product y ShoppingListpara luego usarlos en un bloque de Gutenberg. Con notación estándar lo harías de la siguiente forma, utilizando la llamada wp.element.createElement() que te proporciona Gutenberg:

En cambio, si usas JSX dentro del método render(), que no es más que una notación similar al HTML, lo que tienes es lo siguiente:

Utilizar JSX simplifica la escritura y reutilización de componentes, ya que el código es mucho más simple y más fácil de leer. Como ves, en el ejemplo anterior estamos creando componentes React sin tener ni idea de React, sólo sabiendo manejar JSX y utilizándolo como si de un HTML con superpoderes se tratase. Además, puedes utilizar componentes ya existentes en Gutenberg. Los puedes ver en este visualizador que además está enlazado a la documentación oficial.

Sólo hay un problema. Necesitarás transpilar el código con Babel para que esa notación se acabe transformando en el código sin JSX y cualquier navegador lo pueda interpretar. Sin embargo, esto no es un drama ya que lo puedes hacer automáticamente con WebPack.

Redux para mantener el estado de tu aplicación

Por otro lado, también es posible que hayas oído hablar de Redux. Se trata de una herramienta para guardar y gestionar el estado en aplicaciones JavaScript. De nuevo, si te interesa aprenderlo, te recomiendo estos vídeos de Wes Bos, pero tampoco es necesario.

Si tuvieras la necesidad de crear tu propia store de datos, no la harías con Redux, sino que utilizarías el paquete @wordpress/data incluido en Gutenberg. Este paquete utiliza Redux internamente, pero eso a ti te da igual. Además, estamos hablando de un caso de uso complejo que seguramente no necesites, por lo menos en una etapa inicial. Así que por lo pronto olvídate de ello.

NPM, WebPack, Babel, PostCSS y ESLint

Además de JavaScript y nociones básicas de React y de JSX, para la nueva era que ya está aquí en WordPress vas a necesitar conocer las siguientes tecnologías para que tu trabajo de desarrollador sea mucho más sencillo y automatizado:

  • NPM: el gestor de dependencias por antonomasia para JavaScript. define las dependencias que necesites y al hacer npm install, se instalan solas.
  • WebPack: el empaquetador de JavaScript. Es complicado de configurar al principio, pero una vez lo tienes, facilita el trabajo de gestión de archivos JavaScript: transpilación, minificación…
  • Babel: el compilador de JavaScript para poder usar la sintaxis de las próximas versiones de este lenguaje hoy.
  • PostCSS: lo mismo que Babel, pero para tus hojas de estilo CSS.
  • ESLint: detecta errores de uso y estilo de JavaScript para que los evites mientras estás escribiendo código.

La mayoría de estas tecnologías ya te las presenté con anterioridad aquí. Sin embargo, me voy a poner de deberes escribir otro artículo pronto donde te explicaré cómo integrarlas en un proyecto de desarrollo para WordPress. para que así las sepas usar en un caso real.

Cómo crear nuevos bloques para Gutenberg

Ahora sí, vamos a por la parte más importante de todas: qué necesitamos para empezar a crear nuevos bloques para el editor de WordPress.

Lo primero que necesitas para empezar a crear tus propios bloques es dominar la función wp.blocks.registerBlockType(). La documentación más completa sobre esta función la encontrarás aquí, en la guía oficial de Gutenberg.

A esta función le pasas como parámetro un string con el nombre del bloque, que ha de ser único e identificarlo, y un objeto con la configuración del bloque, donde las partes más importantes son la función save y la función edit del bloque. Ya te expliqué brevemente esto en este artículo.

Si esto te parece demasiado complicado, puedes empezar utilizando el toolkit de Ahmad Awais llamado create-guten-block. Esto te crea una estructura de directorios con todas las dependencias necesarias para crear tu primer bloque. Puedes ver un tutorial sobre su uso en el siguiente vídeo:

Finalmente, si esto te sigue pareciendo demasiado complejo, tienes una última opción disponible. Seguro que conoces el plugin Advanced Custom Fields (también conocido como ACF, por sus siglas). Pues bien, este plugin te va a permitir crear bloques para Gutenberg sin tener ni idea de JavaScript.

Pero esto no te lo voy a explicar yo, mejor te lo cuenta Mauricio Gelves en su blog con todo lujo de detalles. Y si lo prefieres, también puedes ver la presentación que hizo Mauricio sobre este tema en la WordCamp Zaragoza 2019 que ya tienes en WordPress.tv:

Extender el editor de bloques de WordPress

Hay muchas otras cosas que puedes hacer con Gutenberg, además de crear nuevos bloques. Por ejemplo, puedes crear un plugin dentro de Gutenberg para añadir un panel de opciones en la zona lateral derecha del editor con todo lo que desees. Lo mejor de esto es que la documentación oficial de WordPress incluye este tutorial completo con ejemplos concretos de lo que puedes hacer allí.

Además de esto, puedes extender el editor de WordPress añadiendo nuevos estilos a bloques existentes, añadir más ajustes personalizados a los bloques, eliminar bloques u ocultarlos, o filtrar las categorías de bloques que puedes tener en el editor.

Te recomiendo que te mires con mimo toda la documentación oficial que tienes en la guía de Gutenberg para desarrolladores y diseñadores que encontrarás aquí. Tómatelo con calma porque hay mucha información y el orden no es el más claro, pero sin duda, este es uno de los mejores recursos que tienes disponible.

Imagen destacada de Christian Fregnan en Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (1 votos, promedio: 5,00 de 5)
Cargando…