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

Mucha gente se queja de los obstáculos para empezar a construir 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 enorme cantidad de información, pero es posible que se pierda en ese mar de detalles.

Y cabe mencionar lo que Matías 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 del bloque 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? ¡Seguro que lo será!

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

Con suerte, los lectores intermedios y avanzados nos perdonarán por no profundizar en ciertos conceptos como el estado de React, la tienda Redux, los componentes de alto nivel, 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 bloques dinámicos y metacajas.

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

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

Comenzar con el desarrollo de bloques de Gutenberg puede ser intimidante al principio… 😵‍💫 ¡Pero no temas! Esta guía completa para principiantes lo cubre 🙏Haz clic para tuitear

¿Qué es un bloque de Gutenberg?

Desde su lanzamiento por primera vez en diciembre de 2018, el editor de bloques se ha mejorado enormemente 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 la edición completa del sitio y mucho más. .

En resumen, incluso si Gutenberg todavía está en un gran desarrollo, ha recorrido un largo camino, y hoy, el editor de bloques es un candidato de pleno derecho como un creador de páginas y sitios 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 hacerle pensar en una versión mejorada del editor de contenido tradicional.

Queremos dejar esto en 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 las 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 hoy logramos en WordPress con códigos cortos, HTML personalizado y descubrimiento integrado en una única API consistente y experiencia de usuario.

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 de 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 un render() función.

Si bien la experiencia de edición que ofrece 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 núcleo.

Las publicaciones (y esto incluye publicaciones, páginas y tipos de publicaciones personalizadas) creadas con Gutenberg todavía se almacenan en el wp_posts table, exactamente igual que 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.

Estos datos se parecen a comentarios HTML y tienen una función específica: bloques delimitadores:

Delimitadores de bloque dígale a WordPress qué bloque se va a representar en la pantalla. También proporcionan valores para propiedades de bloque en un objeto JSON. Esos accesorios dictan la forma en que se debe representar el bloque en la pantalla:

Configuración de su entorno de desarrollo de WordPress

