De nombreuses personnes se plaignent des obstacles à surmonter pour se lancer dans la construction de blocs et d’applications Gutenberg. La courbe d’apprentissage est raide, principalement en raison de la difficulté d’installer et de configurer l’environnement de développement. En outre, une solide connaissance de JavaScript, Node.js, React et Redux sont des ingrédients indispensables pour cette recette assez complexe.

Le manuel officiel de l’éditeur de blocs de WordPress fournit aux développeurs une quantité considérable d’informations, mais vous risquez de vous perdre dans cette mer de détails.

Et il convient de mentionner ce que Matías Ventura, architecte principal du projet Gutenberg, a rapporté dans son entretien avec WP Tavern :

Bien que certaines personnes puissent l’apprendre rapidement, c’est toujours un obstacle important pour les gens. Je pense qu’il y a plusieurs niveaux à cela ; la documentation pourrait être améliorée d’un ordre de grandeur à la fois dans l’organisation et la présentation. J’espère que nous pourrons faire beaucoup plus dans ce domaine.

Dans cette optique, nous avons décidé de fournir un tutoriel étape par étape visant à aider nos lecteurs à se lancer dans le développement de blocs Gutenberg.

Cela vous semble intéressant ? Plongeons-y !

Conditions préalables au développement de bloc Gutenberg

Pour ce tutoriel, les seules compétences requises sont une bonne connaissance du développement d’extensions WordPress et au moins une compréhension basique de HTML, CSS, JavaScript et React.

S’agira-t-il d’un projet ambitieux ? Bien sûr qu’il le sera !

Il n’a pas été facile de trouver le bon compromis entre exhaustivité et simplicité, ni de décider des sujets à inclure et de ceux à laisser de côté.

Espérons que les lecteurs intermédiaires et avancés nous pardonneront de ne pas approfondir certains concepts tels que React state, Redux store, les composants d’ordre élevé, etc. Ces sujets nécessitent un espace et une attention supplémentaires et sont probablement trop avancés pour le développement de blocs par des débutants (à moins que vous ne soyez un développeur React).

Pour la même raison, nous ne couvrirons pas certains des sujets les plus avancés liés au développement des blocs Gutenberg, tels que les blocs dynamiques et les boîtes méta.

Grâce aux connaissances que vous aurez acquises à la fin de cet article, vous pourrez commencer dès maintenant à vous amuser et à être productif.

Une fois que vous aurez commencé à construire des blocs, vous serez en mesure d’améliorer vos compétences et de construire vous-même des blocs Gutenberg encore plus avancés.

Qu’est-ce qu’un bloc Gutenberg ?

Depuis sa première sortie en décembre 2018, l’éditeur de blocs a été grandement amélioré sur tous les plans : des API plus puissantes, une interface utilisateur plus avancée, une utilisibalité améliorée, une tonne de nouveaux blocs, les premières implémentations de Full Site Editing, et bien plus encore.

En bref, même si Gutenberg est encore en plein développement, il a parcouru un long chemin – et aujourd’hui, l’éditeur de blocs est un candidat à part entière en tant que constructeur de pages et de sites fiable et fonctionnel.

Du point de vue du développeur, Gutenberg est une application mono-page (Single Page Application ou SPA) basée sur React qui permet aux utilisateurs de WordPress de créer, modifier et supprimer du contenu dans WordPress. Cependant, cela ne doit pas vous faire penser à une version améliorée de l’éditeur de contenu traditionnel.

Nous voulons que cela soit clair :

Dans Gutenberg, le contenu est divisé en blocs, qui sont des « briques » que les utilisateurs peuvent utiliser pour créer des articles et des pages ou leurs sites web.

Mais techniquement, qu’est-ce qu’un bloc ?

Nous aimons la définition de WordPress :

« Bloc » est le terme abstrait utilisé pour décrire les unités de balisage qui, composées ensemble, forment le contenu ou la mise en page d’une page web. L’idée combine les concepts de ce que nous réalisons aujourd’hui dans WordPress avec les codes courts, le HTML personnalisé et la découverte d’intégration dans une API et une expérience utilisateur uniques et cohérentes.

Les titres, paragraphes, colonnes, images, galeries et tous les éléments qui composent l’interface de l’éditeur, des panneaux de la colonne latérale aux commandes de la barre d’outils du bloc, sont des composants React.

Alors, que sont les composants React ? W3Schools fournit la définition suivante :

Les composants sont des morceaux de code indépendants et réutilisables. Ils servent le même objectif que les fonctions JavaScript, mais fonctionnent de manière isolée et renvoient du HTML via une fonction render() .

Travailler avec les blocs Gutenberg dans WordPress 5.8.
Travailler avec les blocs Gutenberg dans WordPress 5.8.

Alors que l’expérience d’édition délivrée par Gutenberg est nouvelle par rapport à l’éditeur classique de WordPress, la façon dont WordPress stocke vos morceaux de contenu dans la base de données ne change pas du tout. C’est parce que Gutenberg est une application qui fonctionne au sein de WordPress, mais qui ne change pas la façon dont le CMS fonctionne en son cœur.

Les publications (et cela inclut les articles, les pages et les types de publication personnalisés) créées avec Gutenberg sont toujours stockées dans la table wp_posts, exactement comme avec l’éditeur classique.

Mais dans un article créé avec Gutenberg, vous trouverez des informations supplémentaires dans le tableau qui représentent une différence fondamentale entre les publications créées via l’éditeur classique et Gutenberg.

Ces éléments d’information ressemblent à des commentaires HTML, et ils ont une fonction spécifique : délimiter des blocs :

Un article de blog vu dans l'éditeur de code.
Un article de blog vu dans l’éditeur de code.

Les délimiteurs de bloc indiquent à WordPress quel bloc doit être rendu à l’écran. Ils fournissent également des valeurs pour les propriétés du bloc dans un objet JSON. Ces propriétés déterminent la manière dont le bloc doit être rendu à l’écran :

Un article de blog stocké dans la table wp_posts.
Un article de blog stocké dans la table wp_posts.

Configuration de votre environnement de développement WordPress

La mise en place d’un environnement de développement JavaScript moderne nécessite une solide connaissance des technologies avancées telles que Webpack, React et JSX, Babel, ESLint, etc.

Intimidé ? Ne le soyez pas ! La communauté WordPress est déjà venue à la rescousse en fournissant des outils puissants qui vous permettent d’éviter un processus de configuration manuelle fastidieux.

Pour garder les choses simples, nous ne couvrirons pas la transpilation dans cet article (avec laquelle nous vous recommandons néanmoins de vous familiariser une fois que vous aurez appris les bases du développement par blocs). Au lieu de cela, nous allons présenter deux outils alternatifs que vous pouvez utiliser pour mettre en place rapidement et facilement un environnement de développement JavaScript moderne en quelques minutes. C’est à vous de choisir celui qui vous convient le mieux pour votre projet.

La mise en place d’un environnement de développement JavaScript pour construire des blocs Gutenberg est un processus en trois étapes :

  1. Installer Node.js et npm
  2. Configurer l’environnement de développement
  3. Configurer l’extension de bloc

Commençons.

1. Installer Node.js et npm

Avant d’installer votre environnement de développement et d’enregistrer votre premier bloc, vous devrez installer Node.js et le gestionnaire de paquets Node (npm).

Vous pouvez installer Node.js et npm de plusieurs façons différentes. Mais d’abord, vous pouvez vérifier si le logiciel est déjà installé sur votre machine.

Pour ce faire, lancez le terminal et exécutez la commande suivante :

node -v

Si le résultat est commande non trouvée, alors Node.js n’est pas installé sur votre ordinateur, et vous pouvez poursuivre l’installation.

Pour cet article, nous avons choisi l’option d’installation la plus simple, qui est le Node Installer. Tout ce que vous devez faire est de télécharger la version correspondant à votre système d’exploitation et de lancer l’assistant d’installation :

