Formation « Créer des blocs avec Gutenberg »

Déclarer un bloc Gutenberg

Lecture : 8 minutes • 2

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-guten-block afin de vous préparer.

Attention

Si vous lisez ce cours avant la sortie officielle de Gutenberg et WordPress 5.0, n'oubliez pas de télécharger l'extension Gutenberg sur le répertoire officiel.

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. Jusqu’ici seul l’éditeur visuel ne permettait pas cette extensibilité.

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

Et même si derrière c’est du React, on n’aura clairement pas l’impression d’en faire.

Comme je le disais dans l’aparté : pas besoin d’être un expert SQL pour récupérer des données WordPress depuis la base puisque l’on a la WP Query. Pour Gutenberg c’est pareil : pas besoin d’être un expert React pour écrire des blocs !

Si vous avez suivi le cours sur Create-Guten-Block, vous avez une structure d’extension prête à l’emploi. On va déclarer notre premier bloc en créant un dossier src/1-block et un fichier index.js à l’intérieur.

Conseil

Pour ceux qui suivent la formation premium, vous retrouverez le code complet dans l'extension Base, dossier src/1-block.

On va maintenant y coller ce code, que l’on va analyser juste après :

JS
1-block/index.js
const { __ } = wp.i18n // Importer la fonction __() d'internationalisation des chaines
const { registerBlockType } = wp.blocks // Importe la fonction registerBlockType() de la librairie globale wp.blocks

// Fonction WordPress pour déclarer un bloc
registerBlockType(
	'capitainewp/block', // Nom du bloc sous forme de slug avec son préfixe (wp est bien sûr réservé)
	{
		title: __( "Premier Bloc"), // Titre du bloc lisible par un humain
		description: __("Mon tout premier bloc Gutenberg"), // Description qui apparait dans l'inspecteur
        icon: 'awards', // Dashicon sans le préfixe 'dashicons-' → https://developer.wordpress.org/resource/dashicons/
		category: 'common', // Catégorie (common, formatting, layout widgets, embed)
		keywords: [ // Mots clés pour améliorer la recherche de blocs
			__( 'test' ),
			__( 'exemple simple' ),
		],

		// La partie affichée dans l'administration de WordPress
		edit: props => {

			return (
				<div className={ props.className }>
					<p>Salut ! Je suis le backend</p>
				</div>
			)
		},

		// La partie enregistrée en base et affichée en front
		save: props => {
			return (
				<div>
					<p>Salut, je suis le frontend</p>
				</div>
			)
		},
	}
)

Les imports

Les deux premières lignes sont 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 wp.i18n, qui nous permettra de rendre nos chaines traduisibles, puis la fonction registerBlockType() de wp.blocks.

Il faut savoir que Gutenberg apporte une variable globale wp qui contient plusieurs objets qui vont nous être utiles tout au long de cette formation : wp.blocks, wp.components, wp.i18n

Si vous êtes curieux, vous pouvez ouvrir la console du navigateur et taper wp dans l’onglet console pour voir tout ce que WordPress fournit :

objet wp console
L’objet WP détaillé dans la console

Si vous avez déjà fait un peu de JS moderne, vous aurez peut-être déjà vu une autre syntaxe d’import :

JS
// Cette syntaxe
import registerBlockType() from wp.blocks
// fait exactement la même chose que
const { registerBlockType } = wp.blocks

Simplement pour la deuxième version, on appelle ça l’appel destructuré. On en a parlé dans le cours sur JSX et ESNext.

On verra que la deuxième écriture est plus pratique pour récupérer plusieurs fonctions d’un objet tel que wp.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
registerBlockType( 'slug-plugin/slug-bloc', { params } ) 

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.

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.

category

La catégorie à laquelle appartient votre bloc. Gutenberg propose par défaut 5 catégories : common, formatting, layout, widgets et embed.

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

catégorie des blocs
Les blocs sont rangés par catégorie

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.

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. A l’intérieur on viendra y 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.

Vous noterez que l’on passe un paramètre props : en React les props sont les propriétés (fonctions, variables) passées au composant par le parent, en l’occurence Gutenberg dans notre cas.

Et on va voir après que ça va nous servir à plusieurs choses, comme par exemple à tester si le bloc est actuellement actif.

Conseil

React mettra automatiquement à jour ce rendu en temps réel si une donnée vient à changer. C'est ce qui fait sa puissance. C'est donc une chose que vous n'aurez pas besoin de vous soucier, contrairement à jQuery.

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.

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.


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 !

Le saviez-vous ?

Le saviez-vous ?

Si vous regardez bien, on écrit tout le code dans les paramètres de la fonction, au lieu d’appeler des fonctions externes comme on l’aurait fait dans d’autres langages comme PHP par exemple.

C’est notamment le cas de edit et save.

En JS vous allez le voir souvent et c’est tout à fait légitime !

Déclarer le bloc dans blocks.js

Avant de tester notre nouveau bloc il ne faut pas oublier de l’importer depuis le fichier commun dans src/blocks.js :

JS
src/blocks.js
import './1-block';

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.

Vérifiez qu’aucune erreur ne s’affiche dans notre console

Et enfin, testons notre bloc dans Gutenberg

Allez c’est le grand moment ! Si tout se passe bien on devrait voir notre bloc dans la liste. Rendez-vous dans l’interface d’administration Articles > Ajouter et utilisons le petit bouton + à gauche pour faire apparaitre la liste des blocs disponibles.

Le bloc est bien listé !

Si vous ne voyez pas le bloc tout de suite, allez dans l’onglet Blocks ou lancez une recherche en tapant soit le nom du bloc, soit l’un des mots-clés définis dans keywords.

Votre bloc va apparaitre mais il n’est pas très sexy pour le moment. S’il y a le moindre souci, ouvrez la console de votre navigateur afin de traquer une très probable erreur JS.

Astuce : appeler un bloc sans la souris

Une petite astuce très pratique qui m’a été donnée par Riad Benguella lors du WordCamp Paris 2018 : pour appeler un bloc sans lâcher le clavier, tapez un slash / au début d’un nouveau paragraphe, 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 !

Pratique non ?

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.

Si vous voulez en savoir plus au sujet de Gutenberg, vous pouvez (si ce n’est déjà fait) acheter la formation complète Gutenberg, ou alors obtenir plus d’informations sur 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.

2

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 ?

Laisser un commentaire