La configuración de 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 lo 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 simplificar las cosas, no cubriremos la transpilación en este artículo (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 utilizar 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.

La configuración de 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 formas 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 Node Installer. Todo lo que necesita hacer es descargar la versión correspondiente a su sistema operativo e iniciar el asistente de instalación:

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

Ahora está equipado con las siguientes herramientas:

• los npx Ejecutor de paquetes de Node.js (ver documentos). Esto le permite ejecutar un npm comando sin instalarlo primero.
• los npm Administrador de paquetes Node.js (ver documentos). Se utiliza 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 utilizar un entorno de desarrollo local como DevKinsta o utilizar 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, nuestro moderno desarrollo local de WordPress herramienta. O puede optar por una herramienta de desarrollo local diferente, como MAMP o XAMPP:

Opción 2: wp-env

También puedes optar por el oficial wp-env , que proporciona un entorno de desarrollo local de WordPress que puede ejecutar 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 WordPress locales indoloros. Proporciona decisiones sobre las opciones para que los usuarios puedan activar WordPress rápidamente sin perder tiempo. De hecho, el objetivo es hacer que estos entornos sean fácilmente accesibles para todos, ya sea desarrollador, diseñador, administrador o cualquier otra persona.

Si decide probarlo, instale 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: instalar @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.

Puedes instalar wp-env ya sea a nivel mundial 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

Analicemos eso:

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

wp-env --version

Deberías ver la corriente wp-env versión, 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 WordPress usando 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: Configuración de 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 admitida 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 demás que necesita para iniciar el proyecto.

Está inspirado en gran medida en create-react-app. Felicitaciones a @gaearon, a todo el equipo de Facebook y a 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 comando, y proporcionará todos los archivos y carpetas que necesita para crear el andamio 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 / wp-content / plugins / directorio y ejecute el siguiente comando:

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

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

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

¡Y eso es!

Ahora inicie su entorno de desarrollo de WordPress y vaya a la Complementos pantalla en el panel 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 el Widgets sección y seleccione su nuevo bloque:

Ahora regrese a la terminal y cambie el directorio actual a mi-primer-bloque:

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: Configuración de 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 dev-toolkit 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.

Como el oficial create-block herramienta, create-guten-block se basa en create-react-app 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 de WordPress moderno, incluido lo siguiente:

• Soporte de sintaxis React, JSX y ES6.
• proceso de construcción de desarrollo / producción 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 complicaciones para las herramientas anteriores con una única dependencia cgb-scripts.

Tenga en cuenta la siguiente advertencia:

La compensación 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 el / wp-content / plugins carpeta 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 regrese a su panel de WordPress. Debe aparecer un nuevo elemento en la pantalla Complementos: es el mi-primer-bloque enchufar:

Active el complemento y vuelva a la terminal. Cambiar el directorio actual a mi-primer-bloque, entonces corre 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 usar:

npm run build

Active el complemento y cree una nueva publicación o página, luego explore sus bloques y seleccione su nuevo bloque 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 de bloque de inicio

Cualquiera de las dos herramientas de desarrollo: create-block o create-guten-block – opta por, ahora tiene un andamio de bloques que puede usar como punto de partida para construir un complemento de bloque.

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

Andamio de bloques es un término abreviado que describe la estructura de directorio de soporte que necesita para que WordPress reconozca un bloque. Normalmente, ese directorio incluye archivos como index.php, index.js, style.cssy otros, que a su vez retienen llamadas como register_block_type.

Optamos por el oficial Crear bloque dev-tool, como se usa en el Manual del editor de bloques. Pero incluso si decide utilizar una herramienta de terceros como create-guten-block, tu experiencia no será muy diferente.

Dicho esto, profundicemos en el create-block herramienta.

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

Como mencionamos anteriormente, Create Block es la herramienta de línea de comandos oficial para crear bloques de Gutenberg. Corriendo @wordpress/create-block en su terminal genera los archivos PHP, JS y SCSS y el código necesario 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 archivo de un complemento de bloque creado con la herramienta oficial Crear bloque:

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

El archivo de complemento

Con el archivo de complemento principal, 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' );

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

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 block.json se encuentra el archivo, o una completa WP_Block_Type objeto
• Una matriz de argumentos de tipo de bloque

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

El archivo package.json

El archivo package.json define las propiedades y los scripts 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"
	}
}

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

En este artículo, usaremos los siguientes comandos:

• npm run build – crear una construcción de producción (comprimida)
• npm run start – crear una compilación de desarrollo (sin comprimir)

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

La única dependencia de desarrollo predeterminada es la @wordpress/scripts paquete, que se define como «una colección de scripts reutilizables diseñados para el desarrollo de WordPress».

El archivo block.json

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

Teniendo un block.json file proporciona varios beneficios, incluido un rendimiento mejorado 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á su puesta en cola de activos optimizada desde el primer momento. Los activos de CSS y JavaScript de frontend enumerados en el style o script las propiedades 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.

Ejecutando el @wordpress/create-block comando genera lo siguiente block.json expediente:

{
	"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 – una babosa 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 – el dominio de texto del complemento
• editorScript – definición de script del editor
• editorStyle – definición de estilo del editor
• style – proporciona estilos alternativos para un bloque

Además de las propiedades enumeradas anteriormente, puede (y probablemente lo hará) definir una attributes objeto que proporciona información sobre los datos almacenados por su bloque. En tus block.json puede establecer cualquier número de atributos en valor clave pares, 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" 
	}
},

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

La carpeta src

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

• index.js
• edit.js
• save.js
• editor.scss
• style.scss

index.js

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

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 declaración importa el registerBlockType función de la @wordpress/blocks paquete. Las siguientes declaraciones de importación importan la hoja de estilo junto con la Edit y save funciones.

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

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

edit.js

edit.js es donde construirás 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 el __ función de la @wordpress/i18n paquete (este paquete contiene una versión JavaScript de las funciones de traducción), el useBlockProps Reaccionar gancho, y el editor.scss expediente.

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

