Personnaliser la Toolbar - Formation Gutenberg - Capitaine WP

Formation « Créer des blocs avec Gutenberg »

Exemple • Le bloc alerte : styles et réglages via la Toolbar

Lecture :4 minutes •0

Gutenberg nous offre la possibilité de personnaliser la barre d’outils de l’éditeur RichText afin d’ajouter ses propres boutons et fonctionnalités. Dans ce cours on va créer notre propre composant pour personnaliser l’apparence d’un bloc d’alerte.

Notre exemple

Voici l’exemple que l’on va réaliser aujourd’hui : une boite conseil/avertissement/interdiction colorée afin d’être remarquée plus facilement dans un texte. Ce genre d’alertes sont très pratiques dans les documentations ou lorsque l’on écrit des cours :

Une toolbar personnalisée
Une alerte personnalisable en fonction du contexte

Comme vous pouvez le voir, la Toolbar dispose de 3 boutons supplémentaires pour choisir le type d’alerte.

Vous retrouverez cet exemple dans src/9-toolbar-custom.

Les attributs

Voici le code source de ce bloc. Comme on va le voir, on va faire appel à de nouveaux composants, librairies et concepts intéressants. On commence avec index.js et ses attributs :

JSX
src/9-custom-toolbar/index.js

Valeur par défaut des attributs

Notez que j’ai ajouté également un nouvel attribut nommé type, destiné à stocker le type d’alerte que l’on veut. Les valeurs pourront être advice, warning ou avoid.

Je vais considérer que l’alerte conseil en vert est l’alerte par défaut. Du coup j’applique la valeur default: 'advice' dans l’attribut.

JS

Cet attribut va nous permettre au final de définir la classe CSS à appliquer.

Du côté du CSS

Regardons maintenant du côté du CSS, à commencer par le fichier editor.scss :

Sass
src/9-toolbar-custom/editor.scss

J’ai crée 3 classes spécifiques pour appliquer les couleurs vert, jaune, rouge sur mes Dashicons dans la Toolbar. Par défaut toutes les icônes de la barre d’outils sont noires.

Comme ce sont les mêmes couleurs que je vais appliquer au bloc, je les ai mises sous forme de variables et en commun via un fichier vars.scss stocké dans le dossier du bloc.

Sass
src/9-toolbar-custom/vars.scss

J’utilise la commande Sass @import pour intégrer les styles de mon fichier vars.scss. Les styles de ce fichier seront donc inclus dans le CSS final généré par Webpack.

Je fais de même pour style.scss :

Sass
src/9-toolbar-custom/style.scss

Je crée 3 classes  is-adviceis-warning et is-avoid qui vont me permettre d’appliquer la couleur à mon bloc. Ce sont les mêmes noms que mes valeurs possibles d’attributs.

La commande Sass darken() me permet, à partir d’une couleur, d’obtenir une version plus sombre que j’utilise pour la bordure gauche. Il existe également son inverse lighten().

Les composants de @wordpress/components

Dans edit.js, on charge de nouveaux éléments en provenance de @wordpress.components. Pour rappel cet objet de WordPress vous fournit des composants utiles et réutilisables. On va se servir de :

  • Toolbar : un nouvel espace dans la barre d’outils (avec bordures sur les côtés) ;
  • ToolbarGroup : permet de délimiter mes différents groupes de bouton ;
  • ToolbarButton : un bouton cliquable avec le style de WP accompagné d’un Dashicon ;
  • Tooltip : une infobulle pour ajouter un intitulé à notre bouton.

Voici ce que cela donne visuellement :

Nos composants de la barre d’outils

Ce qu’il faut noter c’est qu’en général quand je parle de la Toolbar, je parle de la barre d’outils complète, mais du point de vue du code elle s’appelle en réalité BlockControls (que l’on importe également en début de fichier). Toolbar fait alors référence à un groupe d’éléments dans la barre d’outils.

Revenons-en au code : pour appliquer une Tooltip il faut la wrapper autour de notre bouton, et pour y mettre une icône on le met à l’intérieur de celui-ci. Ce qui donne une arborescence Toolbar > ToolbarGroup > Tooltip > ToolbarButton.

À chaque fois que vous voulez ajouter un séparateur entre des boutons, fermez et rouvree la balise <ToolbarGroup>.

Enregistrer l’attribut au clic sur un bouton

Pour enregistrer l’attribut, on utilise la technique habituelle sur le onClick() du bouton de la barre d’outils. Mais cette fois j’applique directement et à la main la valeur voulue :

JSX
src/9-toolbar-custom/edit.js

Et j’adapte la valeur à appliquer pour chaque bouton.

Appliquer plusieurs classes et en fonction de conditions

Dans nos boutons de la Toolbar, on va vouloir ajouter notre classe personnelle comme  .capitaine-toolbar-green pour appliquer la couleur verte à mon bouton. Notez que par précaution j’ai commencé le nom de classe par le nom de mon extension. De cette manière j’évite les potentiels conflits.

JSX

Les crochets [ ... ] annoncent une liste JS afin de pouvoir ajouter plusieurs classes CSS.

C’est plus propre que de les écrire dans une chaine de texte concatenée, et en plus je vais pouvoir ajouter des conditions.

C’est justement le cas de la seconde classe : les accolades { ... } vont me permettre de faire un test : j’applique la classe .is-pressed seulement si mon attribut type est bien égal à « advice ». 

Cette classe, fournie par Gutenberg, permet de changer le style du bouton si l’option est sélectionnée.

Et je fais de même avec mes autres boutons pour la valeur « avoid » et « warning ».

Appliquer le style à notre bloc via les blockProps

Et pour terminer, il va falloir appliquer la classe qui définit la couleur du bloc sur celui-ci. Le souci c’est qu’on utilise blockProps qui fournit directement les attributs de la div qui contient le bloc.

Mais on va pouvoir modifier sa valeur. Si vous faites un console.log(blockProps), vous verrez qu’il possède une propriété className. C’est elle qu’on va modifier.

JS
src/9-toolbar-custom/save.js

On va simplement, en amont du return(), ajouter aux props notre classe is-quelque chose, et le tour est joué.

Il faudra bien sûr faire la même chose dans edit.js ainsi que save.js.

Désormais, votre bloc s’adapte en temps réel quand vous changez son style entre advice, warning et avoid. Vous pourriez d’ailleurs rajouter autant de styles que vous le souhaitez.

Conseil

N’oubliez pas l’espace avant le nom de classe, sinon elle finira collée à la classe d’avant et sera mal interprétée.


On a appris pas mal de choses dans ce cours : la valeur d’attribut par défaut, les composants WordPress comme les Tooltip et boutons, et comment appliquer plusieurs classes dynamiquement.

Ce sont des concepts que l’on va réutiliser régulièrement à l’avenir donc retenez-les bien !

Dans le prochain cours on va voir le composant URL, très pratique et prêt-à-l’emploi.

0

Questions, réponses et commentaires

Laisser un commentaire