Creación de bloques de Gutenberg personalizados: el tutorial de desarrollo de bloques definitivo

Muchas personas se quejan de los obstáculos para comenzar a crear bloques y aplicaciones de Gutenberg. La curva de aprendizaje es empinada, principalmente debido a la dificultad de instalar y configurar el entorno de desarrollo. Además, un conocimiento sólido de JavaScript, Node.js, React y Redux son ingredientes imprescindibles para esta receta bastante compleja.

El manual oficial del editor de bloques de WordPress proporciona a los desarrolladores una gran cantidad de información, pero es posible que te pierdas en ese mar de detalles.

Y vale la pena mencionar lo que Matias Ventura, arquitecto principal del proyecto Gutenberg, informó en su entrevista con WP Tavern:

Si bien hay personas que pueden aprenderlo rápidamente, sigue siendo una gran barrera para las personas. Creo que hay varias capas en esto; la documentación podría ser un orden de magnitud mejor tanto en organización como en presentación. Espero que podamos hacer mucho más allí.

Con eso en mente, hemos decidido proporcionar un tutorial paso a paso destinado a ayudar a nuestros lectores a comenzar con el desarrollo de bloques de Gutenberg.

¿Suena interesante? ¡Vamos a sumergirnos!

Requisitos previos para el desarrollo de bloques de Gutenberg

Para este tutorial, las únicas habilidades requeridas son un buen conocimiento del desarrollo de complementos de WordPress y al menos una comprensión básica de HTML, CSS, JavaScript y React.

¿Será este un proyecto ambicioso? ¡Apuesto a que lo será!

No fue fácil encontrar el compromiso adecuado entre integridad y simplicidad o decidir qué temas incluir y cuáles dejar de lado.

Con suerte, los lectores intermedios y avanzados nos perdonarán por no profundizar en ciertos conceptos como el estado React, la tienda Redux, los componentes de alto orden, etc. Estos temas requieren espacio y atención adicionales y probablemente sean demasiado avanzados para comenzar el desarrollo de bloques (a menos que sea un desarrollador de React).

Por la misma razón, no cubriremos algunos de los temas más avanzados relacionados con el desarrollo de bloques de Gutenberg, como los bloques dinámicos y los metaboxes.

Con el conocimiento que obtendrá al final de este artículo, podrá comenzar a divertirse y ser productivo de inmediato.

Una vez que comience a construir bloques, estará preparado para mejorar aún más sus habilidades y construir bloques de Gutenberg aún más avanzados por su cuenta.

¿Qué es un bloque de Gutenberg?

Desde que se lanzó por primera vez en diciembre de 2018, el editor de bloques ha mejorado mucho en todos los aspectos: API más potentes, una interfaz de usuario más avanzada, usabilidad mejorada, un montón de bloques nuevos, las primeras implementaciones de Edición completa del sitio y mucho más. .

En resumen, incluso si Gutenberg todavía está bajo un fuerte desarrollo, ha recorrido un largo camino, y hoy en día, el editor de bloques es un candidato completo como un creador de sitios y páginas confiable y funcional.

Desde el punto de vista de un desarrollador, Gutenberg es una aplicación de página única (SPA) basada en React que permite a los usuarios de WordPress crear, editar y eliminar contenido en WordPress. Sin embargo, esto no debería hacerte pensar en una versión mejorada del editor de contenido tradicional.

Queremos dejar esto claro:

En Gutenberg, el contenido se divide en bloques, que son "ladrillos" que los usuarios pueden usar para crear publicaciones y páginas o sus sitios web completos.

Pero, ¿qué es técnicamente un bloque?

Nos gusta la definición de WordPress:

"Bloque" es el término abstracto utilizado para describir unidades de marcado que, compuestas juntas, forman el contenido o el diseño de una página web. La idea combina conceptos de lo que logramos hoy en WordPress con códigos abreviados, HTML personalizado e incrustar el descubrimiento en una sola API y experiencia de usuario consistentes.

Los títulos, párrafos, columnas, imágenes, galerías y todos los elementos que componen la interfaz del editor, desde los paneles de la barra lateral hasta los controles de la barra de herramientas del bloque, son componentes de React.

Entonces, ¿qué son los componentes de React? W3Schools proporciona la siguiente definición:

Los componentes son bits de código independientes y reutilizables. Tienen el mismo propósito que las funciones de JavaScript, pero funcionan de forma aislada y devuelven HTML a través de una función render() .

Si bien la experiencia de edición que brinda Gutenberg es nueva en comparación con el editor clásico de WordPress, la forma en que WordPress almacena sus piezas de contenido en la base de datos no cambia en absoluto. Eso es porque Gutenberg es una aplicación que funciona dentro de WordPress pero no cambia la forma en que funciona el CMS en su esencia.

Las publicaciones (y esto incluye publicaciones, páginas y tipos de publicaciones personalizadas) creadas con Gutenberg todavía se almacenan en la tabla wp_posts , exactamente como con el editor clásico.

Pero en una publicación creada con Gutenberg, encontrará información adicional en la tabla que representa una diferencia fundamental entre las publicaciones creadas a través del Editor clásico y Gutenberg.

Estas piezas de información parecen comentarios HTML y tienen una función específica: delimitar bloques:

Los delimitadores de bloque le dicen a WordPress qué bloque se representará en la pantalla. También proporcionan valores para propiedades de bloque en un objeto JSON. Esos accesorios dictan la forma en que el bloque debe representarse en la pantalla:

Configuración de su entorno de desarrollo de WordPress

Configurar un entorno de desarrollo de JavaScript moderno requiere un conocimiento sólido de tecnologías avanzadas como Webpack, React y JSX, Babel, ESLint, etc.

intimidado? ¡No seas! La comunidad de WordPress ya ha venido al rescate al proporcionar herramientas poderosas que le permiten evitar un proceso de configuración manual complicado.