Page de téléchargement de Node.js.
Page de téléchargement de Node.js.

Une fois que vous avez installé Node.js, exécutez à nouveau la commande node -v dans votre terminal. Vous pouvez également exécuter la commande npm -v pour confirmer que vous avez le paquet npm disponible.

Vous êtes maintenant équipé des outils suivants :

  • Le gestionnaire de paquets node.js npx. Cela vous permet d’exécuter une commande npm sans l’installer au préalable.
  • Le gestionnaire de paquets npm Node.js (voir docs). Il est utilisé pour installer les dépendances et exécuter les scripts.

L’étape suivante consiste à installer l’environnement de développement.

2. Configurer votre environnement de développement

Une fois que vous aurez installé les dernières versions de Node.js et de npm sur votre machine locale, vous aurez besoin d’un environnement de développement pour WordPress.

Vous pouvez soit utiliser un environnement de développement local comme DevKinsta, soit utiliser l’outil officiel de WordPress. Jetons un coup d’œil aux deux options.

Option 1 : Environnement de développement local (DevKinsta)

En quelques clics, vous pouvez installer WordPress localement en utilisant DevKinsta, notre outil moderne de développement local de WordPress. Vous pouvez également opter pour un autre outil de développement local, tel que MAMP ou XAMPP :

Créer un nouveau site web WordPress dans DevKinsta.
Créer un nouveau site web WordPress dans DevKinsta.

Option 2 : wp-env

Vous pouvez également opter pour l’outil officielwp-env , qui fournit un environnement de développement WordPress local que vous pouvez lancer directement à partir de la ligne de commande. Noah Alen le définit comme suit :

Les environnements locaux de WordPress sont maintenant aussi simples que l’exécution d’une seule commande. wp-env est un outil sans configuration pour des environnements locaux de WordPress sans douleur. Il fournit des décisions sur les options afin que les utilisateurs puissent rapidement lancer WordPress sans perdre de temps. En effet, l’objectif est de rendre ces environnements facilement accessibles à tous – que vous soyez développeur, concepteur, gestionnaire ou autre.

Si vous décidez d’essayer, l’installation de wp-env ne demande qu’un effort minimal. Il suffit de suivre les étapes suivantes :

Étape 1 : Confirmer l’installation de Docker et Node.js

Pour répondre aux exigences techniques, vous devrez d’abord avoir installé Docker et Node.js sur votre ordinateur. En effet, wp-env crée une instance Docker qui exécute un site web WordPress. Toute modification apportée au code est immédiatement répercutée dans l’instance WordPress.

Étape 2 : Installer @wordpress/env à partir de la ligne de commande

Une fois que Docker et Node.js fonctionnent sur votre ordinateur, vous pouvez passer à l’installation de l’environnement de développement WordPress.

Vous pouvez installer wp-env de manière globale ou locale. Pour l’installer globalement, vous devez exécuter la commande suivante à partir du répertoire des extensions (plus d’informations à ce sujet dans l’encadré « Important » ci-dessous) :

npm install -g @wordpress/env

Décomposons ça :

Pour confirmer que wp-env a bien été installé, exécutez la commande suivante :

wp-env --version

Vous devriez voir la version actuelle de wp-env, ce qui signifie que vous pouvez maintenant lancer l’environnement en utilisant la commande suivante depuis le dossier de votre extension :

wp-env start

Vous pouvez accéder au tableau de bord de WordPress en utilisant l’adresse suivante :

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

Les informations d’identification par défaut sont les suivantes :

  • Identifiant : admin
  • Mot de passe : password

Configurez votre extension de bloc

Vous avez maintenant besoin d’une extension de bloc de démarrage sur laquelle vous appuyer. Mais au lieu de créer manuellement une extension de bloc de développement avec tous les fichiers et répertoires nécessaires, vous pouvez simplement exécuter un outil de développement fournissant tous les fichiers et configurations dont vous avez besoin pour commencer le développement de blocs.

Là encore, vous avez le choix entre plusieurs options. Examinons chacune d’elles.

Option 1 : Configurer une extension de bloc avec @wordpress/create-block

@wordpress/create-block est l’outil officiel sans configuration pour la création de blocs Gutenberg :

Create Block est un moyen officiellement supporté de créer des blocs pour enregistrer un bloc pour une extension WordPress. Il offre une configuration de construction moderne sans aucune configuration. Il génère du code PHP, JS, CSS, et tout ce dont vous avez besoin pour démarrer le projet.

Il est largement inspiré de create-react-app. Un grand bravo à @gaearon, à toute l’équipe de Facebook et à la communauté React.

Une fois que votre environnement local est opérationnel, vous pouvez configurer un bloc de démarrage en exécutant simplement la commande npx @wordpress/create-block, et il fournira tous les fichiers et répertoires dont vous avez besoin pour créer l’échafaudage de l’extension et enregistrer un nouveau bloc.

Faisons un test pour voir comment cela fonctionne.

À partir de votre outil de ligne de commande, accédez au répertoire /wp-content/plugins/ et exécutez la commande suivante :

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

Lorsqu’on vous demande de confirmer, saisissez y pour continuer :

Création d'un bloc avec @wordpress/create-block.
Création d’un bloc avec @wordpress/create-block.

Le processus prend quelques instants. Une fois qu’il est terminé, vous devriez obtenir la réponse suivante :

L'extension de bloc a été créée.
L’extension de bloc a été créée.

Et c’est tout !

Lancez maintenant votre environnement de développement WordPress et allez à l’écran des Extensions dans le tableau de bord de WordPress. Une nouvelle extension nommé « My First Block » devrait avoir été ajoutée à votre liste d’extensions :

L'extension de bloc a bien été installée.
L’extension de bloc a bien été installée.

Activez l’extension si nécessaire, créez un nouvel article de blog, faites défiler l’outil dinsertion de blocs jusqu’à la section Widgets, et sélectionnez votre nouveau bloc :

Un exemple de bloc créé avec @wordpress/create-block.
Un exemple de bloc créé avec @wordpress/create-block.

Maintenant, retournez au terminal et changez le répertoire courant en my-first-block :

cd my-first-block

Ensuite, exécutez la commande suivante :

npm start

Cela vous permet d’exécuter l’extension en mode développement. Pour créer le code de production, vous devez utiliser la commande suivante :

npm run build

Option 2 : Configuration d’une extension de bloc avec create-guten-block

create-guten-block est un outil de développement tiers pour la construction de blocs Gutenberg :

