Découvrez comment enregistrer des blocs et pourquoi block.json est la méthode recommandée.
L’éditeur de site WordPress, alimenté par des blocs, permet aux utilisateurs de créer et de personnaliser leur contenu de manière structurée et visuellement attrayante. Chaque bloc représente un type de contenu spécifique, tel qu’un paragraphe de texte, une image, une vidéo ou tout autre élément personnalisé. Pour que ces blocs fonctionnent correctement, ils doivent être enregistrés avec le noyau WordPress.
Table des matières
Différentes méthodes d’enregistrement en bloc
Côté client
Les blocs enregistrés côté client sont traités par le code JavaScript qui s’exécute sur le navigateur du client. Cela permet d’ajouter et de rendre des blocs à la fois dans l’éditeur WordPress et dans le frontal. Le modifier() La méthode définit comment le bloc sera rendu et interagi avec dans l’éditeur, tandis que la sauvegarder() La méthode définit comment le bloc sera rendu sur le front-end du site Web.
Du côté serveur
Les blocs enregistrés côté serveur peuvent être traités par le code PHP du thème ou du plugin WordPress. Cette méthode offre des fonctionnalités avancées, telles que des champs personnalisés et des données dynamiques, qui affichent le bloc sur le serveur.
Block.json (recommandé)
Les blocs peuvent également être enregistré via un fichier block.json, une nouvelle façon de définir les blocs dans l’éditeur de site et une amélioration par rapport à l’enregistrement côté serveur. L’enregistrement via block.json facilite l’utilisation des blocs dans les plugins et les thèmes, garantissant des métadonnées cohérentes, ce qui peut également améliorer les performances du front-end.
Comment fonctionne le fichier `block.json`
Depuis le déploiement de WordPress 5.8, il est possible d’utiliser un métafichier spécial —`block.json`—qui contient les métadonnées et les paramètres d’un bloc (nom, titre et icône). Ce fichier facilite la distribution et l’installation de blocs sur différents thèmes et plugins en fournissant une manière claire et organisée de définir les blocs et leurs attributs.
La définition de bloc offre l’avantage du partage de code entre JavaScript, PHP et d’autres langages lors du traitement des types de bloc stockés au format JSON. L’enregistrement de blocs avec le fichier block.json simplifie également le processus d’enregistrement, permettant un double enregistrement rapide et facile côté serveur et côté client, en utilisant la fonction PHP WordPress `register_block_type()`.
function wpvip_example_block_registration() {
// By providing a path to a directory as the first argument,
// `register_block_type` will look for a `block.json` file in
// that directory.
// You can also provide the full path to the block.json file.
register_block_type( __DIR__ );
}
add_action( 'init', wpvip_example_block_registration );Le fichier block.json est une excellente option pour ceux qui souhaitent distribuer leurs blocs personnalisés à un public plus large et/ou faciliter leur installation et leur utilisation par d’autres. Grâce à la double inscription facile, le bloc peut être utilisé dans n’importe quel contexte : l’éditeur WordPress, un frontal JavaScript ou une application mobile, même l’API REST.
Cette flexibilité donne aux développeurs plus de pouvoir lors de la création et de la distribution de leurs blocs, en particulier lors de l’ingestion du contenu vers plusieurs frontaux avec une approche omnicanal.
La méthode d’enregistrement block.json peut même aider avec les performances frontales si votre thème prend en charge chargement paresseux de ses actifs. Les blocs enregistrés à l’aide de ce métafichier verront automatiquement leur mise en file d’attente optimisée. Les actifs CSS et JavaScript enregistrés dans les propriétés `style` ou `script` ne seront mis en file d’attente que lorsque le bloc est présent sur la page actuelle, ce qui permet de réduire la taille de la page.
Comment enregistrer un bloc en utilisant `block.json`
Le fichier `block.json` gère l’enregistrement des blocs côté client et côté serveur, et contient tous les attributs et la configuration des blocs nécessaires dans un seul fichier de métadonnées.
1. Créez un nouveau fichier block.json et enregistrez-vous auprès du client
Retrouvez tous les champs disponibles pour ce fichier dans documentation officielle WordPress.org. Ajoutez une entrée de schéma en haut du fichier block.json pour fournir une assistance via les info-bulles, la saisie semi-automatique et la validation (si votre éditeur le prend en charge) pendant la phase de développement.
// block.json file
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"name": "wpvip_example/hello-block",
"title": "Hello Block",
"icon": "shield",
"category": "common",
"attributes": {
"name": {
"type": "string"
}
},
"editor_script": "file:./build/hello-block.js"
}La propriété `editor_script` dans le fichier block.json spécifie le fichier JavaScript qui contient le code pour enregistrer le bloc côté client à l’aide de la fonction `registerBlockType` du package `@wordpress/blocks`. Cette propriété doit pointer vers le chemin relatif du fichier JavaScript dans lequel le bloc est enregistré.
import { registerBlockType } from '@wordpress/blocks';
import metadata from '../block.json';
registerBlockType( metadata, {
edit: () => { /* edit component */ },
save: () => { /* save component, where the rendering happens */ },
}2. Inscrivez-vous côté serveur
Une fois que votre bloc est enregistré côté client avec toutes les métadonnées du fichier `block.json`, il doit être enregistré côté serveur. Pour ce faire, appelez la fonction `register_block_type()` avec le répertoire du bloc comme premier argument (le chemin complet vers le fichier `block.json` peut également être fourni). Le bloc sera enregistré côté client et côté serveur, partageant les mêmes métadonnées comme les attributs de bloc, les styles CSS et les fichiers JS.
// file: hello-block.php
<?php
function wpvip_example_register_hello_block() {
// Register the block using a block.json file in the current directory
register_block_type( __DIR__ );
}
add_action( 'init', 'wpvip_example_register_hello_block' );La fonction `register_block_type` accepte également un deuxième argument, avec un tableau d’arguments de type de bloc, qui peut être utilisé pour configurer la façon dont le bloc est enregistré. Cette fonction peut également enregistrer le bloc avec une fonction de rappel de rendu spécifique, comme indiqué ci-dessous.
<?php
function wpvip_example_register_hello_block() {
// Register the block using a block.json file in the current directory
register_block_type( __DIR__,
array(
'render_callback' => 'wpvip_example_render_hello_block',
)
);
}
add_action( 'init', 'wpvip_example_register_hello_block' );
function wpvip_example_render_hello_block( $attr ) { ... }Alternativement à la définition d’un rappel de rendu, il est possible d’exploiter la propriété `render` dans le fichier `block.json`. Cette propriété spécifie quel fichier PHP sera utilisé pour rendre le bloc côté serveur. Si la propriété `render` et l’argument `render_callback` ne sont pas définis, le rendu sera géré par le côté client, comme le ferait un bloc côté client normal.
// block.json file with server-side rendering
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"name": "wpvip_example/hello-block",
(...)
"render": "file:./render.php"
}Pour plus d’informations sur les arguments disponibles lors de l’enregistrement d’un bloc, consultez le documentation `register_block_type` et Documentation des métadonnées `block.json`.
Avantages de l’utilisation de l’enregistrement de blocs côté serveur et côté client pour les applications découplées
Si vous ne pouvez pas utiliser un fichier block.json, enregistrez-vous au moins côté client et côté serveur. Bien que possible, l’enregistrement exclusif côté client pour les blocs dans l’éditeur de site peut malheureusement limiter la fonctionnalité du bloc, le rendant difficile à utiliser en dehors de l’environnement WordPress. Les problèmes incluent le rendu des blocs lors de la génération de code HTML pour une interface Web ou la génération de composants spécifiques sur une application mobile pour représenter ce bloc.
L’enregistrement côté serveur est particulièrement important pour les applications découplées où le contenu doit circuler du back-end WordPress vers un environnement frontal complètement différent. Si le noyau WordPress ne connaît pas un bloc et ses attributs (en raison de l’absence d’enregistrement côté serveur), il ne fournira pas ces informations via l’API pour être consommées par l’application découplée, et donc l’application ne pourra pas rendre ce contenu correctement.
Le double enregistrement côté serveur et côté client permet une plus grande flexibilité dans l’utilisation du bloc. Il permet à l’API WordPress de reconnaître le bloc, ses attributs et comment générer des données structurées pour représenter ce bloc afin que vous puissiez l’utiliser dans n’importe quel contexte.
Notre recommandation : utilisez l’enregistrement côté serveur, ou le fichier block.json, pour enregistrer les blocs dans WordPress.
Comment enregistrer un bloc côté client côté serveur
Vous pouvez enregistrer un bloc actuel côté client côté serveur sans utiliser le fichier de métadonnées `block.json`.
1. Enregistrez le bloc côté client
Pour ce bloc personnalisé nommé “Hello Block”, qui est enregistré uniquement côté client, nous avons utilisé la fonction `registerBlockType`, avec un attribut nommé `name` (une chaîne simple). Voir l’enregistrement étape par étape ci-dessous.
// file: hello-block.js
import { registerBlockType } from '@wordpress/blocks';
registerBlockType( 'wpvip-example/hello-block', {
title: 'Hello Block',
icon: 'shield',
category: 'common',
attributes: {
name: {
type: 'string',
},
},
edit: ( { className, setAttributes, attributes } ) => {
const { name } = attributes;
return (
<div className={ className }>
<p>Hello {name}</p>
<input
type="text"
value={name}
onChange={(event) => setAttributes({name: event.target.value})}
/>
</div>
);
},
save: ( { attributes } ) => {
const { name } = attributes;
return <p>Hello {name}</p>;
},
} );Le rappel `edit` rend un paragraphe avec le texte `”Hello” + name`, suivi d’un champ de saisie qui vous permet de modifier la valeur `name`. Le rappel `save` renvoie ensuite le paragraphe avec la chaîne comme sortie finale du bloc.
Ce bloc, bien qu’entièrement fonctionnel, est enregistré uniquement du côté client de WordPress, ce qui signifie qu’il n’est visible que par l’éditeur WordPress. En tant que tel, le noyau de WordPress n’est pas au courant de son existence.
2. Enregistrez le bloc côté serveur
Pour le rendre visible au cœur de WordPress, enregistrez-le côté serveur à l’aide de l’API WordPress PHP. Il y a deux façons de faire ça:
- Créer un nouveau fichier PHP pour gérer l’enregistrement côté serveur du bloc
- Utilisez un fichier existant s’il est déjà fourni avec un plugin ou un thème
Enregistrez facilement un bloc côté client côté serveur via le Fonction PHP `register_block_type`. Si nous continuons avec l’exemple “Hello Block”, nous avons juste besoin d’appeler le `register_block_type` comme indiqué ci-dessous.
// file: hello-block.php
<?php
function wpvip_example_register_hello_block() {
// (...) enqueue the scripts and styles (...)
register_block_type('wpvip-example/hello-block' );
}
add_action( 'init', 'wpvip_example_register_hello_block' );Nous avons maintenant enregistré un bloc très simple côté client uniquement côté serveur. Tout le rendu est toujours géré côté client avec la fonction de rappel `save` sur le fichier `hello-block.js`.
Note: le côté serveur ne sait toujours pas quels attributs sont disponibles dans ce bloc car son enregistrement est basique – toute la logique du bloc est gérée côté client.
Comme nous n’avons qu’un seul attribut dans cet exemple (`name`), nous pouvons fournir cette information lors de l’enregistrement du bloc, comme indiqué dans le script ci-dessous.
// file: hello-block.php
<?php
function wpvip_example_register_hello_block() {
// (...) enqueue the scripts and styles (...)
register_block_type( 'wpvip-example/hello-block',
(
'attributes' => (
'name' => (
'default' => 'default name',
'type' => 'string'
),
),
) );
}
add_action( 'init', 'wpvip_example_register_hello_block' );Il est également possible de décharger le rendu côté serveur, en utilisant l’argument `render_callback`. Cette approche rendra le contenu du bloc côté serveur à l’aide de PHP.
// file: hello-block.php
<?php
function wpvip_example_register_hello_block() {
// (...) enqueue the scripts and styles (...)
register_block_type(
'wpvip-example/hello-block',
array(
'attributes' => (...), // block attributes
'render_callback' => 'wpvip_example_render_hello_block',
)
);
}
add_action( 'init', 'wpvip_example_register_hello_block' );
function wpvip_example_render_hello_block( $attributes ) {
return '<p>Hello ' . esc_html( $attributes('name') ) . '</p>';
}Nous avons maintenant deux fonctions de rappel qui gèrent le rendu du bloc : une côté client (le rappel `save`) et une côté serveur (la fonction `wpvip_example_render_hello_block`). Lorsque vous travaillez avec des blocs dynamiques, vous devez renvoyer “null” à partir de la fonction de rappel “save” définie sur le fichier JavaScript. Cela indique à l’éditeur de n’enregistrer que les attributs du bloc dans la base de données et d’ignorer le processus de validation du balisage du bloc, évitant ainsi les problèmes de balisage qui changent fréquemment.
Ces attributs sont ensuite transmis à la fonction de rendu côté serveur, que vous pouvez utiliser pour décider comment afficher le bloc sur le front-end de votre site. La fonction de rendu côté serveur se chargera alors d’afficher le bloc sur le front-end, en utilisant les attributs enregistrés pour afficher correctement le bloc.
Le bloc final ressemblera à ceci :
// file: hello-block.js
import { registerBlockType } from '@wordpress/blocks';
registerBlockType( 'wpvip-example/hello-block', {
title: 'Hello Block',
icon: 'shield',
category: 'common',
attributes: {
string: {
type: 'string',
},
},
edit: ( { className, setAttributes, attributes } ) => {
const { string } = attributes;
return (
<div className={ className }>
<p>Hello {string}</p>
<input
type="text"
value={string}
onChange={(event) => setAttributes({string: event.target.value})}
/>
</div>
);
},
save: ( { attributes } ) => null,
} );// file: hello-block.php
<?php
function wpvip_example_register_hello_block() {
// (...) enqueue the scripts and styles (...)
register_block_type(
'wpvip-example/hello-block',
(
'attributes' => (
'name' => (
'default' => 'default name',
'type' => 'string'
),
),
'render_callback' => 'wpvip_example_render_hello_block',
) );
}
add_action( 'init', 'wpvip_example_register_hello_block' );
function wpvip_example_render_hello_block( $attributes ) {
return '<p>Hello ' . esc_html( $attributes('name') ) . '</p>';
}Simplifiez la conversion avec un fichier block.json
Convertir un bloc côté client en bloc côté serveur peut sembler intimidant, mais l’utilisation du fichier block.json simplifie le processus. Cette méthode permet une distribution et une installation faciles des blocs, et enregistre également automatiquement les blocs côté serveur et côté client.
La méthode block.json permet également le partage de code entre JavaScript, PHP et d’autres langages lors du traitement des types de blocs stockés au format JSON. En utilisant block.json, vous pouvez tirer pleinement parti des puissantes capacités de l’éditeur de site et créer des blocs robustes, dynamiques et polyvalents pour votre site Web WordPress.
Cette flexibilité garantit que vos blocs ne sont pas limités dans leurs fonctionnalités et peuvent être utilisés dans n’importe quel contexte, à la fois à l’intérieur et à l’extérieur de l’environnement WordPress.
Encore besoin d’aide?