Para mantener las cosas simples, no cubriremos la transpilación en este artículo (con el cual, sin embargo, recomendamos que se familiarice una vez que haya aprendido los conceptos básicos del desarrollo de bloques). En su lugar, presentaremos dos herramientas alternativas que puede usar para configurar rápida y fácilmente un entorno de desarrollo de JavaScript moderno en pocos minutos. Depende de usted elegir el que le resulte más conveniente para su proyecto.

Configurar un entorno de desarrollo de JavaScript para construir bloques de Gutenberg es un proceso de tres pasos:

1. Instale Node.js y npm
2. Configurar el entorno de desarrollo
3. Configurar el complemento de bloque

Empecemos.

1. Instale Node.js y npm

Antes de instalar su entorno de desarrollo y registrar su primer bloque, deberá instalar Node.js y el administrador de paquetes de Node (npm).

Puede instalar Node.js y npm de varias maneras diferentes. Pero primero, es posible que desee verificar si el software ya está instalado en su máquina.

Para hacer esto, inicie la terminal y ejecute el siguiente comando:

 node -v

Si el resultado es command not found , entonces Node.js no está instalado en su computadora y puede continuar con la instalación.

Para este artículo, hemos elegido la opción de instalación más sencilla, que es el Instalador de nodos. Todo lo que necesita hacer es descargar la versión correspondiente a su sistema operativo y ejecutar el asistente de instalación:

Una vez que haya instalado Node.js, ejecute el comando node -v en su terminal nuevamente. También puede ejecutar el comando npm -v para confirmar que tiene el paquete npm disponible.

Ahora está equipado con las siguientes herramientas:

• El ejecutor del paquete npx Node.js (ver documentos). Esto le permite ejecutar un comando npm sin instalarlo primero.
• El administrador de paquetes npm Node.js (ver documentos). Esto se usa para instalar dependencias y ejecutar scripts.

El siguiente paso es instalar el entorno de desarrollo.

2. Configure su entorno de desarrollo

Una vez que tenga las últimas versiones de Node.js y npm en su máquina local, necesitará un entorno de desarrollo para WordPress.

Puede usar un entorno de desarrollo local como DevKinsta o usar la herramienta oficial de WordPress. Echemos un vistazo a ambas opciones.

Opción 1: Entorno de desarrollo local (DevKinsta)

Con solo unos pocos clics, puede instalar WordPress localmente usando DevKinsta, nuestra moderna herramienta local de desarrollo de WordPress. O puede optar por una herramienta de desarrollo local diferente, como MAMP o XAMPP:

Opción 2: wp-env

También puede optar por la herramienta oficial wp-env , que proporciona un entorno de desarrollo local de WordPress que puede iniciar directamente desde la línea de comandos. Noah Alen lo define de la siguiente manera:

Los entornos locales de WordPress ahora son tan simples como ejecutar un solo comando. wp-env es una herramienta de configuración cero para entornos de WordPress locales sencillos. Brinda decisiones sobre opciones para que los usuarios puedan activar rápidamente WordPress sin perder tiempo. De hecho, el objetivo es hacer que estos entornos sean fácilmente accesibles para todos, ya sea un desarrollador, diseñador, administrador o cualquier otra persona.

Si decide intentarlo, la instalación wp-env requiere un esfuerzo mínimo. Solo sigue estos pasos:

Paso 1: Confirme la instalación de Docker y Node.js

Para cumplir con los requisitos técnicos, primero deberá tener Docker y Node.js instalados en su computadora. Eso es porque wp-env crea una instancia de Docker que ejecuta un sitio web de WordPress. Cualquier cambio realizado en el código se refleja inmediatamente en la instancia de WordPress.

Paso 2: Instale @wordpress/env desde la línea de comandos

Con Docker y Node.js ejecutándose en su computadora, puede continuar e instalar el entorno de desarrollo de WordPress.

Puede instalar wp-env forma global o local. Para hacerlo globalmente, deberá ejecutar el siguiente comando desde el directorio de complementos (más sobre esto en el cuadro de aviso "Importante" a continuación):

 npm install -g @wordpress/env

Vamos a desglosarlo:

• npm install instala el paquete.
• -g agregado al comando instala el paquete especificado globalmente.
• @wordpress/env es el paquete que vas a instalar.

Para confirmar que wp-env se ha instalado correctamente, ejecute el siguiente comando:

 wp-env --version

Debería ver la versión actual wp-env , lo que significa que ahora puede iniciar el entorno usando el siguiente comando desde la carpeta de su complemento:

 wp-env start

Puede acceder al panel de control de WordPress utilizando la siguiente dirección:

• http://localhost:8888/wp-admin/

Las credenciales predeterminadas son las siguientes:

• Nombre de usuario: admin
• contraseña: password

Configure su complemento de bloque

Ahora necesita un complemento de bloque de inicio para construir. Pero en lugar de crear manualmente un complemento de bloque de desarrollo con todos los archivos y carpetas necesarios, simplemente puede ejecutar una herramienta de desarrollo que proporcione todos los archivos y configuraciones que necesita para comenzar con el desarrollo de bloques.

Nuevamente, tiene un par de opciones para elegir. Echemos un vistazo a cada uno.

Opción 1: configurar un complemento de bloque con @wordpress/create-block

@wordpress/create-block es la herramienta oficial de configuración cero para crear bloques de Gutenberg:

Create Block es una forma oficialmente compatible de crear bloques para registrar un bloque para un complemento de WordPress. Ofrece una configuración de construcción moderna sin configuración. Genera código PHP, JS, CSS y todo lo que necesitas para iniciar el proyecto.

Está inspirado en gran medida en create-react-app. Felicitaciones importantes a @gaearon, todo el equipo de Facebook y la comunidad de React.

Una vez que su entorno local esté en funcionamiento, puede configurar un bloque de inicio simplemente ejecutando el npx @wordpress/create-block , y le proporcionará todos los archivos y carpetas que necesita para crear el andamiaje del complemento y registrar un nuevo bloque. .

Hagamos una prueba para ver cómo funciona.