create-guten-block est un dev-toolkit sans configuration (#0CJS) pour développer des blocs WordPress Gutenberg en quelques minutes sans configurer React, webpack, ES6/7/8/Next, ESLint, Babel, etc.

Tout comme l’outil officiel create-block, create-guten-block est basé sur create-react-app et peut vous aider à générer votre première extension de bloc sans problème.

La boîte à outils fournit tout ce dont vous avez besoin pour créer une extension WordPress moderne, notamment les éléments suivants :

  • Prise en charge des syntaxes React, JSX et ES6.
  • Processus de construction de webpack pour le développement et la production en arrière-plan.
  • Les extras du langage au-delà de l’ES6, comme l’opérateur d’étalement d’objet.
  • CSS auto-préfixé, de sorte que vous n’avez pas besoin de -webkit ou d’autres préfixes.
  • Un script de construction pour regrouper JS, CSS et images pour la production avec des cartes de source.
  • Mises à jour sans problème pour les outils ci-dessus avec une seule dépendance cgb-scripts.

Il convient de noter l’avertissement suivant :

La contrepartie est que ces outils sont préconfigurés pour fonctionner d’une manière spécifique. Si votre projet nécessite davantage de personnalisation, vous pouvez « l’éjecter » et le personnaliser, mais vous devrez alors maintenir cette configuration.

Une fois que vous avez un site WordPress local en main, lancez votre outil de ligne de commande, allez dans le répertoire /wp-content/plugins de votre installation, et exécutez la commande suivante :

npx create-guten-block my-first-block

Vous devrez attendre une minute ou deux pendant que la structure du projet est créée et que les dépendances sont téléchargées :

Créer un bloc Gutenberg avec create-guten-block.
Créer un bloc Gutenberg avec create-guten-block.

Lorsque le processus est terminé, vous devriez voir l’écran suivant :

Le bloc Gutenberg a bien été créé avec create-guten-block.
Le bloc Gutenberg a bien été créé avec create-guten-block.

L’image suivante montre la structure du projet avec le terminal exécuté dans Visual Studio Code :

L'extension de bloc dans Visual Studio Code.
L’extension de bloc dans Visual Studio Code.

Retournez maintenant à votre tableau de bord WordPress. Un nouvel élément devrait être listé dans l’écran des extensions – il s’agit de l’extension my-first-block :

L'écran des extensions avec une nouvelle extension créée avec create-guten-block.
L’écran des extensions avec une nouvelle extension créée avec create-guten-block.

Activez l’extension et retournez dans le terminal. Changez le répertoire courant en my-first-block, puis lancez npm start :

cd my-first-block
npm start

Vous devriez obtenir la réponse suivante :

npm a démarré.
npm a démarré.

Encore une fois, cela vous permet d’exécuter l’extension en mode développement. Pour créer le code de production, vous devez utiliser :

npm run build

Activez l’extension et créez un nouvel article ou une nouvelle page, puis parcourez vos blocs et sélectionnez votre tout nouveau bloc Gutenberg :

Un nouveau bloc créé avec create-guten-block.
Un nouveau bloc créé avec create-guten-block.

Pour un aperçu plus approfondi ou en cas d’erreur, consultez la documentation fournie par Ahmad Awais.

Une visite guidée de l’échafaudage du Starter Block

Quel que soit l’outil de développement choisi (create-block ou create-guten-block), vous disposez maintenant d’un échafaudage de blocs que vous pouvez utiliser comme point de départ pour créer une extension de bloc.

Mais qu’est-ce qu’un échafaudage de bloc ?

L’échafaudage (scaffolding) de bloc est un terme abrégé qui décrit la structure de répertoire de soutien dont vous avez besoin pour que WordPress reconnaisse un bloc. En général, ce répertoire comprend des fichiers tels que index.php, index.js, style.css, et d’autres – qui contiennent à leur tour des appels comme register_block_type.

Nous avons opté pour l’outil officiel Create Block, car il est utilisé dans le manuel de l’éditeur de blocs. Mais même si vous décidez d’utiliser un outil tiers comme create-guten-block, votre expérience ne sera pas trop différente.

Ceci étant dit, plongeons plus profondément dans l’outil create-block.

Un regard plus approfondi sur l’outil de développement Create Block

Comme nous l’avons mentionné plus haut, Create Block est l’outil officiel en ligne de commande pour créer des blocs Gutenberg. L’exécution de @wordpress/create-block dans votre terminal génère les fichiers PHP, JS, et SCSS et le code nécessaire pour enregistrer un nouveau type de bloc :

npx @wordpress/create-block [options] [slug]
  • [slug] (facultatif) – permet d’attribuer le slug du bloc et d’installer l’extension.
  • [options] (facultatif) – options disponibles

Par défaut, un modèle ESNext est attribué. Cela signifie que vous obtiendrez la prochaine version de JavaScript, avec l’ajout de la syntaxe JSX.

Si vous omettez le nom du bloc, la commande s’exécute en mode interactif, ce qui vous permet de personnaliser plusieurs options avant de générer les fichiers :

npx @wordpress/create-block
Exécution de create-block en mode interactif.
Exécution de create-block en mode interactif.

L’image ci-dessous montre la structure de fichier d’une extension de bloc créée avec l’outil officiel Create Block :

Fichiers et répertoires d'une extension de bloc créé avec @wordpress/create-block.
Fichiers et répertoires d’une extension de bloc créé avec @wordpress/create-block.

Ceci étant dit, passons en revue les principaux fichiers et répertoire de notre nouvelle extension de bloc.

Le fichier de l’extension

Avec le fichier principal de l’extension, vous enregistrez le bloc sur le serveur :

<?php
/**
 * Plugin Name:       Kinsta Academy Block
 * Plugin URI:        https://kinsta.com/
 * Description:       An example block for Kinsta Academy students
 * Requires at least: 5.9
 * Requires PHP:      7.0
 * Version:           0.1.0
 * Author:            Kinsta Students
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       ka-example-block
 *
 * @package           ka-example-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/reference/functions/register_block_type/
 */
function ka_example_block_ka_example_block_block_init() {
	register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'ka_example_block_ka_example_block_block_init' );

La fonction register_block_type enregistre un type de bloc sur le serveur en utilisant les métadonnées stockées dans le fichier block.json.

  • Le nom du type de bloc, y compris l’espace de noms, ou un chemin d’accès au répertoire où se trouve le fichier block.json, ou un objet WP_Block_Type complet.
  • Un tableau d’arguments de type de bloc

Dans le code ci-dessus, la constante magique __DIR__ renvoie le répertoire actuel. Cela signifie que le fichier block.json réside dans le sous-dossier /build.

Le fichier package.json

Le fichier package.json définit les propriétés et les scripts JavaScript de votre projet. C’est ici que vous pouvez installer les dépendances de votre projet.

Pour mieux comprendre à quoi sert ce fichier, ouvrez-le avec votre éditeur de code préféré :

{
	"name": "ka-example-block",
	"version": "0.1.0",
	"description": "An example block for Kinsta Academy students",
	"author": "Kinsta Students",
	"license": "GPL-2.0-or-later",
	"homepage": "https://kinsta.com/",
	"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",
		"packages-update": "wp-scripts packages-update",
		"plugin-zip": "wp-scripts plugin-zip",
		"start": "wp-scripts start"
	},
	"devDependencies": {
		"@wordpress/scripts": "^24.1.0"
	},
	"dependencies": {
		"classnames": "^2.3.2"
	}
}

La propriété scripts est un dictionnaire contenant des commandes qui sont exécutées à différents moments du cycle de vie d’un paquet en utilisant npm run [cmd].

Dans cet article, nous utiliserons les commandes suivantes :

  • npm run build – crée un build de production (compressé)
  • npm run start ou npm start – crée un build de développement (non compressé)

dependencies et devDependencies sont deux objets faisant correspondre un nom de paquet à une version. dependencies est nécessaire en production, tandis que devDependences est uniquement nécessaire pour le développement local (en savoir plus).

La seule dépendance de développement par défaut est le paquet @wordpress/scripts, qui est défini comme « une collection de scripts réutilisables adaptés au développement de WordPress ».

Le fichier block.json

À partir de WordPress 5.8, le fichier de métadonnées block.json est la façon canonique d’enregistrer les types de blocs.

Le fait de disposer d’un fichier block.json présente plusieurs avantages, notamment une amélioration des performances et une meilleure visibilité dans le répertoire des extensions de WordPress :

Du point de vue des performances, lorsque les thèmes prennent en charge le chargement différé des ressources, la mise en file d’attente des ressources des blocs enregistrés avec block.json est optimisée dès le départ. Les ressources CSS et JavaScript frontend énumérées dans les propriétés de style ou de script ne seront mises en file d’attente que lorsque le bloc sera présent sur la page, ce qui permettra de réduire la taille des pages.

L’exécution de la commande @wordpress/create-block génère le fichier block.json suivant :

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 2,
	"name": "ka-example-block/ka-example-block",
	"version": "0.1.0",
	"title": "Kinsta Academy Block",
	"category": "widgets",
	"icon": "superhero-alt",
	"description": "An example block for Kinsta Academy students",
	"supports": {
		"html": false
	},
	"textdomain": "ka-example-block",
	"editorScript": "file:./index.js",
	"editorStyle": "file:./index.css",
	"style": "file:./style-index.css"
}