save.js

los save.js archivo es donde construimos la estructura de bloques para ser guardados 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 style.scss

Aparte de los scripts, dos archivos SASS residen en el src carpetas. los editor.scss archivo contiene los estilos aplicados al bloque en el contexto del editor, mientras que el style.scss El archivo 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

los node_modules La carpeta 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 instala npm los paquetes.

los build La carpeta 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 de JavaScript y sintaxis de ESNext.

El proyecto: Construyendo su primer bloque Gutenberg

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

El bloque constará de dos columnas, con una imagen a la izquierda y un párrafo de texto a la derecha. Se colocará un botón con un enlace personalizable 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 tenga una comprensión clara de los conceptos básicos, puede seguir adelante 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:

¡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 el / wp-content / plugins carpeta:

Ahora, ejecute 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 los datos necesarios para su bloque fácilmente. Para nuestro ejemplo usaremos los siguientes detalles:

• Bloquear babosa: mi-bloque-afiliado
• Espacio de nombres interno: mi-complemento-afiliado
• Título de visualización del bloque: Bloque de afiliados
• Descripción breve del bloque: Un bloque de ejemplo para 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, ejecute el siguiente comando desde el / wp-content / plugins carpeta:

cd my-affiliate-block

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

npm start

Ahora abra la pantalla Complementos para buscar y activar el Bloque de afiliados enchufar:

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

block.json en el trabajo

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

Entonces, abre 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 style Las propiedades proporcionan las rutas relativas a los estilos y scripts de frontend y backend.

No es necesario que registre manualmente los scripts y estilos definidos aquí porque WordPress los registra y pone en cola automáticamente. Para demostrarlo, inicie el inspector del navegador y abra el La red pestaña:

Como puede ver en la imagen de arriba, nuestro index.js guión que reside en el construir La carpeta se ha puesto en cola con regularidad. sin tener que agregar ningún código PHP.

Etiquetas de interfaz de usuario

los title y description Las propiedades 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 utilizando propiedades y atributos. Por ejemplo, puede agregar uno o más keywords para ayudar a los usuarios a buscar bloques:

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

Si ahora ingresa «kinsta», «afiliado» o «dinero» en el insertador rápido, el editor le sugerirá el bloque de afiliados:

Localización

Si se pregunta cómo ocurre la localización de las cadenas en el archivo JSON, aquí está la respuesta:

En JavaScript, puede usar ahora registerBlockTypeFromMetadata método de @wordpress/blocks paquete para registrar un tipo de bloque usando los metadatos cargados desde block.json expediente. Todas las propiedades localizadas se envuelven automáticamente en _x (de @wordpress/i18n package) llamadas a funciones similares a cómo funciona en PHP con register_block_type_from_metadata. El único requisito es establecer el textdomain propiedad en el block.json expediente.

Aquí estamos usando el registerBlockType función en lugar de registerBlockTypeFromMetadata, ya que este último ha quedado obsoleto desde Gutenberg 10.7, pero el mecanismo es el mismo.

Uso de componentes integrados: el componente RichText

Los elementos que componen un bloque de Gutenberg son componentes de React, y puede acceder a estos componentes a través del wp variable global. Por ejemplo, intente escribir wp.editor en la consola de su navegador. Esto le dará la lista completa de los componentes incluidos en el wp.editor módulo.

Desplácese por la lista y adivine a qué componentes están destinados por sus nombres.

Del mismo modo, puede consultar la lista de componentes incluidos en el wp.components módulo:

Ahora vuelve al edit.js archivo y eche un vistazo más de cerca al 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 y no editable. Pero podemos cambiar las cosas fácilmente:

Para que el texto sea editable, tendrá que reemplazar el actual <p> etiqueta con un componente que hace que el contenido de entrada sea editable. Para eso, Gutenberg proporciona el componente RichText integrado.

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

1. Importe los componentes necesarios de 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 abre el edit.js archivo y cambie lo siguiente import declaración:

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

…para:

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

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

