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ètre settings 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 utilisant wp.i18n .__().
• category [string] – La catégorie détermine dans quelle rubrique se trouvera le bloc. Les options sont common, formatting, layout, widgets et embed.
• icon [Dashicon|Element] – L’icone representera graphiquement le bloc. On peut utiliser les noms de classes WP Dashicons ou utiliser un icon personnalisé en SVG.
• 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 par props.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 utilisant wp.element.createElement() ou JSX. Cette fonction peut accepter des données dynamiques en paramètre props 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 utilisant wp.element.createElement() ou JSX. Cette fonction peut accepter des données dynamiques en paramètre props 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é.

On édite ensuite le fichier JavaScript test-block.js.

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 :

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 :

Et hop, on peut ajouter un bloc personnalisé à l’Editeur de blocs Gutenberg de WordPress.