Voici la liste complète des propriétés par défaut :

  • apiVersion — la version de l’API utilisée par le bloc (la version actuelle est 2)
  • name — un identifiant unique pour un bloc, y compris un espace de noms.
  • version — la version actuelle d’un bloc
  • title — un titre d’affichage pour un bloc
  • category — une catégorie de bloc
  • icon — un slug Dashicon ou une icône SVG personnaliséen
  • description — une brève description visible dans l’inspecteur de bloc
  • supports — un ensemble d’options pour contrôler les fonctionnalités utilisées dans l’éditeur
  • textdomain — le text-domain de l’extension
  • editorScript — définition du script de l’éditeur
  • editorStyle — définition du style de l’éditeur
  • style — fournit des styles alternatifs pour un bloc

Outre les propriétés répertoriées ci-dessus, vous pouvez (et allez probablement) définir un objet attributes fournissant des informations sur les données stockées par votre bloc. Dans votre block.json, vous pouvez définir un nombre quelconque d’attributs dans des paires clé/valeur, où la clé est le nom de l’attribut et la valeur est la définition de l’attribut.

Regardez l’exemple suivant de définitions d’attributs :

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

Nous nous pencherons plus en détail sur le fichier block.json plus loin dans l’article, mais vous pouvez également consulter le manuel de l’éditeur de blocs pour obtenir des informations plus détaillées sur les métadonnées et les attributs block.json.

Le répertoire src

Le répertoire src est l’endroit où le développement se fait. Dans ce répertoire, vous trouverez les fichiers suivants :

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

index.js

Le fichier index.js est votre point de départ. C’est ici que vous allez importer les dépendances et enregistrer le type de bloc sur le client :

import { registerBlockType } from '@wordpress/blocks';

import './style.scss';

import Edit from './edit';
import save from './save';
import metadata from './block.json';

registerBlockType( metadata.name, {
	/**
	 * @see ./edit.js
	 */
	edit: Edit,

	/**
	 * @see ./save.js
	 */
	save,
} );

La première déclaration importe la fonction registerBlockType depuis le paquetage @wordpress/blocks. Les instructions d’importation suivantes importent la feuille de style ainsi que les fonctions Edit et save, et un objet de métadonnées depuis le fichier block.json.

La fonction registerBlockType enregistre le composant sur le client. La fonction prend deux paramètres : un nom de bloc et un objet de configuration de bloc.

La fonction Edit fournit l’interface du bloc telle qu’elle est rendue dans l’éditeur de blocs, tandis que la fonction save fournit la structure qui sera sérialisée et enregistrée dans la base de données (en savoir plus).

edit.js

edit.js est l’endroit où vous allez construire l’interface d’administration du bloc :

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>
	);
}

Tout d’abord, il importe la fonction __ du paquet @wordpress/i18n (ce paquet contient une version JavaScript des fonctions de traduction), le crochet React useBlockProps et le fichier editor.scss.

Ensuite, il exporte le composant React (pour en savoir plus sur les déclarations d’importation et d’exportation).

save.js

Le fichier save.js est l’endroit où nous construisons la structure du bloc à sauvegarder dans la base de données :

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 et style.scss

Outre les scripts, deux fichiers SASS résident dans les répertoires src. Le fichier editor.scss contient les styles appliqués au bloc dans le contexte de l’éditeur, tandis que le fichier style.scss contient les styles du bloc pour l’affichage dans l’interface publique ainsi que dans l’éditeur. Nous nous pencherons plus en détail sur ces fichiers dans la deuxième partie de ce guide.

Les répertoires node_modules et build

Le répertoire node_modules contient les modules node et leurs dépendances. Nous n’allons pas nous plonger plus profondément dans les paquets node car cela dépasse le cadre de cet article, mais vous pouvez en lire plus dans cet article sur l’endroit où npm installe les paquets.

Le répertoire build contient les fichiers JS et CSS résultant du processus de construction. Vous pouvez approfondir le processus de construction dans les guides de syntaxe ESNext et de configuration de la construction JavaScript.

Le projet : Construire votre premier bloc Gutenberg

Il est temps de se salir les mains. Cette section vous apprendra à créer une extension fournissant un bloc d’appel à action (CTA) nommé Kinsta Academy.

Le bloc sera composé de deux colonnes, avec une image à gauche et un paragraphe de texte à droite. Un bouton avec un lien personnalisable sera placé sous le texte :

Le type de bloc que vous allez apprendre à construire dans ce guide
Le type de bloc que vous allez apprendre à construire dans ce guide.

Ce n’est qu’un exemple simple, mais il nous permet de couvrir les bases du développement des blocs Gutenberg. Une fois que vous aurez bien compris les bases, vous pourrez vous lancer dans la création de blocs Gutenberg de plus en plus complexes avec l’aide du Block Editor Handbook et de toutes les autres ressources disponibles.

En supposant que vous avez la dernière version de WordPress sur votre environnement de développement local, voici ce que vous allez apprendre à partir de maintenant :

À vos marques…prêts… partez !

Comment configurer l’extension Starter Block ?

Lancez votre outil de ligne de commande et accédez au répertoire /wp-content/plugins :

Nouveau terminal dans le répertoire dans Mac OS.
Nouveau terminal dans le répertoire dans Mac OS.

Maintenant, exécutez la commande suivante :

npx @wordpress/create-block

Cette commande génère les fichiers PHP, SCSS et JS pour l’enregistrement d’un bloc en mode interactif, ce qui vous permet d’ajouter facilement les données nécessaires à votre bloc. Pour notre exemple, nous utiliserons les données suivantes :

  • Variante du modèle : statique
  • Nom du bloc : ka-example-block
  • Espace de noms interne : ka-example-block
  • Titre d’affichage du bloc : Bloc Kinsta Academy
  • Description courte du bloc : Un bloc d’exemple pour les étudiants de la Kinsta Academy
  • Dashicon : superhero-altsuperhero-alt
  • Nom de la catégorie : widgets
  • Voulez-vous personnaliser l’extension WordPress? : oui
  • La page d’accueil de l’extension : https://kinsta.com/
  • Version actuelle de l’extension : 0.1.0
  • Auteur de l’extension : votre nom
  • Licence : –
  • Lien vers le texte de la licence : –
  • Chemin du domaine personnalisé pour les traductions : –

L’installation de l’extension et de toutes les dépendances prend quelques minutes. Lorsque le processus est terminé, vous verrez la réponse suivante :

Le bloc d'exemple a été installé et enregistré pour le développeur.
Le bloc d’exemple a été installé et enregistré pour le développeur.

Maintenant, exécutez la commande suivante depuis le répertoire /wp-content/plugins :

cd ka-example-block

Exécution de commandes à partir du terminal de Visual Studio Code.
Exécution de commandes à partir du terminal de Visual Studio Code.

Enfin, à partir du répertoire de votre extension (ka-example-block dans notre exemple), vous pouvez commencer à développer avec :

npm start

Ouvrez maintenant l’écran Extensions pour trouver et activer l’extension Kinsta Academy Block :

Activez le bloc d'exemple
Activez le bloc d’exemple

Créez un nouvel article, ouvrez le module d’insertion de blocs et faites défiler la liste jusqu’à la catégorie Design. Cliquez pour ajouter le bloc Kinsta Academy :

Un bloc de démarrage construit avec @wordpress/create-block.
Un bloc de démarrage construit avec @wordpress/create-block.

block.json au travail

Comme nous l’avons mentionné précédemment, l’enregistrement du bloc côté serveur a lieu dans le fichier .php principal. Cependant, nous ne définirons pas les réglages dans le fichier .php. Nous utiliserons plutôt le fichier block.json.

