Déclarer un bloc Gutenberg avec registerBlockType

Un mot sur les prérequis

Pour créer un bloc avec Gutenberg, il faut quelques prérequis tels que la mise en place de React et WebPack. Si vous arrivez sur ce cours directement depuis Internet, je vous conseille d’aller préalablement faire un tour sur la présentation de create-block afin de vous préparer.

Télécharger les exemples de la formation

Afin de bien suivre les exemples abordés tout au long de la formation, je vous invite à télécharger mon extension depuis mon répertoire Github. De cette manière, vous n’aurez pas besoin de tout réécrire, et vous pourrez facilement expérimenter :

Télécharger l’extension

Placez l’extension dans le dossier wp-content/plugins de votre site, et pensez à faire un npm install et npm run start depuis votre terminal afin que tout fonctionne.

Gutenberg, extensible par nature

WordPress a conçu son nouvel éditeur de manière à ce qu’il puisse être facilement étendu et on va justement en voir toute la puissance ici.

WordPress a toujours permis aux développeurs de facilement étendre ses possibilités pour personnaliser chaque site selon ses besoins.

Et Gutenberg ne déroge pas à la règle : il a été prévu en ce sens et propose une surcouche au dessus de React et nous permet d’ajouter facilement nos blocs.

Déclarer un bloc Gutenberg

Allez c’est parti ! Vous allez voir que déclarer un bloc Gutenberg est vraiment très facile, car WordPress a tout prévu pour nous simplifier la tâche.

Si vous bien avez suivi le cours sur create-block, vous avez une structure d’extension prête à l’emploi. Le premier bloc est déjà créé et c’est celui-ci que l’on va analyser.

On va commencer par regarder du côté du fichier block.json qui nous permet de déclarer les informations du bloc.

#1 • Les paramètres du bloc dans block.json

On peut voir dans ce fichier plusieurs données. Toutes ne sont pas obligatoires d’ailleurs pour faire fonctionner le bloc. On va regarder plus en détails à quoi servent ces paramètres.

apiVersion

L’éditeur a pas mal évolué depuis ses débuts en 2018, et pourrait encore évoluer à terme. Actuellement, on utilise la deuxième version de l’api pour déclarer nos blocs. Laissez donc ce paramètre tel quel sur tous vos blocs.

name

C’est le nom unique de votre bloc, que l’on appelle également le slug. Il ne doit pas contenir d’accent, d’espace ou de caractères spéciaux.

Il est composé de 2 parties : le nom de votre plugin, suivi du nom du bloc, le tout séparé par un slash /.

Dans mon cas, le nom du plugin est capitainewp. Il sera donc commun à tous les blocs de mon extension. Seule la seconde partie changera d’un bloc à l’autre.

version

C’est la version de votre bloc. Comme c’est notre première mouture, on indiquera naturellement 1.0. Ce nombre pourra évoluer dans le temps afin de suivre l’évolution de votre bloc.

Cela permet notamment de vider le cache lors du changement de version, afin que le navigateur télécharge les versions à jour des scripts et des styles du bloc.

title

C’est le titre du bloc. Il sera affiché dans l’interface de choix de bloc et donc lu par un humain.

Par contre, en le déclarant ici, vous ne pourrez pas le rendre traduisible. Il faudra alors le déclarer plutôt dans le fichier index.js, que l’on voit juste après.

description

Une courte explication de l’utilité de votre bloc. Elle sera affichée à droite de l’écran, dans la barre latérale de l’inspecteur.

icon

Chaque bloc a sa propre icône et c’est ici que vous allez définir la votre. Vous pouvez même vous servir des Dashicons ou bien insérer votre propre SVG, et ce sera d’ailleurs l’objet du prochain cours.

Concernant les Dashicons, il ne faut pas mettre le préfixe dashicons- dans le nom donc si vous choisissez dashicons-awards il faudra simplement écrire awards.

Essayez d’ajouter votre premier bloc depuis l’éditeur visuel, dans une nouvelle page ou un nouvel article. Une fois votre bloc ajouté, vous devriez voir le titre, la description et l’icône dans l’inspecteur à droite.

category

C’est la catégorie à laquelle appartient votre bloc. Gutenberg propose par défaut 6 catégories : text, media, design, widgets, theme et embed.

Elles apparaissent notamment quand le rédacteur sélectionne un bloc :

Vous pourriez même créer votre propre catégorie pour regrouper vos blocs grâce à un petit hook :

C’est ce qu’a fait par exemple WooCommerce avec ses blocs, ce qui est logique puisqu’aucune catégorie par défaut ne convenait. De cette manières, vous retrouvez facilement tous les blocs dédiés à l’e-commerce :

keywords

Vous pouvez ajouter une liste de mots-clés pour permettre de trouver plus facilement un bloc lors d’une recherche. Par exemple pour un bloc « produit » on pourrait ajouter les mots-clés « WooCommerce » et « acheter ».

Dans notre cas, j’ai ajouté le mot clé « Premier bloc ». Du coup, si je lance une recherche sur le terme premier, je devrais pouvoir trouver mon bloc :

