On va voir comment créer un bloc personnalisé dans le nouvel éditeur de blocs Gutenberg de WordPress. Il s’agira d’ajouter un paragraphe dont on pourra changer le contenu.
La création d’un bloc dans WordPress (au moment de l’écriture) se fait via JavaScript (pas PHP) à l’aide d’une fonction appelée registerBlockType()
. Le fichier JavaScript est chargé en PHP avec le hook enqueue_block_editor_assets
.
La fonction registerBlockType()
se trouve à l’intérieur de la bibliothèque wp.blocks
, qui contient des fonctions utiles pour la création de blocs, ainsi que les principaux blocs WordPress eux-mêmes. WordPress rend cette fonction accessible en tant que variable globale dans l’objet window.wp
sous la forme wp.blocks.registerBlockType()
.
registerBlockType()
: Nom et Paramètres de réglages
La fonction registerBlockType()
prend deux paramètres : le nom et les paramètres (settings).
- Le
nom
: Les noms de bloc doivent contenir un préfixe d’espace de noms, inclure uniquement des caractères alphanumériques en minuscules ou des tirets et commencer par une lettre. Exemple:my-plugin/my-custom-block
. En gros, on commence par une chaîne en caractères minuscules et des tirets si nécessaire, il doit y avoir un slash (/), et une autre chaîne. Voir la source. settings [Object]
– Le paramètresettings
est un objet avec plusieurs propriétés prédéfinies dont certaines doivent être attribuées pour que le bloc fonctionne.
Le paramètre Settings
de registerBlockType()
:
L’objet settings
de registerBlockType()
possède sept propriétés qui incluent à la fois des métadonnées sur le bloc ainsi que des méthodes contrôlant l’interface utilisateur et les fonctionnalités du bloc dans l’éditeur et sur le frontend.
title [string]
– Le titre donne un nom au bloc. Il peut être traduit en utilisantwp.i18n .__()
.category [string]
– La catégorie détermine dans quelle rubrique se trouvera le bloc. Les options sontcommon
,formatting
,layout
,widgets
etembed
.icon [Dashicon|Element]
– L’icone representera graphiquement le bloc. On peut utiliser les noms de classesWP Dashicons
ou utiliser un icon personnalisé enSVG
.keywords [Array]
– keyword fournit jusqu’à trois mots clés/phrases additionnels pour rechercher le bloc. Limité à 3.attributes [Object]
– Les attributs indiquent quels contenus dynamiques sont utilisés dans le bloc. Plusieurs attributs existent selon les types de données utilisées. Les paramètres d’attribut sont facultatifs si votre bloc n’utilise aucune donnée dynamique. Ces données sont ensuite accessibles parprops.attributes.name
. Référence.edit [function]
– Indique ce qui sera affiché dans la zone du bloc dans l’éditeur. Cette fonction doit retourner un élément React valide en utilisantwp.element.createElement()
ouJSX
. Cette fonction peut accepter des données dynamiques en paramètreprops
de la fonction.save [function]
– C’est une fonction qui indique le contenu qui sera sauvegardé et affiché sur le frontend. Cette fonction doit retourner un élément React valide en utilisantwp.element.createElement()
ouJSX
. Cette fonction peut accepter des données dynamiques en paramètreprops
de la fonction.
Charger le fichier JavaScript
Dans functions.php
ou dans un plugin, on charge le fichier Javascript qui créera le block personnalisé.
1 2 3 4 5 6 7 8 9 10 |
add_action('enqueue_block_editor_assets', 'xbs_loadMyBlock'); function xbs_loadMyBlock() { wp_enqueue_script( 'test-block', // Handle id plugin_dir_url(__FILE__) . 'test-block.js', // Block JavaScript URL ['wp-blocks','wp-i18n', 'wp-element'], // Dépendances true // Version ); } |
On édite ensuite le fichier JavaScript test-block.js
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
( function( wp ) { const el = wp.element.createElement; const __ = wp.i18n.__; const textdomain = 'textdomain'; const iconEl = 'universal-access-alt'; wp.blocks.registerBlockType( 'block/test', { title: __( 'My Block', textdomain ), category: 'common', icon: iconEl, // Remove to make block editable in HTML mode. supportHTML: false, edit: function( props ) { return el( 'p', { className: props.className }, __( 'Replace with your content!', textdomain ) ); }, save: function() { return el( 'p', {}, __( 'Replace with your content!', textdomain ) ); } } ); } )( window.wp ); |
On recharge l’éditeur et l’on voit apparaître, en appuyant sur nouveau bloc, l’icone dashicons ‘universal-access-alt’ et le titre ‘My Block’ dans la section ‘common’ des blocs.

On peut personnaliser l’icone représentant le bloc en définissant un svg
et un path
dans iconEl
:
1 |
const iconEl = el( 'svg', { width: 20, height: 20, viewBox: '0 0 512 512' }, el('path', { d: "m236 7c-63 6-114 30-157 72-38 39-62 87-71 142-2 16-2 54 0 70 9 56 33 103 71 142 39 38 87 62 142 71 16 2 54 2 70 0 56-9 103-33 142-71 38-39 62-86 71-142 2-16 2-54 0-70-9-55-33-103-71-142-39-38-87-62-141-70-10-2-48-3-56-2z m-62 129c18 3 32 9 37 16 1 1 10 31 20 65 10 34 19 67 21 71l3 9 16-33c22-45 46-96 58-123 3-7 5-7 20-7 20 0 41 4 51 11 8 5 9 8 9 28 0 14 3 110 5 168 0 17 0 20-1 23-3 4-8 5-20 5-24-2-43-9-48-20-1-2-1-15-1-69 0-36 0-69-1-74l0-9-8 15c-4 9-14 31-23 49-21 45-28 60-37 83-11 25-10 25-26 24-20 0-38-5-46-14-4-3-4-5-12-33-18-66-34-123-35-121-1 3-12 87-18 139-2 13-3 25-3 26-1 2-5 4-9 4-1 0-6-1-9-2-8-2-15-8-18-14-2-6-2-13 15-113 5-36 11-73 13-83 1-10 3-18 4-20 0-1 3-2 5-2 2-1 4-1 5-2 1 0 25 1 33 3z" } ) ); |
Le path est déterminé à l’aide d’un générateur de police d’icones telle que Fontastic. Ne pas oublier l’attribut viewBox
, sinon cela rique de ne pas marcher.

Le code utilisé pour les fonctions edit
et save
est du code wp React Element
. Si l’on veut utiliser du JSX
, il faut au préalable compilé le code JavaScript, ce qui fera l’objet d’un nouvel article. Pour transformer facilement du code JSX
en React.createElement
ou wp.element.createElement
, on peut utiliser le compilateur Babel en ligne.
Par exemple, si l’on veut insérer un bloc du type :
<pre><code>Replace with your content</code></pre>

On insère le code suivant pour les fonctions edit
et save
:
1 2 3 4 5 6 7 8 9 10 11 |
edit: function( props ) { return el( "pre", { className: props.className }, el( "code", null, __( 'Replace with your content!', textdomain ) ) ); }, |
Et hop, on peut ajouter un bloc personnalisé à l’Editeur de blocs Gutenberg de WordPress.