Avec l’évolution de l’éditeur Gutenberg dans WordPress, la création de blocs personnalisés est devenue un incontournable pour les développeurs souhaitant enrichir l’expérience utilisateur et personnaliser les contenus.
Dans ce tutoriel, nous allons apprendre pas à pas à créer un plugin Gutenberg qui ajoute un bloc personnalisé « Hello World » à l’éditeur de WordPress.
- Objectif: comprendre les bases de la création d’un bloc Gutenberg.
- Public: développeurs débutants/intermédiaires ayant des notions en PHP et JavaScript.
Nous allons voir :
- Comment préparer l’environnement de développement sous WordPress.
- Comment structurer un plugin WordPress.
- Comment enregistrer un bloc Gutenberg en PHP.
- Comment compiler et tester le bloc dans l’éditeur.
À la fin du tutoriel, vous aurez :
- Un plugin fonctionnel ajoutant un bloc « Hello World » dans WordPress.
- Une compréhension des bases pour créer vos propres blocs plus avancés.
- Une méthode claire et structurée pour développer d’autres fonctionnalités Gutenberg.
Etape 1 : Installer/Configurer WordPress en local
1. Choisir un outil de développement local
La solution retenue pour cet exercice sera d’installer WordPress en local avec Local.
- Créer un nouveau site WordPress :
- Le nommer par ex « demo-gutenberg-block » :
- On peut rester sur « Preferred » :
- Renseigner les informations de connexion que vous souhaitez et cliquer sur « Add Site » :
- Le site a été créé :
2. Se connecter au Dashboard du site
- Se connecter avec les identifiants choisis lors de la création :
- On arrive sur le Dashboard de notre site :
Etape 2 : Créer la base du plugin
1. Créer le dossier du plugin
Lors de la création du site, des dossiers et fichiers ont été créés dans le dossier « Local Sites » (situé là ou Local a été installé sur le poste).
On va donc retrouver dans le dossier Local Sites > demo-gutenberg-block l’ensemble des dossiers qui composent notre site nouvellement créé.
On va retrouver les dossiers app/, conf/ et logs/.
- Aller dans ..app > public > wp-content > plugins et créer le dossier de notre plugin, ici nommé my-first-block-hello-world :
- Ouvrir ensuite le dossier du projet dans un éditeur de code (ici on utilisera Visual Studio Code) :
2. Créer le fichier principal du plugin
- Créer dans le dossier app > wp-content > plugins > my-first-block-hello-world un fichier PHP nommé « my-first-block-hello-world.php » :
- Dans ce fichier, ajouter en commentaire les informations sur notre plugin :
<?php /** * Nom du plugin : My First Block Hello World * Plugin URI : https://example.com * Description : Example of a plugin to create a Gutenberg block "Hello World" * Version : 1.0.0 * Auteur : Votre nom * Author URI : https://example.com * Text Domain : my-first-block-hello-world */On va retrouver dans ce commentaire :
- Plugin Name: le nom affiché dans l’interface » Extensions » de WordPress.
- Plugin URI (optionnel) : peut pointer vers un site officiel ou un dépôt Git.
- Description: brève description qui apparaît dans la liste des plugins.
- Version: Indique la version de ton plugin.
- Author / Author URI : notre nom et éventuellement notre site web.
- Text Domain: nom de domaine textuel pour la traduction (important si l’on gère les traductions).
- On ajoute une fonction qui va permettre de bloquer l’accès au fichier :
<?php /** * Nom du plugin : My First Block Hello World * Plugin URI : https://example.com * Description : Example of a plugin to create a Gutenberg block " Hello World " * Version : 1.0.0 * Author : Ton Nom * Author URI : https://example.com * Text Domain : my-first-block-hello-world */ if ( ! defined('ABSPATH')) { exit ; }Cette fonction est une mesure de sécurité couramment utilisée dans les fichiers de plugins et thèmes WordPress. Elle empêche l’accès direct au fichier par un utilisateur malveillant.
3. Activation du plugin
- Sur le Dashboard du site, dans le menu Plugins ⇒ Installed Plugins on voit le plugin que l’on vient de créer :
- Cliquer sur « Activate » pour l’activer, et on va obtenir le message « Plugin activated » :
Etape 3 : Configurer la structure du bloc
1. Création d’un dossier dédié au code source
Dans le dossier du plugin my-first-block-hello-world, on va créer un dossier nommé « src ».
Il contiendra tout le code JS (et éventuellement CSS/SCSS) du futur bloc.
2. Utiliser un outil de build
Pour créer un bloc Gutenberg moderne, on utilise souvent Node.js et des outils comme Babel ou Webpack. Cela permet :
- D’écrire du code ESNext (import, const, arrow functions, etc.).
- D’écrire du JSX (une syntaxe semblable à React).
- De compiler en un seul fichier JS » compatible » pour l’éditeur et/ou le front.
Il est possible de le faire sans outil de build mais on va préférer en utiliser un avec la méthode recommandée @wordpress/scripts.
3. Utiliser @wordpress/scripts
- WordPress propose un package officiel @wordpress/scripts qui facilite la configuration Webpack/Babel.
- On peut l’installer (via npm) dans le dossier du plugin, puis l’utiliser pour compiler le code.
- C’est la méthode recommandée pour créer des blocs Gutenberg (et la plus courante).
4. Initialiser npm et installer @wordpress/scripts
- S’assurer que Node.js et npm sont installés sur le poste :
node -v npm -vLes version apparaitront s’ils sont installés sinon, les installer.
- Initialiser le projet Node.
Ouvrir un terminal dans le dossier my-first-block-hello-world et utiliser la commande :
npm init -yCela va créer un fichier « package.json » :
On y retrouve les réglages de base et on va modifier « type » : « commonjs » par « type » : « module ») :
{ "name" : "my-first-block-hello-world", "version" : "1.0.0", "main" : "index.js", "scripts" : { "test" : "echo "Error : no test specified" && exit 1" }, "keywords" : [], "author" : "", "licence" : "ISC", "type" : "module", "description" : "" }- Installer @wordpress/scripts.
Toujours dans le même dossier, exécuter la commande :
npm install --save-dev @wordpress/scriptsCeci ajoute @wordpress/scripts aux dépendances de développement. On obtient également le dossier node_modules/ et le fichier « package-lock.json » :
- Mettre à jour le script dans le package.json :
Dans le package.json on voit qu’il y a maintenant une section « devDependencies » et celle-ci liste @wordpress/scripts :
{"name" : "my-first-block-hello-world", "version" : "1.0.0", "main" : "index.js", "scripts" : { "test" : "echo "Error : no test specified" && exit 1" }, "keywords" : [], "author" : "", "licence" : "ISC", "type" : "module", "description" : "", "devDependencies" : { "@wordpress/scripts" : "^30.9.0" } }On va ajouter 2 commandes pratiques dans la section « scripts » :
-start : lance un mode » développement » (avec rebuild automatique quand on modifa des fichiers).
-build : génère la version finale optimisée du JS (et éventuellement du CSS).
{"name" : "my-first-block-hello-world", "version" : "1.0.0", "main" : "index.js", "scripts" : { "test" : "echo "Error : no test specified" && exit 1", "start" : "wp-scripts start", "build" : "wp-scripts build" }, "keywords" : [], "author" : "", "licence" : "ISC", "type" : "module", "description" : "", "devDependencies" : { "@wordpress/scripts" : "^30.9.0" } }5. Création du fichier principal du bloc (JS)
- Ici nous allons créer, dans le dossier « src », un fichier nommé « index.js » qui va contenir le code du block Gutenberg :
- Lancer la compilation en local
Dans le terminal (toujours depuis le dossier du plugin) on exécute la commande :
npm run buildUn dossier build est créé :
6. Créer les fichiers CSS
Pour styliser le bloc, nous pourrons ajouter dans le dossier src/ :
- editor-style.css : styles spécifiques à l’éditeur (dans Gutenberg).
- style.css : styles pour le front-end.
Importer ces fichiers dans « index.js » pour que le build les prenne en compte. Par exemple :
import './editor-style.css' ; import './style.css' ;On va ajouter dans « editor-style.css » un minimum de styles :
.wp-block-mpbhw-hello-world { background-color : #bbb27e ; padding : 10px ; }Et en ajouter également dans « style.css » :
.wp-block-mpbhw-hello-world { border : solid 2px #e9ec10 ; padding : 10px ; }Etape 4 : Enregistrer le bloc côté PHP
1. Comprendre la fonction register_block_type()
Depuis WordPress 5.0, l’API de blocs fournit la fonction register_block_type(). Elle permet :
- De déclarer l ‘identifiant d’un bloc (ex : mon-plugin/hello-world).
- D’indiquer quel script JS doit être chargé dans l’éditeur.
- D’indiquer également quels fichiers CSS doivent être chargés (côté éditeur et côté front), si besoin.
Voir la documentation pour plus de détails sur la fonction register_block_type().
2. Créer une fonction d’init pour le bloc
- Dans le fichier principal de plugin, « my-first-block-hello-world.php », sous l’en-tête, créer une fonction (par exemple « mpbhw_register_block() ») pour tout ce qui concerne l’enregistrement du bloc.
- Ensuite, accrocher cette fonction à l’action « init ».
<?php /** * Plugin Name : My First Block Hello World * Plugin URI : https://example.com * Description : Example of a plugin to create a Gutenberg block "Hello World" * Version : 1.0.0 * Auteur : Your name * Author URI : https://example.com * Text Domain : my-first-block-hello-world */ if ( ! defined('ABSPATH')) { exit ; } function mpbhw_register_block() { // 1. save editor script wp_register_script( 'mpbhw-editor-script', plugins_url('build/index.js', __FILE__), array('wp-blocks', 'wp-element', 'wp-editor'), filemtime(plugin_dir_path(__FILE__) . 'build/index.js') ) ; // 2. check and save the editor style sheet $editor_css_file = plugin_dir_path(__FILE__) . 'build/index.css' ; if (file_exists($editor_css_file)) { wp_register_style('mpbhw-editor-style', plugins_url('build/index.css', __FILE__), array('wp-edit-blocks'), filemtime($editor_css_file) ) ; } // 3. vérifier et sauvegarder la feuille de style pour le front-end $front_css_file = plugin_dir_path(__FILE__) . 'build/style-index.css' ; if (file_exists($front_css_file)) { wp_register_style('mpbhw-front-style', plugins_url('build/style-index.css', __FILE__), array(), filemtime($front_css_file) ) ; } // 4. Save the block with its assets register_block_type('mpbhw/hello-world', array('editor_script' => 'mpbhw-editor-script', // JS for the editor 'editor_style' => 'mpbhw-editor-style', // CSS for the editor (if présent) 'style' => 'mpbhw-front-style', // CSS for the frontend (if présent) )) ; } // Run the function when WordPress starts add_action('init', 'mpbhw_register_block') ;Explications
- wp_register_script():
- Associe un handle ( » mpbhw-editor-script « ) à un fichier JS et à ses dépendances.
- plugins_url( ‘build/index.js’, FILE ) renvoie l’URL vers le fichier JS compilé.
- filemtime(…) est une astuce pour gérer le cache (il génère une version unique à chaque modification).
- wp_register_style():
- Même principe pour un fichier CSS, si vous en avez un pour l’éditeur et/ou le front.
- register_block_type():
- Déclare l’identifiant du bloc (mpbhw/hello-world) en reliant le script de l’éditeur (editor_script) et, si nécessaire, les styles (editor.css et styles.css).
- add_action( ‘init’, … ):
- On attache la fonction d’enregistrement au hook init, afin que WordPress sache charger le bloc au bon moment.
3. Vérifier l’enregistrement du bloc
- Activer ou réactiver le plugin (si ce n’est pas déjà fait).
- Vérifier dans l’admin WordPress → aucun message d’erreur ne doit apparaître.
- Si tout se passe bien, WordPress sait désormais qu’il y a un bloc « mpbhw/hello-world » et qu’il doit charger « index.js » lorsque l’on édite un article.
À ce stade
- On ne verra pas encore concrètement le bloc dans l’éditeur, car on n’a pas fini de coder la logique dans index.js.
- Mais l’enregistrement technique côté PHP est en place.
Etape 5 : Créer le bloc côté JavaScript (Gutenberg)
1. Importer les dépendances
Dans le fichier « src/index.js », on va importer les fonctions et modules dont on va avoir besoin pour un bloc de base :
import { registerBlockType } from '@wordpress/blocks' ; import { __ } from '@wordpress/i18n' ; import { useBlockProps } from '@wordpress/block-editor' ;- @wordpress/blocks: permet d’enregistrer le bloc (registerBlockType).
- @wordpress/i18n: permet d’utiliser la fonction __() pour la traduction (optionnel).
- @wordpress/block-editor: regroupe différents composants et hooks pour l’éditeur (ex. useBlockProps, InspectorControls, ColorPalette, etc.).
2. Déclarer le bloc avec registerBlockType
Toujours dans src/index.js, on appelle registerBlockType(‘namespace/slug’, config) pour définir notre bloc :
import './editor-style.css' ; import './style.css' ; import { registerBlockType } from '@wordpress/blocks' ; import { __ } from '@wordpress/i18n' ; import { useBlockProps } from '@wordpress/block-editor' ; registerBlockType('mpbhw/hello-world', { title : __('Hello World', 'my-first-block-hello-world'), icon : 'universal-access-alt', // icône personnalisée WP ou SVG category : 'text', // Block categories (common, text, widgets, etc.) // Attributes (data to be stored). attributes : { message : { type : 'string', default : 'Hello World!', }, }, // The function that manages the editing interface (on the Gutenberg editor side). edit : (props) => { // Extract or read the value of the const attribute { attributes, setAttributes } = props ; const { message } = attributes ; // Gutenberg Hook to manage HTML container props const blockProps = useBlockProps({ className : 'wp-block-mpbhw-hello-world' }) ; // Add style editor-style.css from block to editor // Editor's rendering return ( <div {...blockProps}> <h2>Hello from the editor!</h2> <input type="text" value={props.attributes.message} onChange={(e) => setAttributes({ message : e.target.value })}> </div> ) ; }, // The function that manages final rendering (on the front end). save : (props) => { const { attributes } = props ; const { message } = attributes ; // Use `useBlockProps.save()` if you want to keep the CSS classes of WP. const blockProps = useBlockProps.save() ; // The final HTML rendering returns ( <div {...blockProps}> <p>{props.attributes.message}</p> </div> ) ; }, }) ;Explications
- mpbhw/hello-world: l’identifiant unique du bloc (namespace + slug). Il doit correspondre à celui déclaré en PHP : register_block_type(‘mpbhw/hello-world’, … ).
- title: le nom qui apparaît dans la liste des blocs.
- icon: l’icône du bloc (peut être un nom d’icône Dashicons, un objet, ou un SVG).
- category: la catégorie dans laquelle le bloc apparaît (ex : common, text, media, widgets, embed, etc.).
- attributes: définition des données que le bloc va stocker (ici, une chaîne de texte message).
- edit(props): le composant React pour l’éditeur Gutenberg.
- props.attributes : récupère les attributs actuels.
- props.setAttributes() : met à jour les attributs.
- useBlockProps() : hook permettant de gérer les classes et data internes pour le bloc.
- save(props): la fonction qui génère le HTML final du bloc sur le front.
- Le contenu d’attributs est transformé en balises HTML.
(Ici, on utilise un simple <input> pour modifier la valeur. On pourra également utiliser un composant Gutenberg comme TextControl, RichText, etc.)
Compiler et tester
Exécuter dans le terminal :
npm run buildCela va générer (ou regénérer) des fichiers compilés dans le dossier build/ :
- Vérifier dans WordPress (sous Plugins) que le plugin est activé.
- Ouvrir l’éditeur Gutenberg (par exemple, créez un nouvel article) :
- Rechercher » Hello World » parmi les blocs et l’ajouter :
On obtient le bloc avec un <h2>Hello from the editor</h2> et un <input> qui va nous permettre de saisir notre texte. On a également la couleur de background définie dans « editor-style.css » et la bordure définie dans « style.css ».
On retrouve ce code dans src/index.js pour le rendu côté éditeur :
return ( <div {...blockProps}> <h2>Hello from the Editor!</h2> <input type="text" value={props.attributes.message} onChange={(e) => setAttributes({ message : e.target.value })} /> </div>Et pour le rendu côté front, dans « src/index.js » :
return ( <div {...blockProps}> <p>{props.attributes.message}</p> </div>- Entrer un nouveau texte dans le champ <input> :
- Vérifier la prévisualisation. On obtient notre message dans une balise <p>, ainsi que le style qui provient de « style.css » :
Félicitations
Vous avez suivi toutes les étapes nécessaires pour créer un bloc personnalisé Gutenberg dans WordPress, depuis l’installation de l’environnement jusqu’à l’intégration des styles et la gestion du rendu.
À présent, votre bloc « Hello World » est pleinement fonctionnel :
- Il est enregistré et apparaît dans la bibliothèque de blocs.
- Il permet à l’utilisateur de saisir du texte et l’affiche sur le front-end.
- Il applique des styles spécifiques dans l’éditeur et sur le site.
Cela vous donne des bases pour développer d’autres blocs plus avancés !
Pour aller plus loin
Maintenant que vous maîtrisez les bases, voici quelques pistes d’amélioration pour rendre votre bloc plus interactif et puissant :
- Utiliser « RichText » pour du texte formaté : actuellement, le bloc utilise un simple <input>. Vous pouvez remplacer cela par un éditeur de texte enrichi en utilisant le composant « RichText » de Gutenberg. Cela permettra de saisir du texte en gras, en italique, avec des liens etc.
- Ajouter des options de personnalisation (« InspectorControls ») : vous pouvez ajouter un panneau d’options dans la barre latérale de Gutenberg pour que l’utilisateur puisse personnaliser le bloc. On pourra ainsi choisir une couleur de texte, modifier son alignement ou ajouter une couleur de fond.
- Créer un bloc plus complexe (galerie, liste, citations, etc.) : il est possible d’en faire un bloc plus avancé, comme une galerie personnalisée, un compteur dynamique ou un accordéon par ex.
Vous avez maintenant toutes les clés en main pour créer des blocs sur-mesure avec Gutenberg !
WordPress évolue constamment, continuez à expérimenter, ajoutez de nouvelles fonctionnalités et explorez la documentation officielle de WordPress pour aller plus loin.