Ouvrez à nouveau le fichier block.json et examinez de plus près les réglages par défaut :

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 2,
	"name": "ka-example-block/ka-example-block",
	"version": "0.1.0",
	"title": "Kinsta Academy Block",
	"category": "widgets",
	"icon": "superhero-alt",
	"description": "An example block for Kinsta Academy students",
	"supports": {
		"html": false
	},
	"textdomain": "ka-example-block",
	"editorScript": "file:./index.js",
	"editorStyle": "file:./index.css",
	"style": "file:./style-index.css"
}

Scripts et styles

Les propriétés editorScript, editorStyle et style fournissent les chemins relatifs vers les scripts et les styles de l’interface publique et de l’administration.

Vous n’avez pas à enregistrer manuellement les scripts et les styles définis ici car ils sont automatiquement enregistrés et mis en file d’attente par WordPress. Pour le prouver, lancez l’inspecteur du navigateur et ouvrez l’onglet Réseau :

Inspection des ressources dans Chrome DevTools.
Inspecting resources in Chrome DevTools.

Comme vous pouvez le voir dans l’image ci-dessus, notre script index.js résidant dans le répertoire build a été régulièrement mis en file d’attente sans avoir à ajouter de code PHP.

Libellés de l’UI

Les propriétés title et description fournissent les libellés nécessaires pour identifier le bloc dans l’éditeur :

Nom et description du bloc dans la colonne latérale du bloc.
Nom et description du bloc dans la colonne latérale du bloc.

Mots clés

Comme nous l’avons mentionné précédemment, vous pouvez configurer avec précision les réglages de vos blocs à l’aide de propriétés et d’attributs. Par exemple, vous pouvez ajouter un ou plusieurs keywords pour aider les utilisateurs à rechercher des blocs :

"keywords": [ 
		"kinsta", 
		"academy", 
		"superhero" 
	],

Si vous saisissez maintenant « kinsta », « academy » ou « superhero » dans l’insertion rapide, l’éditeur vous proposera le bloc Kinsta Academy :

Recherche d'un bloc à l'aide d'un mot clé dans l'insertion rapide.
Recherche d’un bloc à l’aide d’un mot clé dans l’insertion rapide.

Localisation

Si vous vous demandez comment se fait la localisation des chaînes de caractères dans le fichier JSON, voici la réponse :

En JavaScript, vous pouvez utiliser la méthode registerBlockTypeFromMetadata du package @wordpress/blocks pour enregistrer un type de bloc à l’aide des métadonnées chargées dans le fichier block.json. Toutes les propriétés localisées sont automatiquement enveloppées dans des appels de fonction  _x (du paquet @wordpress/i18n ) de la même manière que cela fonctionne en PHP avec register_block_type_from_metadata.  La seule exigence est de définir la propriété textdomain dans le fichier block.json.

Nous utilisons ici la fonction registerBlockType au lieu de registerBlockTypeFromMetadata, car cette dernière est obsolète depuis Gutenberg 10.7, mais le mécanisme est le même.

Utilisation des composants intégrés : Le composant RichText

Les éléments qui composent un bloc Gutenberg sont des composants React, et vous pouvez accéder à ces composants via la variable globale wp. Par exemple, essayez de saisir wp.editor dans la console de votre navigateur. Vous obtiendrez ainsi la liste complète des composants inclus dans le module wp.editor.

Faites défiler la liste et devinez à quoi servent les composants d’après leur nom.

De même, vous pouvez vérifier la liste des composants inclus dans le module wp.components :

Composants WP
Composants WP

Retournez maintenant au fichier edit.js et regardez de plus près le script :

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __(
				'Kinsta Academy Block – hello from the editor!',
				'ka-example-block'
			) }
		</p>
	);
}

Ce code génère un bloc statique avec un texte simple et non modifiable. Mais nous pouvons facilement changer les choses :

Le bloc de démarrage dans l'éditeur de code.
Le bloc de démarrage dans l’éditeur de code.

Pour rendre le texte modifiable, il faudra remplacer la balise <p> actuelle par un composant qui rend le contenu de la saisie modifiable. Pour cela, Gutenberg fournit le composant RichText intégré.

L’ajout d’un composant intégré à votre bloc est un processus en 5 étapes :

  1. Importer les composants nécessaire à partir d’un paquet WordPress
  2. Inclure les éléments correspondants dans votre code JSX
  3. Définir les attributs nécessaires dans le fichier block.json
  4. Définir les gestionnaires d’événements
  5. Enregistrer les données

Étape 1 : Importer les composants nécessaires à partir d’un paquet WordPress

Ouvrez maintenant le fichier edit.js et modifiez l’instruction import suivante :

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

…en :

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

De cette façon, vous importez la fonction useBlockProps et le composant RichText du paquet @wordpress/block-editor.

useBlockProps

Le crochet React useBlockProps marque l’élément d’habillage du bloc :

Lorsque vous utilisez la version 2 de l’API, vous devez utiliser le nouveau crochet useBlockProps dans la fonction edit du bloc pour marquer l’élément d’habillage du bloc. Le crochet insérera les attributs et les gestionnaires d’événements nécessaires pour activer le comportement du bloc. Tous les attributs que vous souhaitez transmettre à l’élément du bloc doivent passer par useBlockProps et la valeur renvoyée doit être répartie sur l’élément.

Pour faire simple, les useBlockProps attribuent automatiquement des attributs et des classes à l’élément d’habillage (l’élément p dans notre exemple) :

Éléments et classes générés par useBlockProps.
Éléments et classes générés par useBlockProps.

Si vous supprimez useBlockProps de l’élément wrapper, vous aurez une simple chaîne de texte sans accès aux fonctionnalités et au style des blocs :

Le même bloc sans useBlockProps.
Le même bloc sans useBlockProps.

Comme nous l’expliquerons plus tard, vous pouvez également passer à useBlockProps un objet de propriétés pour personnaliser la sortie.

RichText

Le composant RichText fournit une entrée dont le contenu est modifiable, ce qui permet aux utilisateurs de modifier et de formater le contenu.

Vous trouverez le composant documenté sur GitHub à gutenberg/packages/block-editor/src/components/rich-text/README.md.

Étape 2 : Inclure les éléments correspondants dans votre code JSX

...

const blockProps = useBlockProps();

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

Commentons le code ligne par ligne :

  • tagName — nom de la balise de l’élément HTML modifiable
  • onChange — fonction appelée lorsque le contenu de l’élément change
  • allowedFormats — tableau des formats autorisés. Par défaut, tous les formats sont autorisés
  • value — chaîne HTML à rendre modifiable
  • placeholder — texte de remplacement à afficher lorsque l’élément est vide.

Étape 3 : Définir les attributs nécessaires dans le fichier block.json

Les attributs fournissent des informations sur les données stockées par un bloc, comme le contenu riche, la couleur d’arrière-plan, les URL, etc.

Vous pouvez définir un nombre arbitraire attributes dans un objet attributs sous forme de paires clé/valeur, où la clé est le nom de l’attribut et la valeur est la définition de l’attribut.

Ouvrez maintenant le fichier block.json et ajoutez les attributes prop suivants :

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

L’attribut de content permet de stocker le texte saisi par l’utilisateur dans le champ modifiable :

  • type indique le type de données stockées par l’attribut. Le type est obligatoire, sauf si vous définissez une propriété de type enum.
  • source définit comment la valeur de l’attribut est extraite du contenu de l’article. Dans notre exemple, il s’agit du contenu HTML. Notez que si vous ne fournissez pas de propriété source, les données sont stockées dans le délimiteur de bloc (en savoir plus).
  • selector est une balise HTML ou tout autre sélecteur, tel qu’un nom de classe ou un attribut id.

Nous allons passer à la fonction Edit un objet de propriétés. Donc, retournez au fichier edit.js et faites la modification suivante :

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

Étape 4 : Définir les gestionnaires d’événements

L’élément RichText possède un attribut onChange, qui fournit une fonction à appeler lorsque le contenu de l’élément change.

Définissons cette fonction et voyons l’ensemble du script edit.js :

