Hace casi un año y medio, Antonio escribía esta entrada en el blog explicando una de las dificultades a las que nos enfrentamos cuando tuvimos que adaptar nuestros plugins al nuevo editor de bloques de WordPress. Si seguiste ese pequeño tutorial en su día, imagino que pudiste añadir un botón como el siguiente:
Por suerte o por desgracia, Gutenberg ha cambiado muchísimo en este año y medio. El stack de desarrollo se ha ido ampliando y mejorando y los desarrolladores de plugins y temas nos hemos tenido que ir adaptando a él. Y, lógicamente, aquellos que también escribimos sobre nuestra experiencia y compartimos lo que vamos aprendiendo, nos vemos «obligados» a actualizar nuestros tutoriales para que también tú puedas seguir estando al día.
Hace unas semanas, Iván, uno de nuestros lectores, nos dejaba un comentario en el tutorial de Antonio pidiéndonos ayuda; se ve que tenía problemas para replicar los resultados de nuestro tutorial. Y no me sorprende, ya que, como digo, muchas cosas han cambiado en los últimos meses… así que, para ayudar a Iván y a todos los que nos leéis y queréis seguir aprendiendo sobre WordPress, ¡vamos a rehacer el tutorial sobre cómo añadir un botón al editor de bloques Gutenberg aprovechando todas las nuevas herramientas que nos ofrece WordPress!
Creación de un plugin
Lo primero que debemos hacer es crear un plugin donde vamos a meter toda la funcionalidad que queremos añadir a WordPress. Esto es algo que ya te hemos contado en entradas anteriores del blog, así que no voy a entretenerme demasiado en este punto.
Básicamente, lo único que tenemos que hacer es crear una carpeta en wp-content/plugins con el nombre que queremos darle a nuestro plugin (por ejemplo, gutenberg-button) y, dentro de ella, un fichero con el mismo nombre y extensión .php. Y luego debes meter el siguiente código dentro:
En esencia, esto es lo que hemos definido dentro de gutenberg-button.php:
- Empezamos abriendo la etiqueta
<?php, porque los plugins WordPress se escriben en PHP. - A continuación, en este fichero principal, metemos un comentario multilínea. El comentario incluye varias líneas con pares «Clave/Valor». Por ejemplo, vemos cómo especificamos el nombre del plugin (
Plugin Name), su versión (Version) o el nombre del autor (Author). Toda esta información es la que aparece en el escritorio de WordPress, dentro de la sección de Plugins. - Finalmente, metemos el código del propio plugin. De momento, nuestro plugin no hace nada especial:
- especifica un
namespacepropio (de lo que ya hablamos aquí), - incluye una comprobación para asegurarnos de que el plugin se está ejecutando en el contexto de WordPress y
- define algunas constantes sobre el plugin que nos serán útiles más adelante.
- especifica un
Una vez hemos hecho todo esto, si vamos a la pantalla de Plugins de nuestro WordPress, veremos que Gutenberg Button está ahí:
lo activamos y… ¡listo! Aún no hace nada, pero ya está todo preparado.
Desarrollo de un plugin en JavaScript
Una de las principales novedades de la introducción de Gutenberg en WordPress es que, ahora, buena parte del desarrollo de plugins que hacemos ya no es en PHP, sino que es en JavaScript. Y este tutorial no es una excepción.
Nelio Popups
¡Un plugin fantástico! Es muy fácil crear ventanas emergentes con el editor que ya conoces y las opciones que ofrece están muy bien diseñadas.
Juan Hernando
Preparando el entorno
Si queremos añadir un nuevo botón a la interfaz de Gutenberg, debemos programar en JavaScript. Así que vamos a preparar el entorno de desarrollo JavaScript en nuestro plugin. Para ello, simplemente ejecuta este comando desde la carpeta de tu plugin (en nuestro caso, wp-content/plugins/gutenberg-button):
npm inity sigue las instrucciones en pantalla:
This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults.
See `npm help json` for definitive documentation on these fields and exactly what they do.
Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file.
Press ^C at any time to quit.
package name: (gutenberg-button)
version: (1.0.0)
description: Adding a formatting button in Gutenberg.
entry point: (index.js)
...Una vez hayas acabado, tendrás preparado un fichero package.json en la carpeta de tu plugin. Gracias a él, podremos añadir dependencias a nuestro código JavaScript y preparar diferentes comandos con los que empaquetar el plugin y convertirlo en código que podamos ejecutar en nuestro navegador.
Como ya he desvelado en el título de la entrada, usaremos @wordpress/scripts para poder crear fácilmente nuestro plugin e integrarlo con WordPress, así que vamos a instalarlo:
npm install --save-dev @wordpress/scriptsEste comando descargará un montón de dependencias dentro de nuestro plugin, bajo el directorio node_modules. Además, también meterá @wordpress/scripts como una dependencia de desarrollo en nuestro package.json.
Si echas un vistazo a la documentación de este paquete, verás que incluye un montón de scripts para empaquetar el código, validar su sintaxis, formatearlo, etc:
{
"scripts": {
"build": "wp-scripts build",
"check-engines": "wp-scripts check-engines",
"check-licenses": "wp-scripts check-licenses",
"format:js": "wp-scripts format-js",
"lint:css": "wp-scripts lint-style",
"lint:js": "wp-scripts lint-js",
"lint:md:docs": "wp-scripts lint-md-docs",
"lint:md:js": "wp-scripts lint-md-js",
"lint:pkg-json": "wp-scripts lint-pkg-json",
"packages-update": "wp-scripts packages-update",
"start": "wp-scripts start",
"test:e2e": "wp-scripts test-e2e",
"test:unit": "wp-scripts test-unit-js"
}
}Edita tu package.json para que, en la sección "scripts", estén todos los scripts que te recomiendan.
Cómo verificar que todo funciona…
A continuación, crea una carpeta src en la raíz de tu proyecto con el fichero principal index.js dentro. Ese será el fichero principal con nuestro script JavaScript y todo el código irá dentro de src.
Para comprobar que todo funciona, simplemente pon esto dentro de index.js:
console.log( 'Hi!' );y, acto seguido, ejecuta el comando npm run build desde la carpeta wp-content/plugins/gutenberg-button para que @wordpress/scripts compile el código que acabamos de escribir y lo meta en una nueva carpeta build. ¡Y ya está! Ya has transpilado el código JavaScript que has escrito en algo que puedes meter en el navegador y ejecutarlo.
Ahora solo nos queda decirle a WordPress que existe un fichero JavaScript que queremos que meta en nuestras páginas, así que vamos a ello. Abre el fichero principal de tu plugin (gutenberg-button.php) y añade estas líneas al final:
function enqueue_script() {
wp_enqueue_script(
'gutenberg-button',
GUTENBERG_BUTTON_URL . '/build/index.js',
[],
GUTENBERG_BUTTON_VERSION
);
}//end enqueue_script()
add_action(
'enqueue_block_editor_assets',
__NAMESPACE__ . '\enqueue_script'
);Si te fijas, lo único que estamos haciendo es decirle a WordPress que encole el fichero /build/index.js como parte de los recursos que queremos que estén disponibles en el editor de bloques.
Si ahora vas a editar una entrada cualquiera y echas un vistazo a la consola JavaScript de tu navegador, verás que tu plugin ha escrito «Hola» por pantalla:
Replicando nuestro tutorial para añadir un botón a Gutenberg
Vale, ahora que ya hemos visto que podemos escribir código JavaScript y transpilarlo con npm run build a algo que podamos meter en el navegador, es hora de replicar el tutorial de Antonio. Y esto, querido lector, es extremadamente sencillo.
Abre el fichero src/index.js y modifica su contenido para que sea así:
Como ves, es prácticamente el mismo código que creó Antonio en su día. Las principales variaciones es que no estamos accediendo a variables globales wp, sino que todas las dependencias que tenemos a funciones de WordPress las obtenemos usando sentencias import.
Una vez tienes el código escrito, vuelves a ejecutar npm run build y… ¡ya está! Ya tienes el botón en Gutenberg (si no ha funcionado, sigue leyendo):
Y si seleccionas un texto y pinchas en él, pues lógicamente aparece por consola:
Un apunte final sobre las dependencias…
Si echas un vistazo dentro de la carpeta build, verás que @wordpress/scripts no sólo ha creado un fichero index.js, sino que también ha creado un fichero index.asset.php. Este fichero define un pequeño objeto con dos propiedades:
- una lista con todos los scripts de WordPress de los que depende nuestro JavaScript
- una versión de compilación
Podemos (y debemos) usar ambas propiedades cuando encolamos nuestro script en WordPress si queremos garantizar que, cuando se ejecute, tendrá todo lo que necesita tener para funcionar. Para ello, simplemente vuelve a gutenberg-button.php y cámbialo como te muestro a continuación:
function enqueue_script() {
$asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php';
wp_enqueue_script(
'gutenberg-button',
GUTENBERG_BUTTON_URL . '/build/index.js',
$asset['dependencies'],
$asset['version']
);
}//end enqueue_script()
add_action(
'enqueue_block_editor_assets',
__NAMESPACE__ . '\enqueue_script'
);Como puedes ver, lo único que hacemos es recuperar el objeto que hay en index.asset.php para, así, poder cambiar el array vacío [] por la lista de dependencias que ha encontrado @wordpress/scripts y para poder usar el número de versión que ha generado.
Conclusiones
No te voy a mentir: crear plugins realmente útiles para WordPress es complicado. Debes entender bien cómo funciona JavaScript y estar familiarizado con toda la batería de recursos que WordPress pone a tu disposición para hacerlo bien. Pero gracias al paquete @wordpress/scripts, montar el entorno de desarrollo JavaScript es extremadamente más sencillo de lo que era hace unos meses.
Espero que la entrada de hoy te haya gustado. Y, como siempre, si te quedas atascado en algún punto o tienes dudas, déjanos un comentario y te echaremos una mano.
¡Ah! Por cierto, aquí te dejo un enlace a mi Github con el proyecto listo para descargarlo y probarlo. Cuando lo tengas, haz un npm install y un npm run build para poder probarlo 😉
Imagen destacada de Ashim D’Silva en Unsplash.
Deja una respuesta