Ajouter des réglages dans la Toolbar

Par défaut la Toolbar ne propose que le gras, l’italique, et le lien. On va donc ajouter un peu plus d’options avec notamment l’alignement.

Sommaire du cours

La Toolbar et l’Inspecteur d’un bloc
1. Le rôle du Fragment
Ajouter des réglages dans la Toolbar
1. Import de nouveaux composants
2. Ajouter un attribut pour gérer l’alignement

Ce cours est l’occasion idéale pour nous de voir comment ajouter de nouveaux réglages dans la Toolbar de notre bloc. Mais avant de se jeter dans le code, voici un peu de théorie.

Et dans ce cours on va voir comment ajouter le composant d’alignement de texte afin d’obtenir ceci :

La barre d'outil avec les options d'alignement — Nous allons ajouter les options d’alignement dans la Toolbar

C’est un composant qui existe déjà dans WordPress et que l’on va réutiliser. Un peu plus tard dans la formation, on verra également comment ajouter des réglages dans l’inspecteur en créant nos propres composants. La logique restera la même pour les deux d’ailleurs.

Jusqu’à maintenant notre return renvoyait le rendu HTML du bloc à Gutenberg. Mais en fait on peut au total interagir sur 3 choses :

Le bloc ;
Sa Toolbar juste au dessus ;
Et l’inspecteur à droite.

Le Bloc, la Toolbar et l'Inspecteur dans l'interface de Gutenberg — Les éléments sur lesquels vous pouvez intéragir

On va voir comment injecter des composants dans notre Toolbar.

Dans le return de notre edit.js, on va utiliser les composants correspondants, qui joueront le rôle de portails vers ces zones hors de notre composant.

JSX

edit.js

import { Fragment } from '@wordpress/element'

export default function Edit( props ) {
    return (
        <Fragment>

            // La toolbar
            <BlockControls> 
            </BlockControls>

            // L'inspecteur
            <InspectorControls>
            </InspectorControls>

            // Le bloc
            <div { …blockProps }>
                <RichText />
            </div>

        </Fragment>
    )
}

Ça peut paraitre fou, mais c’est totalement possible avec React !

Le rôle du Fragment

Vous avez vu que j’ai ajouté un composant <Fragment> dans mon return.

Le problème c’est que dans le return d’un composant, vous n’avez pas le droit d’enchainer des éléments HTML adjacents (= de même niveau). React veut absolument que vous ayez un bloc parent pour contenir tout ça. Sinon il y aura une erreur à la compilation.

L’erreur « Adjacent JSX elements must be wrapped in an enclosing tag »

Mais ici le bloc de l’inspecteur et de la toolbar ne vont pas être affichés réellement au même endroit que notre composant et ajouter une <div> parente n’aurait alors aucun sens.

Depuis React 16 le composant <Fragment> nous permet de contenir provisoirement plusieurs éléments adjacents. WordPress nous permet de l’utiliser via une petite surcouche de Gutenberg, d’où la nécessité de l’importer au début du code.

JSX

import { Fragment } from '@wordpress/element'

Au final ce bloc ne va pas générer de HTML supplémentaire, mais permet à React de bien délimiter les zones d’affichage et les composants concernés.

Conseil

On va donc utiliser le Fragment dès lors que l’on va utiliser la Toolbar et ou l’inspecteur en complément du code du bloc.

Et cette histoire de fragments sera également valable à l’intérieur des opérateurs ternaires { condition ? ( html ) : ( autre ) } ou des enchainements si / alors { condition && ( html ) }.

Pour la suite de ce cours, on ira voir dans l’exemple 7 : RichText Alignment de notre plugin de blocs (disponible sur Github).

Jetons un oeil à edit.js :

JSX

src-/7-richtext-alignment/edit.js

import { __ } from '@wordpress/i18n'
import {
	useBlockProps,
	RichText,
	AlignmentToolbar, // On charge la Toolbar
	BlockControls, // Et les options d'alignement supplémentaires
} from '@wordpress/block-editor'
import { Fragment } from '@wordpress/element'

import './editor.scss'

export default function Edit( props ) {
	const blockProps = useBlockProps();

	return (
		<Fragment>

			<BlockControls>
				<AlignmentToolbar
					value={ props.attributes.alignment }
					onChange={ alignment => props.setAttributes( { alignment } ) }
				/>
			</BlockControls>

			<div { …blockProps }>
				<RichText
					tagName="div"
					multiline="p"
					placeholder={ __( 'Write your content here', 'capitainewp-gut-bases' ) }
					value={ props.attributes.content }
					className="content"
					onChange={ content => props.setAttributes( { content } ) }
					style={ { textAlign: props.attributes.alignment } }
				/>
			</div>

		</Fragment>
	)
}

Import de nouveaux composants

En premier lieu on voit que l’on importe désormais BlockControls, qui est notre toolbar, et AlignementToolbar, qui est le bloc d’alignement (gauche, centre, droite).

Et donc dans ce cas, on va devoir renvoyer 3 données différentes. Comme on l’a vu précédemment, on va envoyer le tout d’un seul bloc dans le rendu. Gutenberg saura ensuite quoi en faire.

Alors dans cet exemple le code du composant et de la toolbar restent relativement simples, mais lorsque l’on ajoute beaucoup d’HTML, avec des conditions du type props.isSelected, ça peut vite devenir dur à lire.