import { __ } from '@wordpress/i18n';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();

	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } )
	}

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

Enregistrez maintenant le fichier et retournez à votre tableau de bord WordPress, créez un nouvel article ou une nouvelle page et ajoutez votre bloc personnalisé :

La sortie du composant RichText dans l'éditeur de blocs.
La sortie du composant RichText dans l’éditeur de blocs.

Ajoutez du texte et passez à la vue Code. Voici à quoi devrait ressembler votre code :

<!-- wp:ka-example-block/ka-example-block -->
<p class="wp-block-ka-example-block-ka-example-block">Kinsta Academy Block – hello from the saved content!</p>
<!-- /wp:ka-example-block/ka-example-block -->

Comme vous pouvez le voir, si vous passez à l’éditeur de code, le contenu de votre bloc a changé. C’est parce que vous devez modifier le fichier save.js pour stocker les entrées de l’utilisateur dans la base de données lorsque l’article est enregistré.

Étape 5 : Enregistrer les données

Ouvrez maintenant le fichier save.js et modifiez le script comme suit :

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 } 
		/>
	);
}

C’est ce que nous faisons ici :

  • Importez le composant RichText du paquetage block-editor.
  • Passez plusieurs propriétés à la fonction de save via un argument objet (dans cet exemple, nous ne passons que les attributsproperty).
  • Renvoie le contenu du composant RichText
Le contenu du bloc a été enregistré dans la base de données.
Le contenu du bloc a été enregistré dans la base de données.

Vous pouvez en savoir plus sur le composant RichText dans le manuel de l’éditeur de blocs et trouver la liste complète des props sur Github.

Allons maintenant un peu plus loin. Dans la section suivante, vous apprendrez à ajouter des contrôles à la barre d’outils du bloc.

Ajout de contrôles à la barre d’outils du bloc

La barre d’outils du bloc contient un ensemble de contrôles permettant aux utilisateurs de manipuler des parties du contenu du bloc. Pour chaque contrôle de la barre d’outils, vous trouverez un composan :

La barre d'outils du bloc de paragraphe principal.
La barre d’outils du bloc de paragraphe principal.

Par exemple, vous pouvez ajouter un contrôle d’alignement du texte pour votre bloc. Il vous suffit d’importer deux composants du paquetage @wordpress/block-editor.

Nous allons suivre les mêmes étapes que dans l’exemple précédent :

  1. Importer les composants nécessaires à partir des paquets WordPress
  2. Inclure les éléments correspondants dans votre code JSX
  3. Définir les attributs nécessaires dans le fichier block.json
  4. Définir les gestionnaires d’événements
  5. Enregistrer les données

Étape 1 : Importer les composants BlockControls et AlignmentControl de @wordpress/block-editor

Pour ajouter un contrôle d’alignement à la barre d’outils du bloc, vous avez besoin de deux composants :

  • BlockControls rend une barre d’outils dynamique de contrôles (non documenté).
  • AlignmentControl rend un menu déroulant qui affiche les options d’alignement pour le bloc sélectionné (en savoir plus).

Ouvrez le fichier edit.js et modifiez l’instruction import comme indiqué ci-dessous :

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

Étape 2 : Ajouter les éléments BlockControls et AlignmentControl

Allez dans la fonction Edit et insérez l’élément <BlockControls /> au même niveau que <RichText />. Ajoutez ensuite un <AlignmentControl /> à l’intérieur 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 } }
			/>
		</>
	);
}

Dans le code ci-dessus, <> et </> sont la syntaxe courte pour déclarer les fragments React, qui sont la façon dont nous retournons plusieurs éléments dans React.

Dans cet exemple, AlignmentControl possède deux attributs :

Nous avons également défini des attributs supplémentaires pour l’élément RichText (consultez la liste complète des attributs avec des exemples)

Étape 3 : Définir l’attribut align dans block.json

Maintenant, allez dans le fichier block.json et ajoutez l’attribut align :

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

Quand vous avez terminé, retournez à l’éditeur de bloc, actualisez la page et sélectionnez le bloc. Vous devriez voir un message d’erreur dans votre bloc.

Le bloc affiche un message d'erreur
Le bloc affiche un message d’erreur

La raison en est que nous n’avons pas encore défini notre gestionnaire d’événements.

Étape 4 : Définir les gestionnaires d’événements

Définissez maintenant onChangeAlign:

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

Si newAlign est undefined, alors nous mettons newAlign à none. Sinon, nous utilisons newAlign.

Notre script edit.js devrait être complet (pour l’instant) :

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 } }
			/>
		</>
	);
}

Vous pouvez maintenant retourner dans l’éditeur et aligner le contenu du bloc. Votre bloc devrait maintenant afficher fièrement une barre d’outils d’alignement.

Notre bloc possède maintenant une barre d'outils d'alignement
Notre bloc possède maintenant une barre d’outils d’alignement

Mais si vous enregistrez l’article, vous verrez que le contenu de votre bloc n’est pas aligné sur l’interface publique comme il l’est dans l’éditeur de bloc. C’est parce que nous devons modifier la fonction save afin de boutique le contenu et les attributs du bloc dans la base de données.

Étape 5 : Sauvegarder les données

Ouvrez save.js et modifiez la fonction save comme suit :

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

Enfin, pour rendre le code plus lisible, vous pouvez extraire les propriétés individuelles de l’objet attribute en utilisant la syntaxe d’affectation de la déstructuration :

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

Vous pouvez faire de même dans le fichier edit.js.

Enregistrez maintenant le fichier et passez à l’éditeur de code. Le code du bloc devrait ressembler à quelque chose comme ceci :

<!-- wp:ka-example-block/ka-example-block {"align":"right"} -->
<p class="wp-block-ka-example-block-ka-example-block" style="text-align:right">This is my first editable <strong>Gutenberg</strong> <em>block</em> 😎</p>
<!-- /wp:ka-example-block/ka-example-block -->
Vérification des contrôles de la barre d'outils du bloc
Vérification des contrôles de la barre d’outils du bloc

Voilà, c’est fait ! Vous venez d’ajouter un contrôle d’alignement à la barre d’outils du bloc 🤓.

Vous pouvez en savoir plus sur les commandes de la barre d’outils du bloc dans le manuel de l’éditeur de bloc.

Personnalisation de la colonne latérale des réglages du bloc

Vous pouvez également ajouter des contrôles à la colonne latérale des réglages du bloc (ou même créer une nouvelle colonne latérale pour votre application).

L’API fournit un composant InspectorControls pour cela.

Le manuel de l’éditeur de blocs explique comment utiliser la colonne latérale des réglages :

La colonne latérale des réglages est utilisée pour afficher les réglages moins souvent utilisés ou ceux qui nécessitent plus d’espace à l’écran. La colonne latérale des réglages ne doit être utilisée que pour les réglages au niveau du bloc.

Si vous disposez de réglages qui n’affectent que le contenu sélectionné à l’intérieur d’un bloc (par exemple, le réglage « gras » pour le texte sélectionné dans un paragraphe), ne les placez pas dans la colonne latérale des réglages. La colonne latérale des réglages s’affiche même lors de l’édition d’un bloc en mode HTML. Elle ne doit donc contenir que les réglages relatifs aux blocs.

Encore une fois :

  1. Importer les composants nécessaires à partir des paquets WordPress
  2. Inclure les éléments correspondants dans votre code JSX
  3. Définir les attributs nécessaires dans le fichier block.json
  4. Définir les gestionnaires d’événements
  5. Enregistrer les données

Étape 1. Importation des composants InspectorControls et PanelColorSettings depuis @wordpress/block-editor

Vous pouvez ajouter plusieurs contrôles pour permettre aux utilisateurs de personnaliser des aspects spécifiques du bloc. Par exemple, vous pouvez fournir un panneau de contrôle des couleurs. Pour ce faire, vous devez importer les composants InspectorControls et PanelColorSettings du module block-editor :

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

