Formation « Créer des blocs avec Gutenberg »

Déclarer un bloc Gutenberg avec registerBlockType

Lecture : 7 minutes • 4

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 !

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.

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

Déclarer un bloc Gutenberg est vraiment très facile, car WordPress a tout prévu pour nous simplifier la tâche. Une fonction registerBlockType() va nous permettre de déclarer tout le nécessaire sous forme de paramètres.

Si vous 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.

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 __() de la librairie @wordpress/i18n, qui nous permettra de rendre nos chaines traduisibles, puis la fonction registerBlockType() de @wordpress/blocks.

RegisterBlockType

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

  1. Le nom unique du bloc,  que l’on appelle slug (sans caractères spéciaux ou espace)
  2. Un objet dans lequel on passe plusieurs valeurs pour définir ce bloc. Certaines sont obligatoires et d’autres optionnelles.
JS

Concernant le slug, il est composé de 2 parties : le nom de l’extension (ou du thème) suivi du nom du bloc, et séparés par un slash /.

Il doit être absolument unique parmi tous les blocs présents sur votre site. C’est pour cela que l’on met aussi le slug du plugin en amont, pour ne pas créer de conflit avec un bloc natif ou d’une autre extension qui porterait le même nom.

Pour les prochains blocs, j’utiliserais le nommage suivant :

JS

Ils auront donc tous la même base Capitaine, unique à ce plugin. Mais cela va changer la classe CSS générée pour le bloc, dont il faudra également changer les noms de classes. Mais on reviendra sur le sujet un peu plus tard.

J’en profite pour vous remettre la définition d’un slug :

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

Les paramètres

Le deuxième paramètre de la fonction registerPostType() est un objet qui va contenir plusieurs valeurs.

title

Le titre sera affiché dans l’interface de choix de bloc et donc lu par un humain. On utilise ici la fonction __() pour permettre d’internationaliser le texte et donc rendre votre bloc traduisible dans d’autres langues.

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 vous servir des Dashicons ou bien insérer votre propre SVG, et c’est 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 (en anglais pour le moment) et l’icône à 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 5 catégories : text, media, layout, widgets 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

keywords

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

En JS la liste entre crochets [ ... ] est l’équivalent PHP des tableaux simples (non associatifs), contrairement aux objets JS entre accolades { ... } qui peuvent eux posséder des associations clé – valeur.

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.

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.

Afin d’alléger le code, cette fonction est délocalisée dans un autre fichier edit.js. On fera souvent ça pour garder un code plus léger et plus facile à lire, mais il faudra bien penser à ajouter import Edit from ‘./edit.js’ en haut du fichier.

Dans la fonction Edit on pourra à terme placer d’autres fonctions pour le traitement de nos données ainsi que le rendu HTML via la fonction return() qui se positionne toujours en dernier.

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 en 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, et c’est pour cela que l’on a bien une distinction back / front.

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.

apiVersion

Enfin, Gutenberg évoluant rapidement, l’API développeur change. Depuis WordPress 5.6, une nouvelle version a été proposée, la V2. C’est celle qu’on va utiliser pour avoir accès à la syntaxe la plus récente (et la plus pratique) pour créer nos blocs.


Voici pour les bases de la création de blocs ! Il nous manque encore quelques éléments 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 !

Préparer le code pour d’autres blocs

Create-bloc nous fourni une structure pour un seul bloc. Mais nous, on va vouloir en faire pleins d’autres.

On ne va pas forcément faire une extension par bloc, car ce serait multiplier les requêtes HTTP pour les scripts et styles.

Donc on va procéder à quelques changements dans la structure de notre dossier src.

La nouvelle arborescence de nos fichiers avec un dossier par bloc.
On va ranger nos blocs dans des sous-dossiers de src

On va passer tous les fichiers de notre bloc dans un nouveau sous-dossier src/1-block. À l’avenir, chaque nouveau bloc aura son propre dossier.

Mais du coup il faut tout de même conserver src/index.js, qui servira désormais à appeler nos différents blocs :

JS
src/index.js

Pas besoin d’indiquer ./1-block/index.js dans vos appels, Webpack comprendra qu’en l’absence de nom, c’est un fichier index qu’il devra importer.

Conseil

N’oubliez pas de mettre à jour ce fichier lorsque vous ajoutez un nouveau bloc, et contrôlez bien votre ligne de commande pour vous assurer qu’aucune erreur de compilation n’a été trouvée.

On va vérifier qu’avec ces changements, la compilation continue de bien fonctionner. Jetez tout de même un oeil au terminal pour contrôler qu’aucune erreur en rouge n’est apparue :

Le terminal ne devrait pas indiquer d'erreur après les changements effectués dans l'arborescence des fichiers
Aucune erreur, c’est que tout va bien !

Télécharger les exemples de la formation

Tout au long de la formation, vous pourrez suivre mes exemples sans avoir à tout réecrire, en vous basant sur mon répertoire Github :

Télécharger l’extension

Pensez à faire un npm install et npm start afin que tout fonctionne.

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.

4

Questions, réponses et commentaires

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

  2. 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 ?

Laisser un commentaire