useBlockProps

los useBlockProps React hook marca el elemento contenedor del bloque:

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

Para poner las cosas simplemente, useBlockProps Asignar automáticamente atributos y clases al elemento contenedor (el p elemento en nuestro ejemplo):

Si quitas useBlockProps desde el 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 satisfactoria, 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 variedad de formatos permitidos. Por defecto, todos los formatos están permitidos.
• value – la cadena HTML para hacer editable
• placeholder – 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 proporcionan 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 attributes objeto en pares clave / valor, donde la clave es el nombre del atributo y el valor es la definición del atributo.

Ahora abre el block.json archivo y agregue lo siguiente attributes apuntalar:

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

los content El atributo 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 un enum propiedad.
• 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 (leer más).
• selector es una etiqueta HTML o cualquier otro selector, como un nombre de clase o un atributo de identificación.

Pasaremos el Edit función un objeto de propiedades. Entonces, regrese al edit.js archivo y realice el siguiente cambio:

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

Paso 4: definir controladores de eventos

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

Definamos esa función y veamos el conjunto edit.js texto:

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 panel de WordPress, cree una nueva publicación o página y agregue su bloque de Afiliado:

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 comprueba el resultado de la interfaz, es posible que se sienta un poco decepcionado porque sus cambios no afectan el sitio. Eso es porque tienes que modificar el save.js archivo para almacenar la entrada del usuario en la base de datos cuando se guarda la publicación.

Paso 5: guardar datos

Ahora abre el save.js archivo 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í:

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

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

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

Agregar controles a la barra de herramientas del bloque

La barra de herramientas de 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, puede agregar un control de alineación de texto para su bloque. Todo lo que necesita hacer es importar dos componentes del @wordpress/block-editor paquete.

Seguiremos los mismos pasos que en el ejemplo anterior:

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

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

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

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

Abre el edit.js archivar y editar el import declaración como se muestra a continuación:

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

Paso 2: agregar elementos BlockControls y AlignmentControl

Ve a la Edit función e inserte el <BlockControls /> elemento 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 de arriba, <> y </> son la sintaxis corta para declarar fragmentos de React, que es la forma en que devolvemos múltiples elementos en React.

En este ejemplo, AlignmentControl tiene dos atributos:

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

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

Paso 3: Defina el atributo de alineación en block.json

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

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

Regrese a la terminal, detenga el proceso actual con ^C y comience el guión de nuevo 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 del 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 define onChangeAlign:

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

Si newAlign es undefined, luego establecemos newAlign para none. De lo contrario, usamos newAlign.

Nuestro edit.js El script debe 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

Abierto save.js y cambia el save funcionan 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 attribute objeto usando 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 vuelva al editor en el modo de editor de código. El código debería verse así:

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

¡Hormiga, eso es todo! 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.

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 una InspectorControls componente 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 utiliza para mostrar configuraciones de uso menos frecuente o configuraciones que requieren más espacio en la pantalla. La barra lateral de configuración debe usarse para solo configuraciones a nivel de bloque.

Si tiene configuraciones que afectan solo al contenido seleccionado dentro de un bloque (ejemplo: la configuración «negrita» para el texto seleccionado dentro de un párrafo): no lo 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.

De nuevo:

1. Importar componentes necesarios de paquetes de WordPress
2. Incluya los elementos correspondientes en su código JSX
3. Definir 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 a los usuarios personalizar aspectos específicos del bloque. Por ejemplo, puede proporcionar un panel de control de color. Para hacerlo, deberá importar el InspectorControls y PanelColorSettings componentes de la block-editor módulo:

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 el Edit función:

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 style atributo del RichText elemento:

<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: definir los atributos necesarios en block.json

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

"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 necesitas 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 save.js archivo 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 de nuevo. Actualice la página, elimine cualquier instancia de su bloque y agréguela nuevamente a su publicación:

Realice sus cambios, guarde la publicación y véala en la interfaz. Los cambios que realizó en el editor de bloques deben reflejarse en el sitio frontal.