Desde su herramienta de línea de comandos, navegue hasta el directorio /wp-content/plugins/ y ejecute el siguiente comando:

 npx @wordpress/create-block my-first-block

Cuando se le pida que confirme, ingrese y para continuar:

El proceso lleva unos momentos. Cuando esté completo, debería obtener la siguiente respuesta:

¡Y eso es!

Ahora inicie su entorno de desarrollo de WordPress y vaya a la pantalla Complementos en el panel de control de WordPress. Se debería haber agregado un nuevo complemento llamado "Mi primer bloque" a su lista de complementos:

Active el complemento si es necesario, cree una nueva publicación de blog, desplácese hacia abajo en el insertador de bloques hasta la sección Widgets y seleccione su nuevo bloque:

Ahora regrese a la terminal y cambie el directorio actual a my-first-block :

 cd my-first-block

Luego ejecute el siguiente comando:

 npm start

Esto le permite ejecutar el complemento en modo de desarrollo. Para crear el código de producción, debe usar el siguiente comando:

 npm run build

Opción 2: configurar un complemento de bloque con create-guten-block

create-guten-block es una herramienta de desarrollo de terceros para construir bloques de Gutenberg:

create-guten-block es un kit de herramientas de desarrollo de configuración cero (#0CJS) para desarrollar bloques de WordPress Gutenberg en cuestión de minutos sin configurar React, webpack, ES6/7/8/Next, ESLint, Babel, etc.

Al igual que la herramienta oficial create-block , create-guten-block se basa en la aplicación create-react y puede ayudarlo a generar su primer complemento de bloque sin problemas.

El kit de herramientas proporciona todo lo que necesita para crear un complemento moderno de WordPress, incluido lo siguiente:

• Compatibilidad con la sintaxis de React, JSX y ES6.
• Proceso de compilación de producción/desarrollo de webpack detrás de escena.
• Extras de lenguaje más allá de ES6 como el operador de extensión de objetos.
• CSS con prefijo automático, por lo que no necesita -webkit u otros prefijos.
• Un script de compilación para agrupar JS, CSS e imágenes para la producción con mapas de origen.
• Actualizaciones sin problemas para las herramientas anteriores con una única dependencia cgb-scripts.

Tenga en cuenta la siguiente advertencia:

La contrapartida es que estas herramientas están preconfiguradas para funcionar de una manera específica. Si su proyecto necesita más personalización, puede "expulsarlo" y personalizarlo, pero luego deberá mantener esta configuración.

Una vez que tenga un sitio web local de WordPress a mano, inicie su herramienta de línea de comandos, navegue hasta la carpeta /wp-content/plugins de su instalación y ejecute el siguiente comando:

 npx create-guten-block my-first-block

Tendrá que esperar uno o dos minutos mientras se crea la estructura del proyecto y se descargan las dependencias:

Cuando se complete el proceso, debería ver la siguiente pantalla:

La siguiente imagen muestra la estructura del proyecto con la terminal ejecutándose en Visual Studio Code:

Ahora vuelve a tu panel de WordPress. Debería aparecer un nuevo elemento en la pantalla Complementos: es el complemento mi primer bloque :

Active el complemento y vuelva a la terminal. Cambie el directorio actual a my-first-block , luego ejecute npm start :

 cd my-first-block npm start

Debería obtener la siguiente respuesta:

Nuevamente, esto le permite ejecutar el complemento en modo de desarrollo. Para crear el código de producción, debe utilizar:

 npm run build

Active el complemento y cree una nueva publicación o página, luego explore sus bloques y seleccione su nuevo bloque de Gutenberg:

Para obtener una descripción más detallada o en caso de errores, consulte la documentación proporcionada por Ahmad Awais.

Un recorrido por el andamio del bloque de inicio

Cualquiera de las dos herramientas de desarrollo ( create-block o create-guten-block ) que elijas, ahora tienes un andamiaje de bloques que puedes usar como punto de partida para crear un complemento de bloques.

Pero, ¿qué es exactamente el andamio de bloques?

Block scaffolding es un término abreviado que describe la estructura de directorios de soporte que necesita para que WordPress reconozca un bloque. Por lo general, ese directorio incluye archivos como index.php , index.js , style.css y otros, que a su vez contienen llamadas como register_block_type .

Optamos por la herramienta de desarrollo oficial Crear bloque , ya que se usa en el Manual del editor de bloques. Pero incluso si decide usar una herramienta de terceros como create-guten-block , su experiencia no será muy diferente.

Dicho esto, profundicemos en la herramienta create-block .

Una mirada más cercana a la herramienta de desarrollo Crear bloque

Como mencionamos anteriormente, Create Block es la herramienta oficial de línea de comandos para crear bloques de Gutenberg. Ejecutar @wordpress/create-block en su terminal genera los archivos PHP, JS y SCSS y el código necesarios para registrar un nuevo tipo de bloque:

 npx @wordpress/create-block [options] [slug]

• [slug] (opcional): se usa para asignar el bloque slug e instalar el complemento
• [options] (opcional) — opciones disponibles

De forma predeterminada, se asigna una plantilla de ESNext. Esto significa que obtendrá la próxima versión de JavaScript, con la adición de la sintaxis JSX.

Si omite el nombre del bloque, el comando se ejecuta en modo interactivo, lo que le permite personalizar varias opciones antes de generar los archivos:

 npx @wordpress/create-block

La siguiente imagen muestra la estructura de archivos de un complemento de bloque creado con la herramienta oficial Create Block:

Dicho esto, repasemos los archivos y carpetas principales de nuestro nuevo complemento de bloque.

El archivo de complemento

Con el archivo principal del complemento, registra el bloque en el servidor:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

La función register_block_type registra un tipo de bloque en el servidor utilizando los metadatos almacenados en el archivo block.json .

La función toma dos parámetros:

• El nombre del tipo de bloque, incluido el espacio de nombres, o una ruta a la carpeta donde se encuentra el archivo block.json , o un objeto WP_Block_Type completo
• Una matriz de argumentos de tipo bloque

En el código anterior, el argumento de tipo de bloque lo proporciona la constante mágica __DIR__ . Eso significa que el archivo block.json reside en la misma carpeta que el archivo del complemento.

El archivo paquete.json

El archivo package.json define las propiedades y secuencias de comandos de JavaScript para su proyecto. Aquí es donde puede instalar las dependencias de su proyecto.

Para comprender mejor para qué sirve este archivo, ábralo con su editor de código favorito:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

La propiedad scripts es un diccionario que contiene comandos que se ejecutan en varios momentos del ciclo de vida de un paquete mediante npm run [cmd] .

En este artículo, usaremos los siguientes comandos:

• npm run build : crea una compilación de producción (comprimida)
• npm run start : crea una compilación de desarrollo (sin comprimir)

Las dependencies y devDependencies son dos objetos que asignan un nombre de paquete a una versión. dependencies son necesarias en producción, mientras que devDependences solo son necesarias para el desarrollo local (leer más).

La única dependencia de desarrollo predeterminada es el paquete @wordpress/scripts , que se define como "una colección de scripts reutilizables adaptados para el desarrollo de WordPress".

El archivo block.json

A partir de WordPress 5.8, el archivo de metadatos block.json es la forma canónica de registrar tipos de bloques.

Tener un archivo block.json brinda varios beneficios, incluido un mejor rendimiento y una mejor visibilidad en el directorio de complementos de WordPress:

Desde una perspectiva de rendimiento, cuando los temas admiten activos de carga diferida, los bloques registrados con block.json tendrán sus activos en cola optimizados de forma inmediata. Los activos CSS y JavaScript de la interfaz que se enumeran en las propiedades de style o secuencia de script solo se pondrán en cola cuando el bloque esté presente en la página, lo que resultará en tamaños de página reducidos.

Ejecutar el comando @wordpress/create-block genera el siguiente archivo block.json :

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Aquí está la lista completa de propiedades predeterminadas:

• apiVersion : la versión de la API utilizada por el bloque (la versión actual es 2)
• name : un identificador único para un bloque que incluye un espacio de nombres
• version — la versión actual de un bloque
• title — un título de visualización para un bloque
• category - una categoría de bloque
• icon : un slug de Dashicon o un icono SVG personalizado
• description : una breve descripción visible en el inspector de bloques
• supports : un conjunto de opciones para controlar las funciones utilizadas en el editor
• textdomain de texto: el dominio de texto del complemento
• editorScript — definición de script del editor
• editorStyle — definición del estilo del editor
• style : proporciona estilos alternativos para un bloque

Además de las propiedades enumeradas anteriormente, puede (y probablemente lo hará) definir un objeto de attributes que proporcione información sobre los datos almacenados por su bloque. En su block.json puede establecer cualquier cantidad de atributos en pares clave/valor , donde la clave es el nombre del atributo y el valor es la definición del atributo.

Eche un vistazo al siguiente ejemplo de definiciones de atributos:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

Profundizaremos en el archivo block.json más adelante en este artículo, pero también puede consultar el Manual del editor de bloques para obtener información más detallada sobre los metadatos y atributos de block.json .

La carpeta src

La carpeta src es donde ocurre el desarrollo. En esa carpeta, encontrará los siguientes archivos:

• índice.js
• editar.js
• guardar.js
• editor.scss
• estilo.scss

índice.js

El archivo index.js es su punto de partida. Aquí importará dependencias y registrará el tipo de bloque en el cliente:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

La primera instrucción importa la función registerBlockType del paquete @wordpress/blocks . Las siguientes declaraciones de importación importan la hoja de estilo junto con las funciones Edit y save .

La función registerBlockType registra el componente en el cliente. La función toma dos parámetros: un namespace/block-name (el mismo que está registrado en el servidor) y un objeto de configuración de bloque.

La función Edit proporciona la interfaz de bloque tal como se presenta en el editor de bloques, mientras que la función save proporciona la estructura que se serializará y guardará en la base de datos (leer más).

editar.js

edit.js es donde construirá la interfaz de administración de bloques:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Primero, importa la función __ del paquete @wordpress/i18n (este paquete contiene una versión de JavaScript de las funciones de traducción), el useBlockProps React y el archivo editor.scss .

A continuación, exporta el componente React (lea más sobre declaraciones de importación y exportación).

guardar.js

El archivo save.js es donde construimos la estructura del bloque que se guardará en la base de datos:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss y estilo.scss

Aparte de los scripts, dos archivos SASS residen en las carpetas src . El archivo editor.scss contiene los estilos aplicados al bloque en el contexto del editor, mientras que el archivo style.scss contiene los estilos del bloque para mostrar en la interfaz. Profundizaremos en estos archivos en la segunda parte de esta guía.

Los node_modules y las carpetas de compilación

La carpeta node_modules contiene módulos de nodo y sus dependencias. No profundizaremos en los paquetes de nodos, ya que está más allá del alcance de este artículo, pero puede leer más en este artículo sobre dónde npm instala los paquetes.

La carpeta de build contiene los archivos JS y CSS resultantes del proceso de compilación. Puede profundizar en el proceso de compilación en las guías de configuración de compilación JavaScript y sintaxis de ESNext.

El proyecto: construir su primer bloque de Gutenberg

Es hora de ensuciarnos las manos. Esta sección le enseñará cómo crear un complemento que proporcione un bloque CTA llamado Affiliate Block.

El bloque constará de dos columnas, con una imagen a la izquierda y un párrafo de texto a la derecha. Un botón con un enlace personalizable se colocará debajo del texto:

Este es solo un ejemplo simple, pero nos permite cubrir los conceptos básicos del desarrollo de bloques de Gutenberg. Una vez que obtenga una comprensión clara de los conceptos básicos, puede continuar y crear bloques de Gutenberg cada vez más complejos con la ayuda del Manual del editor de bloques y cualquier otro de los vastos recursos disponibles.

Suponiendo que tiene la última versión de WordPress ejecutándose en su entorno de desarrollo local, esto es lo que aprenderá de aquí en adelante:

• Cómo configurar el complemento del bloque de inicio
• bloque.json en el trabajo
• Uso de componentes integrados: el componente de texto enriquecido
• Adición de controles a la barra de herramientas de bloque
• Personalización de la barra lateral de configuración de bloque
• Agregar y personalizar un enlace externo
• Agregar múltiples estilos de bloque
• Anidamiento de bloques con el componente InnerBlocks
• Mejoras adicionales

¡En sus marcas, listos, fuera!

Cómo configurar el complemento del bloque de inicio

Inicie su herramienta de línea de comandos y navegue hasta la carpeta /wp-content/plugins :

Ahora, ejecuta el siguiente comando:

 npx @wordpress/create-block

Este comando genera los archivos PHP, SCSS y JS para registrar un bloque en modo interactivo, lo que le permite agregar fácilmente los datos necesarios para su bloque. Para nuestro ejemplo, usaremos los siguientes detalles:

• Slug de bloque : mi-afiliado-bloque
• Espacio de nombres interno : mi-afiliado-plugin
• Título de visualización del bloque : bloque de afiliados
• Breve descripción del bloque : un bloque de ejemplo para los lectores de Kinsta
• Dashicon : dinero
• Nombre de la categoría : diseño
• Autor del complemento : tu nombre
• Licencia : –
• Enlace al texto de la licencia : –
• Versión actual del complemento : 0.1.0

La instalación del complemento y todas las dependencias lleva un par de minutos. Cuando se complete el proceso, verá la siguiente respuesta:

Ahora, ejecuta el siguiente comando desde la carpeta /wp-content/plugins :

 cd my-affiliate-block

Finalmente, desde dentro de la carpeta de su complemento ( mi bloque de afiliados en nuestro ejemplo), puede comenzar el desarrollo con:

 npm start

Ahora abra la pantalla Complementos para encontrar y activar el complemento Bloqueo de afiliados :

Cree una nueva publicación, abra el insertador de bloques y desplácese hacia abajo hasta la categoría Diseño . Haga clic para agregar el bloque de afiliados:

bloque.json en el trabajo

Como mencionamos anteriormente, el registro del bloque del lado del servidor se lleva a cabo en el archivo principal .php . Sin embargo, no definiremos la configuración en el archivo .php . En su lugar, usaremos el archivo block.json .

Por lo tanto, abra block.json nuevamente y eche un vistazo más de cerca a la configuración predeterminada:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Guiones y Estilos

editorScript , editorStyle y las propiedades de style proporcionan las rutas relativas a los scripts y estilos de frontend y backend.

No tiene que registrar manualmente los scripts y estilos definidos aquí porque WordPress los registra y los pone en cola automáticamente. Para probar eso, inicie el inspector del navegador y abra la pestaña Red :

Como puede ver en la imagen de arriba, nuestro script index.js que reside en la carpeta de compilación se ha puesto en cola regularmente sin tener que agregar ningún código PHP .

Regístrese para recibir el boletín

¿Quiere saber cómo aumentamos nuestro tráfico en un 1000 %?

¡Únase a más de 20,000 personas que reciben nuestro boletín semanal con consejos internos de WordPress!

Suscríbase ahora

Etiquetas de interfaz de usuario

Las propiedades de title y description proporcionan las etiquetas necesarias para identificar el bloque en el editor:

Palabras clave

Como mencionamos anteriormente, puede configurar con precisión la configuración de su bloque usando propiedades y atributos. Por ejemplo, puede agregar una o más keywords para ayudar a los usuarios a buscar bloques:

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Localización

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Este código genera un bloque estático con texto simple no editable. Pero podemos cambiar las cosas fácilmente:

Para hacer que el texto sea editable, deberá reemplazar la etiqueta <p> actual con un componente que haga que el contenido de entrada sea editable. Para eso, Gutenberg proporciona el componente RichText incorporado.

Agregar un componente incorporado a su bloque es un proceso de 5 pasos:

1. Importe los componentes necesarios desde un paquete de WordPress
2. Incluya los elementos correspondientes en su código JSX
3. Defina los atributos necesarios en el archivo block.json
4. Definir controladores de eventos
5. Guardar datos

Paso 1: importe los componentes necesarios de un paquete de WordPress

Ahora abra el archivo edit.js y cambie la siguiente declaración de import :

 import { useBlockProps } from '@wordpress/block-editor';

…para:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

De esta manera, está importando la función useBlockProps y el componente RichText del paquete @wordpress/block-editor .

usarBlockProps

El gancho useBlockProps React marca el elemento contenedor del bloque:

Al usar la versión 2 de la API, debe usar el nuevo gancho useBlockProps en la función de edit del bloque para marcar el elemento contenedor del bloque. El gancho insertará los atributos y los controladores de eventos necesarios para habilitar el comportamiento del bloque. Cualquier atributo que desee pasar al elemento de bloque debe pasarse a través useBlockProps y el valor devuelto se distribuirá en el elemento.

En pocas palabras, useBlockProps asigna automáticamente atributos y clases al elemento contenedor (el elemento p en nuestro ejemplo):

Si elimina useBlockProps del elemento contenedor, tendría una cadena de texto simple sin acceso a la funcionalidad y el estilo del bloque:

Como explicaremos más adelante, también puedes pasar a useBlockProps un objeto de propiedades para personalizar la salida.

Texto rico

El componente RichText proporciona una entrada editable, lo que permite a los usuarios editar y formatear el contenido.

Encontrará el componente documentado en GitHub en gutenberg/packages/block-editor/src/components/rich-text/README.md.

Paso 2: incluya los elementos correspondientes en su código JSX

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Comentemos el código línea por línea:

• tagName — el nombre de la etiqueta del elemento HTML editable
• onChange — función llamada cuando cambia el contenido del elemento
• allowedFormats : una matriz de formatos permitidos. Por defecto, todos los formatos están permitidos
• value — la cadena HTML para hacer editable
• placeholder de posición: texto de marcador de posición para mostrar cuando el elemento está vacío

Paso 3: Defina los atributos necesarios en el archivo block.json

Los atributos brindan información sobre los datos almacenados por un bloque, como contenido enriquecido, color de fondo, URL, etc.

Puede establecer un número arbitrario de atributos dentro de un objeto de attributes en pares clave/valor, donde la clave es el nombre del atributo y el valor es la definición del atributo.

Ahora abra el archivo block.json y agregue los siguientes attributes prop:

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

El atributo de content permite almacenar el texto escrito por el usuario en el campo editable:

• type indica el tipo de datos almacenados por el atributo. El tipo es obligatorio a menos que defina una propiedad de enum .
• source define cómo se extrae el valor del atributo del contenido de la publicación. En nuestro ejemplo, es el contenido HTML. Tenga en cuenta que si no proporciona una propiedad de origen, los datos se almacenan en el delimitador de bloque (lea más).
• selector es una etiqueta HTML o cualquier otro selector, como un nombre de clase o un atributo de identificación.

Pasaremos a la función Edit un objeto de propiedades. Por lo tanto, vuelva al archivo edit.js y realice el siguiente cambio:

 export default function Edit( { attributes, setAttributes } ) { ... }

Paso 4: Definir controladores de eventos

El elemento RichText tiene un atributo onChange , que proporciona una función para llamar cuando cambia el contenido del elemento.

Definamos esa función y veamos todo el script edit.js :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Ahora guarde el archivo y ejecute npm run start en la ventana de su terminal. Luego, regrese a su tablero de WordPress, cree una nueva publicación o página y agregue su bloque de Afiliados:

Agregue algo de texto y cambie a la vista Código. Así es como debería verse su código:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Si ahora guarda la página y verifica el resultado de la interfaz, puede sentirse un poco decepcionado porque sus cambios no afectan el sitio. Esto se debe a que debe modificar el archivo save.js para almacenar la entrada del usuario en la base de datos cuando se guarda la publicación.

Paso 5: Guardar datos

Ahora abra el archivo save.js y cambie el script de la siguiente manera:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

Eso es lo que estamos haciendo aquí:

• Importe el componente RichText del paquete block-editor .
• Pase varias propiedades a través de un argumento de objeto a la función de save (en este ejemplo, solo estamos pasando la propiedad de attributes )
• Devolver el contenido del componente RichText

Puede leer más sobre el componente RichText en el Manual del editor de bloques y encontrar la lista completa de accesorios en Github.

Ahora vamos a dar un paso más. En la siguiente sección, aprenderá cómo agregar controles a la barra de herramientas de bloque.

Adición de controles a la barra de herramientas de bloque

La barra de herramientas del bloque contiene un conjunto de controles que permiten a los usuarios manipular partes del contenido del bloque. Para cada control de la barra de herramientas, encontrará un componente:

Por ejemplo, podría agregar un control de alineación de texto para su bloque. Todo lo que necesita hacer es importar dos componentes del paquete @wordpress/block-editor .

Seguiremos los mismos pasos que en el ejemplo anterior:

1. Importar componentes requeridos de paquetes de WordPress
2. Incluya los elementos correspondientes en su código JSX
3. Defina los atributos necesarios en el archivo block.json
4. Definir controladores de eventos
5. Guardar datos

Paso 1: Importe componentes BlockControls y AlignmentControl desde @wordpress/block-editor

Para agregar un control de alineación a la barra de herramientas de bloque, necesita dos componentes:

• BlockControls representa una barra de herramientas dinámica de controles (sin documentar).
• AlignmentControl presenta un menú desplegable que muestra las opciones de alineación para el bloque seleccionado (leer más)

Abra el archivo edit.js y edite la declaración de import como se muestra a continuación:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Paso 2: agregar elementos BlockControls y AlignmentControl

Vaya a la función Edit e inserte el <BlockControls /> al mismo nivel que <RichText /> . Luego agregue y <AlignmentControl /> dentro de <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

En el código anterior, <> y </> son la sintaxis abreviada para declarar fragmentos de React, que es cómo devolvemos varios elementos en React.

En este ejemplo, AlignmentControl tiene dos atributos:

• value proporciona el valor actual para el elemento
• onChange proporciona un controlador de eventos para ejecutar cuando cambia el valor

También hemos definido atributos adicionales para el elemento RichText (consulte la lista completa de atributos con ejemplos)

Paso 3: Defina el atributo align en block.json

Ahora ve al archivo block.json y agrega el atributo align :

 "align": { "type": "string", "default": "none" }

Regrese a la terminal, detenga el proceso actual con ^C y vuelva a iniciar el script con npm run start . Luego regrese al editor de bloques, actualice la página y seleccione el bloque. Debería ver la barra de herramientas de bloque con un control de alineación:

Ahora, si intenta formatear el contenido del bloque usando los nuevos controles de alineación, verá que no pasa nada. Eso es porque aún no hemos definido el controlador de eventos.

Paso 4: definir los controladores de eventos

Ahora defina onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Si newAlign no está undefined , establecemos newAlign en none . De lo contrario, usamos newAlign .

Nuestro script edit.js debería estar completo (por ahora):

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Ahora puede volver al editor y alinear el contenido del bloque.

Necesitamos modificar la función de guardar para almacenar el contenido y los atributos del bloque en la base de datos.

Paso 5: Guardar datos

Abra save.js y cambie la función de save de la siguiente manera:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Finalmente, para que el código sea más legible, puede extraer las propiedades individuales del objeto de attribute utilizando la sintaxis de asignación de desestructuración:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Guarde el archivo, reinicie el proceso y regrese al editor en modo Editor de código. El código debería ser algo como esto:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

¡Y eso es! Acaba de agregar un control de alineación a la barra de herramientas del bloque.

Puede leer más sobre los controles de la barra de herramientas de bloques en el Manual del editor de bloques.

Personalización de la barra lateral de configuración de bloque

También puede agregar controles a la barra lateral de configuración del bloque (o incluso crear una nueva barra lateral para su aplicación).

La API proporciona un componente InspectorControls para eso.

El manual del editor de bloques explica cómo usar la barra lateral de configuración:

La barra lateral de configuración se usa para mostrar configuraciones que se usan con menos frecuencia o configuraciones que requieren más espacio en la pantalla. La barra lateral de configuración debe usarse solo para la configuración a nivel de bloque .

Si tiene una configuración que afecta solo al contenido seleccionado dentro de un bloque (por ejemplo: la configuración en "negrita" para el texto seleccionado dentro de un párrafo): no la coloque dentro de la barra lateral de configuración. La barra lateral de configuración se muestra incluso cuando se edita un bloque en modo HTML, por lo que solo debe contener configuraciones a nivel de bloque.

Otra vez:

1. Importar componentes requeridos de paquetes de WordPress
2. Incluya los elementos correspondientes en su código JSX
3. Defina los atributos necesarios en el archivo block.json
4. Definir controladores de eventos
5. Guardar datos

Paso 1. Importe los componentes InspectorControls y PanelColorSettings desde @wordpress/block-editor

Puede agregar varios controles para permitir que los usuarios personalicen aspectos específicos del bloque. Por ejemplo, puede proporcionar un panel de control de color. Para hacerlo, deberá importar los componentes InspectorControls y PanelColorSettings desde el módulo block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Paso 2: incluya los elementos correspondientes en su código JSX

Ahora puede agregar los elementos correspondientes al JSX devuelto por la función Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Tenga en cuenta que también hemos actualizado el atributo de style del elemento RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Paso 3: Defina los atributos necesarios en block.json

Ahora defina los atributos backgroundColor y textColor en el archivo block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Paso 4: definir los controladores de eventos

Ahora necesita definir dos funciones para actualizar backgroundColor y textColor en la entrada del usuario:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Paso 5: Guardar datos

Un último paso: abra el archivo save.js y cambie el script de la siguiente manera:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Ahora detenga el proceso (^C) y ejecute npm run start nuevamente. Actualice la página, elimine cualquier instancia de su bloque y agréguelo nuevamente a su publicación:

Realice sus cambios, guarde la publicación y visualícela en la interfaz. Los cambios que realizó en el editor de bloques deben reflejarse en el sitio principal.

Agregar y personalizar un enlace externo

En esta sección, agregará nuevos componentes a su tipo de bloque:

• Un componente ExternalLink que permite a los usuarios agregar un enlace personalizable al bloque de afiliados
• Varios controles de la barra lateral que permiten a los usuarios personalizar la configuración de los enlaces

Paso 1. Importar componentes desde @wordpress/components

Ahora necesita importar varios componentes de @wordpress/components . Abra su archivo edit.js y agregue la siguiente declaración de import :

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody agrega un contenedor plegable a la barra lateral de configuración.
• PaneRow produce un contenedor genérico para los controles de la barra lateral.
• TextControl proporciona un control de entrada de texto.
• ToggleControl proporciona un conmutador que permite a los usuarios habilitar/deshabilitar una opción específica
• ExternalLink es un componente simple para agregar un enlace externo.

Paso 2. Incluya los elementos correspondientes en su código JSX

Primero agregará el elemento ExternalLink al mismo nivel de RichText en un contenedor div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

El componente ExternalLink no está documentado, por lo que nos referimos al propio componente para obtener la lista de atributos disponibles. Aquí estamos usando los atributos href , className y rel .

De forma predeterminada, el valor del atributo rel se establece en noopener noreferrer . Nuestro código agregará la palabra clave nofollow al atributo rel de a etiqueta resultante cuando el control de alternar esté activado .

Ahora puede agregar configuraciones de enlaces a la barra lateral del bloque.

Primero, agregará un elemento PanelBody dentro de InspectorControls al mismo nivel que PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Esto es lo que estamos haciendo con esto:

1. El atributo de title proporciona el título del panel.
2. initialOpen establece si el panel está inicialmente abierto o no.

A continuación, agregaremos dos elementos PanelRow dentro de PanelBody y un elemento TextControl dentro de cada PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

El código anterior ahora debería verse bastante sencillo. Los dos controles de texto permiten a los usuarios establecer la etiqueta del enlace y la URL.

También agregaremos un PanelRow adicional con un ToggleControl para activar/desactivar una opción específica, como si incluir un atributo o no:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Paso 3: Defina los atributos necesarios en block.json

Ahora defina los atributos affiliateLink , linkLabel y hasLinkNofollow en el archivo block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

¡Nada más que agregar aquí! Pasemos a definir las funciones de manejo de eventos.

Paso 4: definir los controladores de eventos

Regrese al archivo edit.js y agregue las siguientes funciones:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Estas funciones actualizan los valores de atributo correspondientes en la entrada del usuario.

Paso 5: Guardar datos

Por último, tenemos que actualizar la función de save en save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Tenga en cuenta que aquí hemos utilizado a elemento a normal en lugar de ExternalLink :

Ahora guarde los datos y reinicie su entorno.

Agregar múltiples estilos de bloque

En una sección anterior, aprendió cómo agregar un control de barra de herramientas de bloque que permite a los usuarios alinear la entrada del usuario. Podemos agregar más controles de estilo a la barra de herramientas de bloques, pero también podemos proporcionar un conjunto de estilos de bloques predefinidos que el usuario puede elegir con un solo clic.

Para este propósito, vamos a utilizar una función útil de la API de bloques: los estilos de bloques.

Todo lo que necesita hacer es definir la propiedad de styles block.json y declarar los estilos correspondientes en sus hojas de estilo.

Por ejemplo, puede agregar la siguiente matriz de estilos:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

Con esto, acaba de agregar un estilo predeterminado y un estilo adicional llamado border . Ahora vuelve al editor de bloques:

Los estilos estarán disponibles para el usuario haciendo clic en el selector de bloques y luego buscando el panel Estilos en la barra lateral de configuración de bloques .

Seleccione un estilo y verifique las clases aplicadas al elemento p . Haga clic con el botón derecho en el bloque e Inspeccionar . Se ha agregado una nueva clase con un nombre estructurado de la siguiente manera:

 is-style-{style-name}

Si marcó el estilo "Borde", se agregará una clase is-style-border al elemento p . Si marcó el estilo "Predeterminado", se agregará en su lugar una clase is-style-default .

Ahora solo tienes que declarar las propiedades CSS. Abra el archivo editor.scss y reemplace los estilos actuales con lo siguiente:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Ahora puedes hacer lo mismo con style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Detenga el proceso (^C) y ejecute npm run start nuevamente.

¡Y eso es! Actualice la página y diviértase con sus nuevos estilos de bloques:

Anidación de bloques de Gutenberg con el componente InnerBlocks

Aunque completamente funcional, nuestro Bloque de Afiliados todavía no es muy atractivo. Para hacerlo más atractivo para la audiencia, podríamos agregar una imagen.

Esto puede agregar una capa de complejidad a nuestro bloque, pero afortunadamente, no necesita reinventar la rueda porque Gutenberg proporciona un componente específico que puede usar para crear una estructura de bloques anidados.

El componente InnerBlocks se define de la siguiente manera:

InnerBlocks exporta un par de componentes que se pueden usar en implementaciones de bloques para habilitar el contenido de bloques anidados.

Primero, deberá crear un nuevo archivo .js en la carpeta src . En nuestro ejemplo, llamaremos a este archivo container.js .

Ahora deberá importar el nuevo recurso en el archivo index.js :

 import './container';

Regrese a container.js e importe los componentes necesarios:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

El siguiente paso es definir una plantilla que proporcione la estructura dentro de la cual se colocarán los bloques. En el siguiente ejemplo, definimos una plantilla que consta de dos columnas que contienen un bloque de Imagen central y nuestro bloque de Afiliado personalizado:

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

La plantilla está estructurada como una matriz de tipos de bloque (nombre de bloque y atributos opcionales).

En el código anterior, usamos varios atributos para configurar las columnas y los bloques de columnas. Específicamente, el atributo templateLock: 'all' bloquea los bloques de columnas para que el usuario no agregue, reordene o elimine bloques existentes. templateLock puede tomar uno de los siguientes valores:

• all : InnerBlocks está bloqueado y no se pueden agregar, reordenar ni eliminar bloques.
• insert : los bloques solo se pueden reordenar o eliminar.
• false : la plantilla no está bloqueada.

Luego, la plantilla se asigna al elemento InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Para evitar cualquier problema de compatibilidad, también agregamos un atributo templateLock al componente InnerBlocks (consulte también el problema n.º 17262 y extraiga el n.º 26128).

Aquí está nuestro archivo container.js final:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Mejoras adicionales

Nuestro bloque es completamente funcional, pero podríamos mejorarlo un poco con algunos pequeños cambios.

Asignamos el atributo backgroundColor al párrafo generado por el componente RichText . Sin embargo, podemos preferir asignar el color de fondo al div del contenedor:

Entonces, cambie el archivo edit.js y save.js div s de la siguiente manera:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Esto permitirá al usuario cambiar el fondo de todo el bloque.

Por otro lado, un cambio más relevante implica el método useBlockProps . En el código original, definimos la constante blockProps de la siguiente manera:

 const blockProps = useBlockProps();

Pero podemos usar useBlockProps de manera más efectiva pasando un conjunto de propiedades. Por ejemplo, podemos importar classnames de clase desde el classnames de nombres de clase y establecer el nombre de la clase contenedora en consecuencia.

En el siguiente ejemplo, asignamos un nombre de clase en función del valor del atributo de align ( edit.js ):

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Haremos el mismo cambio en el archivo save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

¡Y eso es una envoltura! Ahora puede ejecutar la compilación para producción.

Resumen

¡Y aquí estamos, al final de este increíble viaje! Empezamos con la configuración del entorno de desarrollo y terminamos creando un tipo de bloque completo.

Como mencionamos en la introducción, un conocimiento sólido de Node.js, Webpack, Babel y React es esencial para crear bloques avanzados de Gutenberg y posicionarse en el mercado como un desarrollador profesional de Gutenberg.

Sin embargo, no es necesario tener una experiencia establecida en React para comenzar a divertirse con el desarrollo de bloques. El desarrollo de bloques podría brindarle motivación y objetivos para adquirir habilidades cada vez más amplias en las tecnologías detrás de los bloques de Gutenberg.

Esta guía, por lo tanto, está lejos de ser completa. Es simplemente una introducción a una amplia variedad de temas que lo ayudarán a comenzar a construir sus primeros bloques de Gutenberg.

Por este motivo, le recomendamos que profundice sus conocimientos leyendo atentamente la documentación y las guías en línea. Entre los muchos recursos disponibles, recomendamos los siguientes:

• Tutorial oficial de Create a Block para principiantes
• Tutorial oficial de bloques para desarrolladores intermedios
• Bloques dinámicos
• Metacajas
• Crear una barra lateral para su complemento

Si recién está comenzando con el desarrollo de WordPress, es posible que desee comprender los conceptos básicos del desarrollo frontend. Aquí hay una lista rápida de recursos que pueden ayudarlo a comenzar:

• Cómo instalar WordPress localmente (ebook gratuito)
• El valor real del alojamiento administrado de WordPress (libro electrónico gratuito)
• ¿Qué es JavaScript?
• HTML frente a HTML5
• Cómo editar CSS en WordPress
• ¿Qué es PHP?
• El campo de entrenamiento de ganchos de WordPress: cómo usar acciones, filtros y ganchos personalizados

Y recuerda que el código completo de los ejemplos de esta guía está disponible en Gist.

Ahora es tu turno: ¿has desarrollado algún bloque de Gutenberg? ¿Cuáles son las principales dificultades que ha experimentado hasta ahora? ¡Cuéntanos tu experiencia en los comentarios!