Les hooks sont l’une des fonctionnalités fondamentales de WordPress. Ils vous permettent de vous « brancher » sur le cœur de WordPress et d’exécuter votre propre code à des moments précis du cycle de vie de WordPress.
L’éditeur de blocs possède son propre ensemble de hooks qui vous permettent d’interagir avec l’éditeur et de modifier son comportement.
Cette leçon vous présentera différents hooks disponibles dans l’éditeur de blocs et vous expliquera comment les utiliser pour étendre les fonctionnalités de l’éditeur.
Le package @wordpress/hooks
Alors que les hooks d’action et de filtre n’étaient historiquement disponibles qu’en PHP, le fait que l’éditeur de blocs soit construit avec JavaScript signifie qu’il existe désormais également un nouvel ensemble de hooks JavaScript.
Ces hooks d’action et de filtre JavaScript vous permettent de vous brancher sur différents aspects de l’éditeur et d’apporter des modifications au comportement de l’éditeur ou aux blocs eux-mêmes.
Les hooks JavaScript sont enregistrés à l’aide des fonctions addAction et addFilter du package @wordpress/hooks.
Comme pour les versions PHP, vous transmettez le nom du hook et la fonction de rappel à ces fonctions.
La seule différence notable est que vous devez également transmettre l’espace de noms du hook. L’espace de noms est un identifiant unique pour la fonction de rappel et aide à éviter les conflits liés aux collisions de noms.
Examinons un exemple pour montrer comment utiliser un hook JavaScript.
Le filtre blocks.registerBlockType
Pour tous les exemples de blocs présentés jusqu’à présent, vous avez utilisé la fonction registerBlockType du package @wordpress/blocks pour enregistrer un bloc en JavaScript.
Chaque bloc commence par l’enregistrement d’une nouvelle définition de type de bloc à l’aide de cette fonction.
/**
* 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,
} );Lorsque le code qui traite tous les blocs enregistrés est exécuté, toutes les fonctions de rappel liées au hook de filtre blocks.registerBlockType sont exécutées et doivent renvoyer un objet de paramètres de bloc modifié.
const settings = applyFilters(
'blocks.registerBlockType',
blockType,
name,
null
);Ce hook de filtre vous permet de modifier l’objet de paramètres du bloc avant l’enregistrement du bloc.
Pour enregistrer une fonction de rappel sur le filtre blocks.registerBlockType, vous utilisez la fonction addFilter du package @wordpress/hooks.
Créons une extension pour mettre en file d’attente un fichier JavaScript afin d’enregistrer le filtre.
Commencez par créer un répertoire dans votre répertoire wp-content/plugins pour stocker le code des hooks de blocs.
mkdir -p wp-content/plugins/wp-learn-block-hooksCréez le fichier PHP principal de l’extension, wp-learn-block-hooks.php, dans le répertoire nouvellement créé.
Ajoutez ensuite le code suivant pour configurer l’en-tête de l’extension et vous assurer que le code de l’extension ne s’exécute que dans l’environnement 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.
}Ensuite, vous pouvez relier une fonction de rappel à l’action enqueue_block_editor_assets afin de mettre en file d’attente le fichier 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',
),
);
}Notez que vous devez spécifier la dépendance wp-hooks afin de vous assurer que le code de vos hooks de blocs ne se charge qu’une fois le package @wordpress/hooks disponible. En effet, vous allez utiliser la fonction addFilter du package @wordpress/hooks dans le fichier JavaScript.
Créez maintenant un fichier block-hooks.js dans le répertoire de l’extension et commencez par une IIFE (expression de fonction immédiatement invoquée) afin d’empêcher toute fuite de variable de ce code dans la portée globale :
( function(){
} )()Utilisez ensuite la fonction addFilter pour enregistrer une fonction de rappel sur le hook de filtre blocks.registerBlockType :
( function(){
wp.hooks.addFilter(
'blocks.registerBlockType',
'wp-learn-block-hooks/list-block-description',
addListBlockDescription
);
} )()Remarquez comment vous spécifiez un espace de noms unique avant la fonction de rappel addListBlockDescription. L’espace de noms est défini par le développeur et doit être unique pour votre extension.
Créons maintenant la fonction de rappel addListBlockDescription afin qu’elle effectue une action :
function addListBlockDescription( settings, name ) {
if ( name === 'core/list' ) {
settings.description = 'This is a list block';
}
return settings;
}Ici, la fonction de rappel addListBlockDescription reçoit l’objet de paramètres du bloc et le nom du bloc en tant que paramètres.
Elle vérifie ensuite si le bloc en cours d’enregistrement est un bloc de liste et, si c’est le cas, elle modifie la propriété de description de l’objet de paramètres du bloc.
Enfin, comme il s’agit d’un filtre, la fonction doit renvoyer quelque chose ; dans ce cas, elle doit renvoyer l’objet de paramètres modifié.
Pour tester cela, n’activez pas encore l’extension. Modifiez plutôt un article ou une page et recherchez le bloc de liste dans l’outil d’insertion de blocs.
Si vous survolez le bloc de liste, vous devriez voir s’afficher la description « Créer une liste à puces ou numérotée ».
Activez maintenant l’extension.
Une fois l’extension activée, vous devriez voir la description du bloc de liste devenir « Ceci est un bloc de liste ».
Documentation sur les hooks de l’éditeur de blocs
Le manuel de l’éditeur de blocs possède une section consacrée aux hooks de l’éditeur de blocs, qui contient différentes pages pour les différents types de hooks disponibles.
La page Filtres de blocs contient une liste de tous les filtres disponibles permettant de modifier le comportement des blocs existants, avec des sections consacrées à la modification des blocs lors de leur enregistrement, à la modification des blocs sur l’interface publique, à la modification du comportement des blocs dans l’éditeur de blocs, à la suppression des blocs, au masquage des blocs et à la gestion des catégories de blocs.
La page Hooks de l’éditeur documente tous les hooks permettant de modifier l’expérience d’édition, notamment la modification des réglages de l’éditeur, la désactivation des fonctionnalités de répertoire de blocs et de répertoire de compositions, l’extension des fonctionnalités de l’éditeur, le contrôle des données de l’API REST pour l’éditeur et la journalisation des erreurs de l’éditeur.
La page Filtres i18n contient une liste de filtres permettant de modifier les fonctions d’internationalisation utilisées dans l’éditeur.
La page Filtres de l’analyseur documente tous les filtres permettant de modifier l’analyseur de blocs, utilisé pour convertir les données de bloc stockées en mémoire en balisage de bloc stocké dans le contenu de l’article dans la base de données.
Autocomplete est un composant du package @wordpress/block-editor qui permet d’ajouter des complétions automatiques à l’éditeur.
Si vous avez déjà utilisé la fonctionnalité @username dans l’éditeur de blocs, celle-ci repose sur un composant Autocomplete.
La page des filtres Autocomplete explique comment ajouter vos propres complétions automatiques à l’éditeur.
Enfin, la page des filtres de styles globaux documente les filtres ajoutés à WordPress dans la version 6.1, qui permettent aux développeurs de modifier les réglages et les styles globaux d’un thème de blocs tels qu’ils sont définis dans le fichier theme.json.
Toutes ces pages contiennent des exemples détaillés expliquant comment utiliser ces hooks et comment les employer pour étendre les fonctionnalités de l’éditeur de blocs.