Cómo agregar un botón al editor de Gutenberg usando @wordpress/scripts

Hace casi un año y medio, Antonio escribió esta publicación de blog explicando una de las dificultades que enfrentamos al adaptar nuestros complementos al nuevo editor de bloques de WordPress. El resultado de su tutorial se parecía a esto:

Por suerte o por desgracia, Gutenberg ha cambiado mucho en este año y medio. La pila de desarrollo se ha estado expandiendo y mejorando, y los desarrolladores de complementos y temas tuvieron que adoptar y adaptar las nuevas tecnologías. Y aquellos de nosotros que también escribimos sobre nuestra experiencia y compartimos lo que aprendemos ahora estamos "obligados" a actualizar nuestros tutoriales para que pueda mantenerse actualizado. ¡Pero estamos felices por eso!

Hace unas semanas, Iván, uno de nuestros lectores, nos dejó un comentario en el tutorial de Antonio pidiendo ayuda. Aparentemente no pudo implementar el complemento de Antonio. Y, para ser honesto, esto no me sorprende, porque las cosas han cambiado mucho últimamente. Así que, para ayudar a Iván y a todos los que nos leéis y queréis seguir aprendiendo sobre WordPress, ¡recreemos el tutorial de cómo añadir un botón al editor de bloques de Gutenberg aprovechando todas las nuevas herramientas que nos ofrece WordPress!

crear un complemento

Lo primero que debemos hacer es crear un plugin de WordPress. Esto es bastante sencillo. Básicamente, lo único que tenemos que hacer es crear una carpeta en wp-content/plugins con el nombre que queramos darle a nuestro plugin (por ejemplo, gutenberg-button ) y, dentro de ella, crear un archivo con el mismo nombre y extensión .php extensión .php . Luego escriba el siguiente código en su archivo de complemento:

Ahora, echemos un vistazo más de cerca a lo que hace el fragmento anterior:

• Primero abrimos una etiqueta <?php . No hay sorpresas aquí.
• A continuación, en este archivo principal, agregamos un comentario de varias líneas. El comentario incluye varias líneas con pares "Clave/Valor". Por ejemplo, vemos como especificamos el nombre del plugin ( Plugin Name ), su versión ( Version ) o el nombre del autor ( Author ). Toda esta información será visible en la sección Complementos dentro de WordPress.
• Finalmente, agregamos un código repetitivo:
  • especificamos un espacio de namespace (hablamos de espacios de nombres aquí),
  • nos aseguramos de que, si el archivo se ejecuta, se ejecute como parte de WordPress, y
  • definimos algunas constantes sobre el complemento (que serán útiles más adelante).

Una vez hayamos hecho todo esto, si vamos a la pantalla de Plugins de nuestro WordPress, veremos que ahí está el Botón de Gutenberg :

lo activamos y… ¡listo! Claro, no hará nada, pero ya está ahí.

Desarrollo de complementos de JavaScript

Hoy en día, los desarrolladores de WordPress deben dominar JavaScript. Esa es una de las consecuencias de que Gutenberg esté en el centro, supongo. Y este tutorial no es una excepción.

Preparando el ambiente

Si queremos agregar un nuevo botón a la interfaz de Gutenberg, debemos codificar esta función en JavaScript. Entonces, preparemos el entorno de desarrollo de JavaScript en nuestro complemento. Para hacer esto, simplemente ejecute el siguiente comando desde su línea de comando (asegúrese de estar en wp-content/plugins/gutenberg-button cuando lo haga):

 npm init

y sigue las instrucciones:

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

El resultado de este proceso es un archivo package.json . Como verá en unos momentos, este archivo será extremadamente útil en el futuro.

Como ya he revelado en el título de esta publicación, usaremos @wordpress/scripts para crear nuestro complemento. Así que vamos a agregarlo como una dependencia ejecutando el siguiente comando:

 npm install --save-dev @wordpress/scripts

Este comando descargará un montón de dependencias dentro de nuestro complemento (bajo node_modules ) y modificará nuestro package.json para que quede claro que @wordpress/scripts ahora es una dependencia de desarrollo.