Étape 2 : Inclure les éléments correspondants dans votre code JSX

Vous pouvez maintenant ajouter les éléments correspondants au JSX renvoyé par la fonction Edit :

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();

	const { content, align, backgroundColor, textColor } = attributes;

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

Notez que nous avons également mis à jour l’attribut style de l’élément RichText :

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

Étape 3 : Définir les attributs nécessaires dans block.json

Définissez maintenant les attributs backgroundColor et textColor dans le fichier block.json :

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

Étape 4 : Définir les gestionnaires d’événements

Vous devez maintenant définir deux fonctions pour mettre à jour backgroundColor et textColor en fonction des entrées de l’utilisateur :

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

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

Étape 5 : Enregistrer les données

Une dernière étape : Ouvrez le fichier save.js et modifiez le script comme suit :

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 } }
		/>
	);
}

Enregistrez le fichier et vérifiez le bloc dans l’éditeur. Vous trouverez peut-être une mauvaise surprise : un message d’erreur vous informant que le bloc contient un contenu inattendu ou non valide.

Message d'erreur sur le contenu inattendu ou non valide
Message d’erreur sur le contenu inattendu ou non valide

Cela se produit parce que le fichier save.js est modifié et que le code enregistré dans la base de données ne correspond pas au code utilisé dans l’éditeur.

Pour résoudre ce problème, actualisez la page, supprimez toute instance de votre bloc et ajoutez-le à nouveau à votre publication :

Le panneau des réglages de couleur dans la colonne latérale du bloc Réglage des couleurs
Le panneau des réglages de couleur dans la colonne latérale du bloc Réglage des couleurs

Apportez vos modifications, enregistrez l’article et affichez-le dans le site principal. Les modifications que vous avez apportées dans l’éditeur de blocs doivent être reflétées sur le site principal.

Le bloc personnalisé fonctionne désormais correctement sur l'interface publique
Le bloc personnalisé fonctionne désormais correctement sur l’interface publique

Dans cette section, vous allez ajouter de nouveaux composants à votre type de bloc :

  • Un composant ExternalLink permettant aux utilisateurs d’ajouter un lien personnalisable à votre bloc personnalisé
  • Plusieurs contrôles de la colonne latérale permettant aux utilisateurs de personnaliser les réglages des liens.

Étape 1. Importez les composants depuis @wordpress/components

Maintenant, vous devez importer plusieurs composants de @wordpress/components. Ouvrez votre fichier edit.js et ajoutez l’instruction import suivante :

import {
	TextControl,
	PanelBody,
	PanelRow,
	ToggleControl,
	ExternalLink
} from '@wordpress/components';
  • PanelBody ajoute un conteneur pliable à la colonne latérale des réglages.
  • PaneRow produit un conteneur générique pour les contrôles de la colonne latérale.
  • TextControl fournit un contrôle de saisie de texte.
  • ToggleControl fournit une bascule permettant aux utilisateurs d’activer/désactiver une option spécifique.
  • ExternalLink est un composant simple pour ajouter un lien externe.

Étape 2. Inclure les éléments correspondants dans votre code JSX

Vous allez d’abord ajouter l’élément ExternalLink au même niveau que RichText dans un conteneur div :

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

</div>

Le composant ExternalLink n’est pas documenté, nous nous sommes donc référés au composant lui-même pour obtenir la liste des attributs disponibles. Ici, nous utilisons les attributs href, className et rel.

Par défaut, la valeur de l’attribut rel est définie sur noopener noreferrer. Notre code ajoutera le nofollow mot clé à l’attribut rel de la balise a résultante lorsque la commande de basculement sera activée.

Vous pouvez maintenant ajouter des réglages de liens dans la colonne latérale du bloc.

Tout d’abord, vous allez ajouter un élément PanelBody dans InspectorControls, au même niveau que PanelColorSettings :

<InspectorControls>
	<PanelColorSettings 
	...
	/>
	<PanelBody 
		title={ __( 'Link Settings' )}
		initialOpen={true}
	>
	...
	</PanelBody>
</InspectorControls>

Voici ce que nous faisons avec ça :

  1. L’attribut title fournit le titre du panneau.
  2. initialOpen définit si le panneau est initialement ouvert ou non.

Ensuite, nous allons ajouter deux éléments PanelRow à l’intérieur de PanelBody, et un élément TextControl à l’intérieur de chaque PanelRow :

<PanelBody 
	title={ __( 'Link Settings', 'ka-example-block' )}
	initialOpen={true}
>
	<PanelRow>
		<fieldset>
			<TextControl
				label={__( 'KA link', 'ka-example-block' )}
				value={ kaLink }
				onChange={ onChangeKaLink }
				help={ __( 'Add your Academy link', 'ka-example-block' )}
			/>
		</fieldset>
	</PanelRow>
	<PanelRow>
		<fieldset>
			<TextControl
				label={__( 'Link label', 'ka-example-block' )}
				value={ linkLabel }
				onChange={ onChangeLinkLabel }
				help={ __( 'Add link label', 'ka-example-block' )}
			/>
		</fieldset>
	</PanelRow>
</PanelBody>

Le code ci-dessus devrait maintenant avoir l’air assez simple. Les deux contrôles de texte permettent aux utilisateurs de définir le libellé du lien et l’URL.

Nous ajouterons également un PanelRow supplémentaire avec un ToggleControl pour activer/désactiver une option spécifique, comme l’inclusion ou non d’un attribut :

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

Étape 3 : Définir les attributs nécessaires dans block.json

Définissez maintenant les attributs kaLink, linkLabel et hasLinkNofollow dans le fichier block.json :

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

Rien de plus à ajouter ici ! Passons à la définition des fonctions de gestion des événements.

Étape 4 : Définir les gestionnaires d’événements

Revenez au fichier edit.js, ajoutez les nouveaux attributs à l’objet attributes, et ajoutez les fonctions suivantes :

const { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;

const onChangeKaLink = ( newKaLink ) => {
	setAttributes( { kaLink: newKaLink === undefined ? '' : newKaLink } )
}

const onChangeLinkLabel = ( newLinkLabel ) => {
	setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } )
}

const toggleNofollow = () => {
	setAttributes( { hasLinkNofollow: ! hasLinkNofollow } )
}

Ces fonctions mettent à jour les valeurs des attributs correspondants lors de la saisie par l’utilisateur.

Étape 5 : Enregistrer les données

Enfin, nous devons mettre à jour la fonction de save dans save.js :