Agregar y personalizar un enlace externo

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

• Un ExternalLink componente 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 de @ wordpress / components

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

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 una palanca 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 ExternalLink elemento al mismo nivel de RichText en un div envase:

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

</div>

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

Por defecto, el rel el valor del atributo se establece en noopener noreferrer. Nuestro código agregará el nofollow palabra clave para el rel atributo del resultante a etiqueta cuando el control de alternancia es sobre.

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

Primero, agregará un PanelBody elemento interior 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. los title atributo proporciona el título del panel.
2. initialOpen establece si el panel está inicialmente abierto o no.

A continuación, agregaremos dos PanelRow elementos en el interior PanelBodyy un TextControl elemento dentro de cada uno 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 configurar la etiqueta del enlace y la URL.

También agregaremos un adicional PanelRow con un ToggleControl para activar / desactivar una opción específica, como 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: definir los atributos necesarios en block.json

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

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

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

Paso 4: definir los controladores de eventos

Vuelve al edit.js archivo 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 el save funcionar 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 un a elemento en lugar de ExternalLink:

Ahora guarde los datos y reinicie su entorno.

Agregar varios 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 bloque, pero también podemos proporcionar un conjunto de estilos de bloque predefinidos que el usuario puede elegir con un solo clic.

Para este propósito, usaremos una función útil de Block API: Block Styles.

Todo lo que necesita hacer es definir el block.json styles propiedad y declare 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 regrese al editor de bloques:

Los estilos estarán disponibles para el usuario haciendo clic en el conmutador de bloques y luego buscando el Panel de estilos en el Barra lateral de configuración de bloque.

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

is-style-{style-name}

Si marcó el estilo «Borde», entonces un is-style-border la clase se agregará a la p elemento. Si marcó el estilo «Predeterminado», entonces un is-style-default en su lugar, se agregará la clase.

Ahora solo tienes que declarar las propiedades CSS. Abre el editor.scss archivo 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 de nuevo.

¡Y eso es! Actualiza la página y diviértete con tus nuevos estilos de bloques:

Anidación de bloques de Gutenberg con el componente InnerBlocks

Aunque es 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.

los InnerBlocks componente se define de la siguiente manera:

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

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

Ahora deberá importar el nuevo recurso a la index.js expediente:

import './container';

Volver a container.js e importar 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 principal y nuestro bloque de afiliados 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 blockTypes (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 templateLock: 'all' Bloqueos de atributos Bloques de columnas para que el usuario no agregue, reordene ni 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.

A continuación, la plantilla se asigna al InnerBlocks elemento:

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

Para evitar cualquier problema de compatibilidad, también agregamos un templateLock atribuir a la InnerBlocks componente (vea también el problema # 17262 y tire # 26128).

Aquí está nuestro final container.js expediente:

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 backgroundColor atributo al párrafo generado por el RichText componente. Sin embargo, es posible que prefiramos asignar el color de fondo al contenedor. div:

Entonces, cambia el edit.js archivo y save.js divs 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 la useBlockProps método. En el código original, definimos la constante blockProps como sigue:

const blockProps = useBlockProps();

Pero podemos usar el useBlockProps pasar más eficazmente un conjunto de propiedades. Por ejemplo, podemos importar classnames desde el classnames módulo y establezca el nombre de la clase contenedora respectivamente.

En el siguiente ejemplo, asignamos un nombre de clase basado en el valor de la align atributo (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 save.js expediente:

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.

Si está buscando una guía detallada para comenzar con el desarrollo de bloques de Gutenberg, esta guía masiva es para usted. ¡Compruébalo y comienza a construir tus bloques Gutenberg hoy! 👷‍♀️🧱Haz clic para tuitear

Resumen

¡Y aquí estamos, al final de este increíble viaje! Comenzamos 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 React establecida para comenzar a divertirse con el desarrollo de bloques. El desarrollo de bloques podría darle 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 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 detenidamente la documentación y las guías en línea. Entre los muchos recursos disponibles, recomendamos los siguientes:

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

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!