Si echa un vistazo a la documentación de este paquete, verá que incluye muchos scripts para compilar, validar sintaxis, formatear código, 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" } }

así que editemos nuestro archivo package.json para que la sección "scripts" contenga todos los comandos recomendados.

Cómo comprobar que todo funciona…

Creemos una carpeta src en la raíz de su proyecto y agreguemos un archivo index.js dentro de ella. Este será el archivo JavaScript principal de nuestro complemento y contendrá todo su código (luego puede organizar el código como desee, siempre que el archivo principal sea src/index.js ).

Probemos si las cosas funcionan como se esperaba agregando la siguiente declaración index.js :

 console.log( 'Hi!' );

y construir el proyecto usando npm run build . Esto transpilará su código en algo que un navegador pueda ejecutar (en realidad no era necesario en este momento, pero lo será en solo un par de minutos) y generará un nuevo script dentro de una carpeta de build .

Todo lo que tenemos que hacer ahora es decirle a WordPress que este script existe para que pueda cargarlo. Para hacerlo, simplemente abra el archivo principal de su complemento ( gutenberg-button.php ) y agregue las siguientes 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 presta atención, verá que simplemente le estamos diciendo a WordPress que ponga en cola nuestro nuevo script /build/index.js como recurso del editor de bloques. De esta forma, cuando un usuario acceda al editor de bloques, nuestro script formará parte de los activos que incluirá el editor.

Así que echemos un vistazo a esto. Vaya a su panel de WordPress, edite una publicación y mire la consola de JavaScript de su navegador. Si las cosas salieron como se esperaba, debería ver "¡Hola!" escrito en la consola:

Replicando nuestro tutorial para agregar un botón a Gutenberg

Bien, ahora que hemos visto que podemos escribir código JavaScript y npm run build en algo que nuestros navegadores entiendan, es hora de replicar el tutorial de Antonio. Y esto, querido lector, es extremadamente simple.

Abra el archivo src/index.js y reemplace la declaración anterior de console.log con lo siguiente:

Como puedes ver, este es casi el mismo código que escribió Antonio hace unos meses. La principal diferencia es el hecho de que ya no usamos la variable global wp para acceder a las funciones y componentes de Gutenberg; en cambio, ahora confiamos en declaraciones de import . Pero aparte de eso, es más o menos lo mismo.

Una vez que haya escrito el código, simplemente npm run build y ¡listo! Ya tienes el botón en Gutenberg:

Asegurémonos de que funcione seleccionando algún texto y haciendo clic en el botón:

y listo, ¡vemos que el texto aparece en la consola nuevamente!

Una nota final sobre las dependencias...

Si echa un vistazo dentro de la carpeta de build , verá que @wordpress/scripts no solo ha creado un archivo index.js , sino que también tiene un archivo index.asset.php . Este archivo define un objeto pequeño con dos propiedades:

• una lista de dependencias (es decir, scripts de WordPress) requeridas por nuestro complemento
• una versión de compilación

Podemos (y debemos) usar ambas propiedades al poner en cola nuestro script en WordPress si queremos asegurarnos de que se ejecutará correctamente. Para hacerlo, simplemente regrese a gutenberg-button.php y cámbielo como se muestra 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' );

Simplemente cargue el objeto en index.asset.php usando una declaración de include y reemplace la lista de dependencias que teníamos ( [] ) con las dependencias reales y use el número de compilación como la versión del complemento.

Conclusiones

Crear complementos de WordPress realmente útiles es complicado. Debes entender bien cómo funciona JavaScript y estar familiarizado con todos los recursos que tiene WordPress. Pero gracias al paquete @wordpress/scripts , preparar el entorno de desarrollo de JavaScript y crear un complemento de JavaScript que pueda ejecutarse dentro de WordPress es más fácil que nunca.

Espero que les haya gustado el post de hoy. Y, como siempre, si te quedas atascado en algún punto o tienes preguntas, déjanos un comentario y te ayudaremos.

Ah, y por cierto, aquí tienes un enlace al proyecto, listo para descargar y probar si así lo deseas. Simplemente clone el proyecto, npm install todas las dependencias, npm run build y ¡pruébelo!

Imagen destacada de Ashim D'Silva en Unsplash.