Je vous montrerai donc à terme comment séparer le tout en plusieurs sous-composants dans des fichiers séparés pour alléger notre code.

Ajouter un attribut pour gérer l’alignement

Maintenant il nous faut enregistrer cette valeur d’alignement quelque part dans notre composant ainsi que mettre à jour le style CSS en fonction de l’options choisie.

Pour stocker cette donnée, on va ajouter un attribut alignment de type stringdans nos attributes. Et on ne met rien d’autre !

JSON

src/7-richtext-alignment/block.json

attributes: {
    content: {
        type: 'string',
        source: 'html',
        selector: '.content'
    },
    alignment: { // On ajoute un attribut alignment
        type: 'string', // Pas de sélecteur par contre
    },
},

En l’absence de sélecteur défini, Gutenberg comprend alors que c’est une donnée qu’il ne trouvera pas dans le HTML, il va donc alors la stocker sous forme d’un objet JS dans le commentaire :

HTML

<!– wp:capitainewp/richtext-toolbar {"alignment":"right"} –>
<div class="wp-block-capitainewp-richtext-alignment">
    <div class="content" style="text-align:right">
        <p><strong>Coucou</strong> je suis un bloc</p>
    </div>
</div>
<!– /wp:capitainewp/richtext-toolbar –>

Oui, c’est bien le {"alignment":"right"} situé à la fin du commentaire de la première ligne, après le nom du bloc. ! Alors forcément, ça a fait s’arracher les cheveux à certains développeurs mais en réalité c’est pas si bête.

Le saviez-vous ?

Ce serait trop compliqué de récupérer le style directement dans le HTML. Dans ce cas c’est simple car il n’y a qu’un seul style, notre alignement. Mais à terme il pourrait y avoir plusieurs styles appliqués, et du coup l’éditeur ne saurait pas lequel récupérer pour notre valeur alignement.

C’est pour cela qu’on va stocker la donnée directement en base et pas dans le HTML.

Rappelez-vous que ce HTML généré est la seule et unique source de vérité, enregistrée en base. Si besoin retournez faire un petit tour dans le cours sur le cycle de vie de Gutenberg, où j’en parlais initialement.

On va notamment se servir de cette technique quand on fera des blocs dynamiques, qui ne génèrent pas tout de suite du HTML mais conservent juste par exemple l’ID d’un article à afficher. On reviendra sur ce point bien assez vite.

De retour dans edit.js, on peut observer qu’on assigne la valeur d’alignment sur l’attribut onChange de notre composant <AlignmentToolbar />.

JSX

src/7-richtext-alignment/edit.js

<AlignmentToolbar
	value={ props.attributes.alignment }
	onChange={ alignment => props.setAttributes( { alignment } ) }
/>

Maintenant il faut bien penser à appliquer le style à la fois sur notre RichText, mais aussi dans save :

JSX

// Dans edit
<RichText
    tagName="div"
	multiline="p"
    …
    style={ { textAlign: props.attributes.alignment } }
/>

// Dans save
<RichText.Content
	tagName="div"
	…
	style={ { textAlign: props.attributes.alignment } }
/>

La présence d’une double accolade n’est pas anodine :

La première accolade affiche une valeur JS dans mon template HTML ;
Et la seconde fait référence à un vrai objet JS avec des clés-valeurs.

Et enfin dans notre objet on utilise le nommage JS de la propriété CSS : text-aligndevient donc textAlign. Ce n’est pas nouveau en fait, c’est un truc aussi vieux que le JS mais on n’avait pas vraiment l’occasion de l’utiliser jusque là, surtout avec jQuery et sa fonction css().

Et voilà. Vous venez d’ajouter votre premier composant de réglages dans la Toolbar. On va bientôt voir que c’est la même chose pour l’inspecteur.

À partir de là, on va pouvoir ajouter tous pleins de réglages à nos blocs et ils vont commencer à devenir vraiment intéressants.

Dans le prochain cours, on va voir comment bien gérer les styles CSS au sein de nos blocs.

Questions, réponses et commentaires

Julien Lavie

Le 22 juin 2021

Hello, tout d’abord merci pour toutes les informations que tu partage, c’est une mine d’or.
J’ai pu commencer à créer des blocs assez complexes.
Mais je suis confronté à un problème.
Sur un bloc personnalisé Pré formaté avec se gestion de grille, je veux ajouter plusieurs richtext différents.
La personne qui va gérer le contenu me demande de pouvoir gérer les options sur chacun des richtext indépendamment.
Comment peut on ajouter un AlignmentToolbar différent pour chaque richtext ?

Merci beaucoup

Répondre
1. Maxime BJ
  
  Le 23 juin 2021
  
  Salut julien. En effet la barre d’alignement s’applique sur le bloc en entier. Une solution serait de faire un bloc conteneur dans lequel l’utilisateur pourra ajouter lui-même des blocs titres, paragraphes… et choisir pour chacun d’entre-eux l’alignement. Tu peux voir le cours sur les InnerBlocks.
  
  Répondre

Laisser un commentaire Annuler la réponse

La Toolbar et l’Inspecteur d’un bloc

Le rôle du Fragment

Import de nouveaux composants

Ajouter un attribut pour gérer l’alignement