Formation « Créer des blocs avec Gutenberg »

Déclarer un bloc Gutenberg avec registerBlockType

Lecture : 7 minutes • 9

Dans ce cours nous allons déclarer notre premier bloc Gutenberg, qui certes ne fera pas grand chose mais qui par la suite nous ouvrira la voie vers de nombreuses possibilités !

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éecrire, 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.

Aparté: Les surcouches WordPress

Un petit mot sur les surcouches de WordPress.

Prenons l’exemple de la WP Query, cette classe qui permet d’aller récupérer n’importe quel contenu de votre site grâce à des centaines de critères différents, et ce dans le but d’éviter de faire des requêtes SQL dans la base lorsque vous créez votre thème.

Eh bien là c’est pareil pour les blocs : la fonction registerBlockType() est une surcouche WordPress au dessus de React pour vous permettre de déclarer facilement et rapidement un bloc.

Ces surcouches sont d’ailleurs en premier lieu utilisées par le coeur du CMS lui-même : la WP Query est utilisée par WordPress pour récupérer le contenu de la page à afficher, et les blocs natifs de Gutenberg sont déclarés via la fonction registerBlockType() également.

Déclarer un bloc Gutenberg

Allez c’est parti ! Vous allez voir que de 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.

JSON
1-block/block.json

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 /.

JSON

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.

Slug

Définition

Le slug est un nom unique donné à une ressource WordPress (une page, un article, une catégorie…) et généré à partir de son titre. le slug doit pouvoir être utilisé dans l’URL du site, par conséquent il ne conserve ni espace (remplacés par des tirets), ni accents, ni caractères spéciaux.

Traduction : Identifiant

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.

Notre premier bloc Gutenberg accompagné de son titre et sa description (en anglais pour le moment).
Le titre et la description de notre bloc apparaissent bien

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 :

Le bloc apparait bien dans la catégorie widgets
Notre bloc est bien listé dans la catégorie Widgets

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

PHP
capitaine-gut-bases.php

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 :

Les blocs WooCommerce sont regroupés dans une seule catégorie
La catégorie de blocs WooCommerce

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 :

Notre premier bloc est trouvé lors d'une recherche sur le mot premier.
Je peux maintenant trouver mon bloc grâce aux mots-clés

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.

JSX
src/index.js

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.
JSX

Pour le moment, il y a 2 fonctions qui vous 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.

JSX
1-block/edit.js

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.

JSX
1-block/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.

JSX
1-block/index.js

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 !

Notre bloc apparait en suggestion si l'on tape /premier directement dans un nouveau paragraphe.

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.

9

Questions, réponses et commentaires

  1. sebastien

    Le 22 avril 2018

    Hello, Je ne sais pas si je suis le seul mais, la recherche via les keywords ne fonctionne pas chez moi 🙁

    1. Maxime BJ

      Le 23 avril 2018

      Alors j’ai remarqué qu’il ne prenait pas en compte les accents (un e ne cherchera pas un é par exemple). C’est peut-être ça le problème ?

  2. webmaster.abcom

    Le 22 mai 2020

    Hello, j’ai pu utiliser le blocka avant d’ajouter l’import dans blcoks.js…
    Étrange non ?

    1. Maxime BJ

      Le 22 mai 2020

      Oui car si tu ne fais pas l’import, il n’y a aucune chance que ton script termine dans le fichier compilé du coup.

  3. Hugo

    Le 18 mai 2021

    Hello !
    Est-ce qu’il y a eu des mises à jours ? Mon fichier src/index.js a beaucoup changé depuis votre cours
    Merci 😉

    1. Maxime BJ

      Le 18 mai 2021

      Possible, le projet Gutenberg évolue très (trop ?) rapidement. Mais tu devrais tout de même retrouver ce que j’indique dans le cours, c’est la base pour déclarer un bloc.

      1. Hugo

        Le 18 mai 2021

        J’ai en effet retrouvé les éléments, ils sont séparés entre le dossier src, et maintenant le block.json. Et c’est dans ce fichier json à la racine que sont indiqué le nom, le title, etc …

  4. Phil

    Le 19 février 2022

    Hello,
    Mon bloc nouvellement créé fonctionne bien. Cependant, quand je créé le dossier pour mon bloc dans le src en prévision de créer plusieurs bloc, plus rien ne fonctionne. J’ai pourtant bien laisser un index.js à la racine du src avec l’import vers le dossier de mon bloc. Je remarque que si je n’ai pas d’erreur à la compilation, il n’y a aucun fichier index.js dans le dossier build. Une idée ?

    1. Maxime BJ

      Le 21 février 2022

      WordPress a changé plusieurs fois la manière de faire. Il faut que je mette à jour ce cours prochainement. En attendant, regarde du côté de la documentation officielle en passant par la méthode du block.json : https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/ ça devrait te débloquer.

Laisser un commentaire