Ce paramètre est optionnel. Si le nom du bloc est assez évocateur, vous n’avez pas besoin d’ajouter de mots-clés.

supports

Ce paramètre va nous permettre d’ajouter ou retirer des comportements dans notre bloc. Par exemple, dans ce cas précis, on retire le support du HTML.

Cela veut dire que l’utilisateur ne pourras pas éditer le bloc en vue HTML, et de ce fait, il sera moins enclin à tout casser. On verra plus tard les autres options disponibles.

---

On vient de voir les paramètres principaux, ce qui sont le plus souvent utilisés. Il y en a certains que l’on n’a pas abordés, comme le paramètre attributes que j’ai volontairement omis, et qui nous permettra de rendre tout cela un peu plus dynamique, mais patience, c’est pour les prochains cours !

#2 • Déclarer le bloc en Javascript dans index.js

Maintenant, on va regarder dans index.js. C’est ici que le bloc est initialisé auprès de l’éditeur.

Les imports

Les premières lignes sont en général des inclusions d’éléments de librairies externes. Le Javascript s’est beaucoup rapproché de certains langages de programmation qui nécessitent de faire des appels en début de fichier.

Ici on charge la fonction registerBlockType() de @wordpress/blocks, c’est la fonction la plus importante de ce fichier.

L’import de la feuille de style indique simplement que le fichier CSS devra être compilé en même temps que ce bloc. Le compilateur générera donc la feuille de style dans le dossier /build/.

Enfin, on charge 2 fichiers JS qui sont edit.js et save.js. C’est un peu comme un include en PHP : cela permet de séparer le code en plusieurs fichiers, afin de le garder plus léger.

RegisterBlockType

Vient ensuite la fonction registerBlockType() pour déclarer notre bloc, et qui accepte 2 paramètres :

1. Le nom unique du bloc, qui doit exactement correspondre à celui qu’on a mis dans block.json.
2. Un objet dans lequel on passe plusieurs valeurs pour définir ce bloc.

Pour le moment, il y a 2 fonctions qui vont nous intéresser :

edit

C’est l’un des paramètres les plus importants puisque c’est la méthode (=fonction) qui sera lancée dans l’éditeur pour afficher votre bloc.

Comme on l’a vu, le contenu de cette fonction est délocalisée dans le fichier edit.js dans le but d’alléger le code. On fera souvent appel à cette technique dans la suite du cours, mais il faudra bien penser importer le fichier en haut du code.

Dans le fichier edit.js, il n’y a pas grand chose pour l’instant : on affiche simplement un paragraphe et on peut observer une fonction useBlockProps() (qui est en fait un hook), mais on étudiera ça de plus près dans les prochains cours.

save

Cette méthode est toute aussi importante que la précédente car c’est celle qui va permettre d’enregistrer le HTML de votre bloc dans la base de données.

Là aussi, la fonction est délocalisée dans un fichier à part : save.js.

Pour rappel c’est du HTML qui est enregistré en base par l’éditeur et non pas des données brutes, ou du JSON comme on a pu le voir dans le cours sur le cycle de vie de Gutenberg.

C’est donc ce code qui sera affiché en front, c’est-à-dire sur le site.

Alors on peut se demander pourquoi distinguer le code HTML qui apparaitra dans l’éditeur de celui affiché en front, puisqu’au final on est sensé avoir la même chose.

Eh bien en fait tout simplement parce que dans l’éditeur, on va bientôt ajouter des champs pour nous permettre d’éditer notre contenu : le code du bloc dans l’éditeur sera donc différent du code sauvegardé en base. Donc si je résume :

• Dans Edit, on a le bloc et ses interactions : les champs administrables ainsi que les paramètres personnalisables.
• Et dans save, on a le code HTML définitif, qui sera enregistré en base et retranscrit sur le site.

Paramètres du block.json

On pourrait également déclarer dans cet objet tous les paramètres qu’on a mis dans block.json. L’avantage de les déclarer ici, serait de pouvoir rendre traduisibles les chaines de textes.

Pensez dans ce cas à importer la fonction __() en début de fichier.

Donc si vous faites une extension destinée à être publiée dans le répertoire officiel des extensions de WordPress, privilégiez cette approche.

Astuce : appeler un bloc sans la souris

Avant de continuer, voici une petite astuce bien pratique pour appeler un bloc plus rapidement, et sans utiliser la souris :

Tapez un slash / au début d’un nouveau paragraphe, et vous pourrez alors taper le nom du bloc désiré et Gutenberg vous suggérera des blocs. Naviguez au clavier et validez avec Entrée !

Une fois qu’on connait cette technique, on ne peut s’en passer !

---

Et voilà, notre premier bloc est opérationnel ! Pour l’instant il n’est pas dynamique, ni même joli, mais nous avons la base pour aller ensuite beaucoup plus loin, et c’est le sujet des prochains cours.

En complément de cette formation, n’hésitez pas à consulter la documentation officielle Gutenberg.

Dans le prochain cours on va voir comment personnaliser l’icône du bloc si l’on ne trouve pas notre bonheur avec les Dashicons.