Los hooks son una de las características fundamentales de WordPress. Te permiten «engancharte» al núcleo de WordPress y ejecutar tu propio código en puntos específicos del ciclo de vida de WordPress.
El Editor de bloques tiene su propio conjunto de hooks que te permiten interactuar con el editor y modificar su comportamiento.
Esta lección te presentará algunos hooks diferentes disponibles en el Editor de bloques y cómo usarlos para ampliar la funcionalidad del editor.
El paquete @wordpress/hooks
Aunque históricamente los hooks de acción y filtro solo estaban disponibles en PHP, dado que el Editor de bloques está construido con JavScript, ahora también existe un nuevo conjunto de hooks de JavaScript.
Estos hooks de acción y filtro de JavaScript te permiten engancharte a diferentes aspectos del editor y realizar cambios en el comportamiento del editor o en los propios bloques.
Los hooks de JavaScript se registran mediante las funciones addAction y addFilter del @wordpress/hooks paquete.
Al igual que en las versiones de PHP, pasas el nombre del hook y la función de callback a estas funciones.
La única diferencia notable es que también tienes que pasar el espacio de nombres del hook. El espacio de nombres es un identificador único para la función de callback y ayuda a evitar conflictos de colisión de nombres.
Veamos un ejemplo para demostrar cómo usar un hook de JavaScript.
El filtro blocks.registerBlockType
En todos los ejemplos de bloques que has visto hasta ahora, has usado la función registerBlockType del paquete @wordpress/blocks para registrar un bloque en JavaScript.
Cada bloque comienza registrando una nueva definición de tipo de bloque mediante esta función.
/**
* Every block starts by registering a new block type definition.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
*/
registerBlockType( metadata.name, {
/**
* @see ./edit.js
*/
edit: Edit,
/**
* @see ./save.js
*/
save,
} );Cuando se procesan todos los bloques registrados, se ejecuta cualquier función de callback enganchada al hook de filtro blocks.registerBlockType, que debe devolver un objeto de ajustes del bloque modificado.
const settings = applyFilters(
'blocks.registerBlockType',
blockType,
name,
null
);Este hook de filtro te permite modificar el objeto de ajustes del bloque antes de que se registre el bloque.
Para registrar una función de callback en el filtro blocks.registerBlockType, usas la función addFilter del paquete @wordpress/hooks.
Vamos a crear un plugin para poner en cola un archivo JavaScript y registrar el filtro.
Empieza creando un directorio en tu directorio wp-content/plugins para almacenar el código de los hooks del bloque.
mkdir -p wp-content/plugins/wp-learn-block-hooksCrea el archivo PHP principal del plugin, wp-learn-block-hooks.php, en el directorio recién creado.
A continuación, añade el siguiente código para configurar la cabecera del plugin y asegurarte de que el código del plugin solo se ejecute en el entorno de WordPress:
<?php
/**
* Plugin Name: WP Learn Block Hooks
* Description: WP Learn Block Hooks
* Requires at least: 6.6
* Requires PHP: 7.0
* Version: 1.0.0
* Author: The WordPress Contributors
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: wp-learn-block-hooks
*
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}A continuación, puedes enganchar una función de callback a la acción enqueue_block_editor_assets para poner en cola el archivo JavaScript.
add_action( 'enqueue_block_editor_assets', 'wp_learn_block_hooks_editor_assets' );
function wp_learn_block_hooks_editor_assets() {
wp_enqueue_script(
'wp-learn-block-hooks-editor-script',
plugin_dir_url( __FILE__ ) . 'block-hooks.js',
array(
'wp-hooks',
),
);
}Observa que debes especificar la dependencia wp-hooks para asegurarte de que el código de los hooks del bloque solo se cargue una vez que el paquete @wordpress/hooks esté disponible. Esto se debe a que vas a usar la función addFilter del paquete @wordpress/hooks en el archivo JavaScript.
Ahora, crea un archivo block-hooks.js en el directorio del plugin y comienza con una IIFE (expresión de función ejecutada inmediatamente) para evitar que cualquier variable de este código se filtre al ámbito global:
( function(){
} )()A continuación, usa la función addFilter para registrar un callback en el hook de filtro blocks.registerBlockType:
( function(){
wp.hooks.addFilter(
'blocks.registerBlockType',
'wp-learn-block-hooks/list-block-description',
addListBlockDescription
);
} )()Observa cómo especificas un espacio de nombres único antes de la función de callback addListBlockDescription. El espacio de nombres lo define el desarrollador y debe ser único para tu plugin.
Ahora, vamos a crear la función de callback addListBlockDescription para que haga algo:
function addListBlockDescription( settings, name ) {
if ( name === 'core/list' ) {
settings.description = 'This is a list block';
}
return settings;
}Aquí, la función de callback addListBlockDescription recibe como parámetros el objeto de ajustes del bloque y el nombre del bloque.
A continuación, comprueba si el bloque que se está registrando es un bloque de lista y, si lo es, cambia la propiedad de descripción del objeto de ajustes del bloque.
Por último, como esto es un filtro, debe devolver algo; en este caso, debe devolver el objeto de ajustes modificado.
Para probarlo, no actives todavía el plugin. En su lugar, edita una entrada o página y busca el bloque de lista en el insertador de bloques.
Si pasas el cursor sobre el bloque de lista, deberías ver la descripción «Crea una lista con viñetas o numerada».
Ahora, activa el plugin.
Con el plugin activado, deberías ver que la descripción del bloque de lista cambia a «Este es un bloque de lista».
Documentación sobre los hooks del Editor de bloques
El manual del Editor de bloques tiene una sección dedicada a los hooks del Editor de bloques, que contiene diferentes páginas para los distintos tipos de hooks disponibles.
La página de filtros de bloques contiene una lista de todos los filtros disponibles que te permiten modificar el comportamiento de los bloques existentes, con secciones sobre la modificación de bloques durante el registro de bloques, la modificación de bloques en la interfaz pública, el cambio del comportamiento de los bloques en el Editor de bloques, la eliminación de bloques, la ocultación de bloques y la gestión de categorías de bloques.
Los hooks del editor documentan todos los hooks que te permiten modificar la experiencia del editor, incluida la modificación de los ajustes del editor, la desactivación de las funciones del directorio de bloques y del directorio de patrones, la ampliación de las funciones del editor, el control de los datos de la API REST para el editor y el registro de errores del editor.
La página de filtros de i18n contiene una lista de filtros que te permiten modificar las funciones de internacionalización utilizadas en el editor.
Los filtros del analizador documentan todos los filtros que te permiten modificar el analizador de bloques, que se utiliza para convertir los datos de bloques almacenados en memoria en el marcado de bloques que se almacena en el contenido de la entrada en la base de datos.
Autocompletar es un componente del paquete @wordpress/block-editor que proporciona una forma de añadir autocompletados al editor.
Si alguna vez has usado la función @username en el editor de bloques, esta funciona gracias a un componente de autocompletado.
La página de filtros de Autocompletar documenta cómo puedes añadir tus propios autocompletados al editor.
Por último, la página de filtros de estilos globales documenta los filtros añadidos a WordPress en la versión 6.1 que permiten a los desarrolladores modificar los ajustes y estilos globales de un tema de bloques tal como se definen en el archivo theme.json.
Todas estas páginas incluyen ejemplos detallados sobre cómo usar estos hooks y cómo pueden utilizarse para ampliar la funcionalidad del Editor de bloques.