Formation « Créer des blocs avec Gutenberg »

Gérer la dépréciation de vos blocs

Lecture : 3 minutes • 0

Que se passe-t’il lorsque l’on change le HTML de la méthode save ? Gutenberg renvoie une erreur sur le bloc qui semble non récupérable. Afin d’éviter cela, on peut définir une migration pour convertir les blocs dépréciés.

Le problème lorsque vous changez le HTML

Si vous modifiez le rendu HTML d’un bloc dans sa méthode save, la prochaine fois que vous chargerez un article comprenant ce bloc, vous ferez face à cette erreur :

un bloc qui a été modifié

Cliquez sur Solutionner afin de comparer le code reçu et le code attendu :

Solutionner un bloc cassé

Vous aurez également l’erreur dans la console mais c’est beaucoup moins lisible :

Le code attendu par Gutenberg face au code obtenu

Autant ce n’est pas gênant lorsque vous développez vos premiers blocs, autant cela va poser un gros souci lorsque vous voudrez mettre à jour le rendu d’un bloc déjà utilisé maintes fois par les rédacteurs du site.

Pour cela il existe une méthode de dépréciation qui va nous permettre de garder une trace des anciens attributs, afin que l’éditeur ne nous mette pas une erreur.

D’après le handbook Gutenberg, les développeurs ont pensé à tout, heureusement pour nous !

On va utiliser la méthode deprecated, que l’on place généralement après edit et save, pour nous sortir de ce mauvais pas.

Cas n°1 : Dépréciation du bloc lors d’un changement de HTML

Prenons le cas le plus simple : ici seul le HTML change. Le bloc rendait auparavant un <p>, et désormais il affichera un titre <h2>.

Voici le code de la dépréciation :

JSX
index.js

Le but ici est de définir les éventuels changement d’attributs et HTML dans la méthode save. Tout ce qui se trouve dans la méthode deprecated concerne l’ancienne version de notre bloc.

Les attributs restent les mêmes, du coup au lieu de les redéfinir, je vais les déclarer en amont dans une constante (après tout j’ai le droit) et je les appelle dans le bloc, et dans la dépréciation. De cette manière j’évite une répétition et je reste DRY (Don’t Repeat Yourself).

Le seul changement est dans deprecated / save : j’indique l’ancienne version, qui comprenait le paragraphe à la place du bloc. Notez que la class content n’a pas changé.

Cas n°2 : Dépréciation des attributs

Maintenant, pour épicer un peu le tout, on va changer le nom d’un attribut. Imaginons que l’on veuille renommer l’attribut text par content.

Voyons comment gérer ce cas au niveau du code :

JSX

Bon déjà cette fois, comme les attributs sont différents, on ne les met plus en commun.

Dans la nouvelle version du bloc, l’attribut s’appelle content. Dans le deprecated, il s’appelait text.

On voit aussi dans deprecated une méthode migrate qui permet de faire la conversion. Ici on dit que si le bloc a reçu l’ancien HTML, il prend la valeur de text et l’enregistre dans la nouvelle version content.

Et le tour est joué !

Au final c’est plutôt facile de gérer la dépréciation des blocs, et c’est tant mieux. Cela permet de penser sereinement au futur sans casser le passé.

Gérer plusieurs dépréciations

Un bloc vit avec le temps, et risque d’évoluer à plusieurs reprises. Si vous avez remarqué, notre deprecated est une liste (un tableau non associatif en JS), du coup il indique que l’on peut mettre plusieurs objets dépréciation à l’intérieur.

JSX
index.js

Envoyer la dépréciation dans un fichier séparé

Afin de conserver un code propre et lisible, on peut déporter nos dépréciations dans un fichier JS à part, comme on a appris à le faire pour la méthode edit et la méthode save.

En reprenant l’exemple du cas n°1, on obtiendrait ceci :

JSX
index.js

Et on ajouterait un fichier deprecated.js qui contiendra la, ou les dépréciations :

JSX
index.js

Et c’est d’ailleurs dans le cas où on a plusieurs dépréciations qu’il devient impératif de séparer les fichiers. De cette manière, index.js restera simple à lire. Et on a bien séparé les différentes méthodes et responsabilités du bloc dans des fichiers distincts.


En tous cas ce concept est hyper important, puisque sans lui vous ne pouvez pas modifier le rendu d’un bloc ou un attribut sans casser la compatibilité des blocs déjà écrits par vos utilisateurs.

Ne leur donnons donc pas une raison de pousser une gueulante !

Si vous souhaitez en savoir plus sur les dépréciation, la documentation officielle est aujourd’hui bien fournie.

0

Questions, réponses et commentaires

Laisser un commentaire