export default function save( { attributes } ) {
	
	const { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;

	const blockProps = useBlockProps.save( {
		className: `has-text-align-${ align }`
	} );
	
	return (
		<div 
			{ ...blockProps }
			style={ { backgroundColor: backgroundColor } }
		>
			<RichText.Content 
				tagName="p" 
				value={ content } 
				style={ { color: textColor } }
			/>
			<p>
				<a 
					href={ kaLink }
					className="ka-button"
					rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" }
				>
					{ linkLabel }
				</a>
			</p>
		</div>
	);
}

Notez qu’ici nous avons utilisé un élément a normal au lieu de ExternalLink .

Vous pouvez voir le résultat dans l’image ci-dessous.

Le panneau des réglages du lien dans la colonne latérale des réglages du bloc
Le panneau des réglages du lien dans la colonne latérale des réglages du bloc

Ajout de styles de blocs multiples

Dans une section précédente, vous avez appris à ajouter un contrôle de barre d’outils de bloc permettant aux utilisateurs d’aligner la saisie de l’utilisateur. Nous pouvons ajouter d’autres contrôles de style à la barre d’outils de bloc, mais nous pouvons également fournir un ensemble de styles de bloc prédéfinis parmi lesquels l’utilisateur peut choisir d’un simple clic.

À cette fin, nous allons utiliser une fonctionnalité utile de l’API de bloc : les styles de bloc.

Il vous suffit de définir la propriété styles du fichier block.json et de déclarer les styles correspondants dans vos feuilles de style.

Par exemple, vous pouvez ajouter le tableau de styles suivant :

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

Ainsi, vous venez d’ajouter un style par défaut et un style supplémentaire appelé border. Revenez maintenant à l’éditeur de blocs :

Deux styles de bloc pré-construits.
Deux styles de bloc pré-construits.

Les styles seront disponibles pour l’utilisateur en cliquant sur le sélecteur de bloc, puis en recherchant le panneau de styles dans la colonne latérale des réglages du bloc.

Sélectionnez un style et vérifiez les classes appliquées à l’élément p. Cliquez avec le bouton droit de la souris sur le bloc et inspectez. Une nouvelle classe a été ajoutée avec un nom structuré comme suit :

is-style-{style-name}

Si vous avez coché le style « Border », une classe is-style-border sera ajoutée à l’élément p. Si vous avez coché le style « Default », une classe is-style-default sera ajoutée à la place.

Il ne vous reste plus qu’à déclarer les propriétés CSS. Ouvrez le fichier editor.scss et remplacez les styles actuels par les suivants :

.wp-block-ka-example-block-ka-example-block {
    padding: 4px;
}

Vous pouvez maintenant faire de même avec style.scss. Comme nous l’avons mentionné plus haut, les styles définis dans style.scss sont appliqués à la fois sur l’interface publique et dans l’éditeur :

.wp-block-ka-example-block-ka-example-block {
	&.is-style-default{
		border: 0;
        background-color: #FFE2C7;
	}
	&.is-style-border{
		border: 2px solid #000;
        border-radius: 16px;
        background-color: #F6F6F6;
	}
}

Et c’est tout ! Rafraîchissez la page et amusez-vous avec vos nouveaux styles de blocs :

Comparaison des styles de bloc
Comparaison des styles de bloc

Emboîter les blocs Gutenberg avec le composant InnerBlocks

Bien que pleinement fonctionnel, notre bloc personnalisé n’est toujours pas très attrayant. Pour le rendre plus attrayant pour le public, nous pourrions ajouter une image.

Cela peut ajouter une couche de complexité à notre bloc, mais heureusement, vous n’avez pas besoin de réinventer la roue car Gutenberg fournit un composant spécifique que vous pouvez utiliser pour créer une structure de blocs imbriqués.

Le composant InnerBlocks est défini comme suit :

InnerBlocks exporte une paire de composants qui peuvent être utilisés dans les implémentations de blocs pour activer le contenu des blocs imbriqués.

Tout d’abord, vous devez créer un nouveau fichier .js dans le dossier src. Dans notre exemple, nous appellerons ce fichier container.js.

Vous devez maintenant importer la nouvelle ressource dans le fichier index.js :

import './container';

Retournez dans le fichier container.js et importez les composants nécessaires :

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

L’étape suivante consiste à définir un modèle fournissant la structure dans laquelle les blocs seront placés. Dans l’exemple suivant, nous définissons un modèle composé de deux colonnes contenant un bloc Image de base et notre bloc personnalisé :

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

Le modèle est structuré comme un tableau de blockTypes (nom du bloc et attributs facultatifs).

Dans le code ci-dessus, nous avons utilisé plusieurs attributs pour configurer les blocs Columns et Column. Plus précisément, l’attribut templateLock : 'all' verrouille les blocs Columns afin que l’utilisateur ne puisse pas ajouter, réorganiser ou supprimer des blocs existants. templateLock peut prendre l’une des valeurs suivantes :

  • all — InnerBlocks est verrouillé, et aucun bloc ne peut être ajouté, réorganisé ou supprimé.
  • insert — Les blocs peuvent uniquement être réorganisés ou supprimés.
  • false — Le modèle n’est pas verrouillé.

Le modèle est ensuite affecté à l’élément InnerBlocks :

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

Pour éviter tout problème de compatibilité, nous avons également ajouté un attribut templateLock au composant InnerBlocks (voir également le problème #17262 et la commande #26128).

Voici notre fichier final container.js :

registerBlockType('ka-example-block/ka-example-container-block', {
	title: __( 'KA Container block', 'ka-example-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>
		)
	},
});
Le bloc final dans l'éditeur de blocs
Le bloc final dans l’éditeur de blocs

Améliorations supplémentaires

Notre bloc est entièrement fonctionnel, mais nous pourrions l’améliorer un peu avec quelques petits changements.

Nous avons attribué l’attribut backgroundColor au paragraphe généré par le composant RichText. Cependant, nous pouvons préférer attribuer la couleur d’arrière-plan à la div du conteneur :

Donc, modifiez le fichier edit.js et  div save.js comme suit :

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

Cela permettra à l’utilisateur de modifier l’arrière-plan de l’ensemble du bloc.

En revanche, un changement plus pertinent concerne la méthode useBlockProps. Dans le code original, nous définissions la constante blockProps comme suit :

const blockProps = useBlockProps();

Mais nous pouvons utiliser useBlockProps de manière plus efficace en passant un ensemble de propriétés. Par exemple, nous pouvons importer classnames depuis le module classnames et définir le nom de la classe d’enveloppe en conséquence.

Dans l’exemple suivant, nous attribuons un nom de classe en fonction de la valeur de l’attribut align (edit.js) :

import classnames from 'classnames';

...

export default function Edit( { attributes, setAttributes } ) {
	...
	
	const onChangeAlign = ( newAlign ) => {
		setAttributes( { 
			align: newAlign === undefined ? 'none' : newAlign, 
		} )
	}

	const blockProps = useBlockProps( {
		className: `has-text-align-${ align }`
	} );
	...
}

Nous ferons le même changement dans le fichier save.js :

import classnames from 'classnames';

...

export default function save( { attributes } ) {
	...
	const { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;

	const blockProps = useBlockProps.save( {
		className: `has-text-align-${ align }`
	} );
	...
}

Et c’est fini ! Vous pouvez maintenant exécuter le build pour la production :

npm run build

Résumé

Et nous voici arrivés à la fin de cet incroyable voyage ! Nous avons commencé par la configuration de l’environnement de développement et avons fini par créer un type de bloc complet.

Comme nous l’avons mentionné dans l’introduction, une solide connaissance de Node.js, Webpack, Babel et React est essentielle pour créer des blocs Gutenberg avancés et vous positionner sur le marché en tant que développeur Gutenberg professionnel.

Mais vous n’avez pas besoin d’avoir une expérience établie de React pour commencer à vous amuser avec le développement de blocs, cependant. Le développement de blocs pourrait vous donner une motivation et des objectifs pour acquérir des compétences de plus en plus larges dans les technologies derrière les blocs Gutenberg.

Ce guide est donc loin d’être complet. Il s’agit simplement d’une introduction à une grande variété de sujets qui vous aideront à commencer à construire vos tout premiers blocs Gutenberg.

Pour cette raison, nous vous recommandons d’approfondir vos connaissances en lisant attentivement la documentation et les guides en ligne. Parmi les nombreuses ressources disponibles, nous vous recommandons les suivantes :

Si vous débutez dans le développement de WordPress, vous voudrez peut-être comprendre les concepts de base du développement frontend. Voici une liste rapide de ressources qui peuvent vous aider à démarrer :

Et n’oubliez pas que le code complet des exemples de ce guide est disponible sur Gist.

Maintenant c’est votre tour : Avez-vous développé des blocs Gutenberg ? Quelles sont les principales difficultés que vous avez rencontrées jusqu’à présent ? Faites-nous part de votre expérience dans les commentaires !

Carlo Daniele Kinsta

Carlo is a passionate lover of webdesign and front-end development. He has been playing with WordPress for more than 20 years, also in collaboration with Italian and European universities and educational institutions. He has written hundreds of articles and guides about WordPress, published both on Italian and international websites, as well as on printed magazines. You can find him on LinkedIn.