Rétro-compatibilité : gérer la dépréciation de vos blocs Gutenberg

Avec le temps, il se peut que le code HTML ou les attributs de vos blocs varient. Mais voilà, ça va poser un problème à l’éditeur qui ne comprendra plus les blocs déjà insérés. Alors pour éviter cela, on va mettre en place un mécanisme de dépréciation des blocs afin de gérer leur obsolescence !

Sommaire du cours

Le problème lorsque vous modifiez un bloc
Déclarer une dépréciation
Dépréciation due au changement de HTML
Dépréciation due au renommage des attributs
Des fichiers séparés pour chaque dépréciation

Vous savez ce qu’il se passe lorsque l’on change le HTML enregistré en base via la méthode save ? Gutenberg renvoie une erreur sur le bloc qui semble non récupérable.

Et pourtant, avec le temps, on va probablement avoir besoin de modifier et améliorer certains blocs.

Mais du coup, ceux qui auront déjà été insérés avant la modification risquent de générer une erreur d’interprétation de Gutenberg.

Dans ce cours, on va voir comment éviter ce souci via le mécanisme des dépréciations.

Pour ceux qui suivent la formation en formule premium, vous pouvez ouvrir l’exemple /src/17-deprecated du plugin de blocs.

Le problème lorsque vous modifiez un bloc

Si vous modifiez le HTML enregistré d’un bloc sans mettre en place de dépréciation, vous allez avoir des soucis la prochaine fois que vous chargerez dans l’éditeur un contenu contenant ce bloc.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Comme on peut le voir sur la capture, un message d’erreur apparaît à la place du bloc en question :

Un message indique que le bloc contient du contenu invalide ou inattendu et propose une tentative de récupération. — Un bloc qui a du mal à être interprété par Gutenberg

Par curiosité, cliquez sur les 3 points et Résoudre afin de comparer le code reçu et le code attendu :

L’outil de résolution des problèmes de bloc

Dans l’interface, on n’a pas beaucoup d’indices sur le souci rencontré. Mais vous aurez également l’erreur affichée dans la console du navigateur, et là, c’est beaucoup plus compréhensible.

Dans la capture d’écran, on comprend bien que le bloc attend un couple ul > li et il reçoit un couple div > p, d’où l’objet de son désarroi.

Autant ce n’est pas gênant lorsque vous développez vos premiers blocs (car vous pourrez simplement les supprimer et les insérer à nouveau), autant cela va poser un gros souci lorsque vous voudrez mettre à jour le rendu d’un bloc déjà utilisé sur le site.

Déclarer une dépréciation

Alors pour éviter cela, il existe une méthode de dépréciation qui va nous permettre de garder une trace des anciennes versions du bloc et des instructions de migration, afin que l’éditeur ne nous mette plus d’erreur.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Pour nous sortir de ce mauvais pas, on va utiliser la méthode deprecated, que l’on place généralement après edit et save dans le fichier index.js.

JSX

index.js

registerBlockType(metadata.name, {
    edit: Edit,
    save,
	transforms,
    deprecated: [
      	// version N - 1
        {  
            attributes: { … },
            migrate( {} ) { … },
            save( props ) { … },
        },
        
        // version N - 2
        { 
            attributes: { … },
            migrate( {} ) { … },
            save( props ) { … },
        },
        // …
    ]
} )

Notez que c’est un tableau [], car on va pouvoir définir plusieurs migrations dans le temps et ainsi rendre le bloc intemporel.

Avec elle, on va pouvoir traiter 2 cas :

Si le HTML du bloc doit changer dans la méthode save ;
Ou si on souhaite changer le nom des attributs du block.json ;

On va voir comment gérer ces 2 cas dans la suite de ce cours.

Dépréciation due au changement de HTML

Et on va commencer avec le cas où seul le HTML change. Le bloc rendait auparavant un div > p, et désormais il affichera un titre ul > li.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Dans save.js, voici ce que l’on a changé :

JSX

/src/17-deprecated/save.js

import { useBlockProps, RichText } from "@wordpress/block-editor";

export default function save(props) {
	const { attributes } = props;
	const { content } = attributes;
    
	// ❌ Ancienne version
	return (
		<div {…useBlockProps.save()}>
			<RichText.Content tagName="p" value={content} />
        </div>
    )

	// ✅ Nouvelle version
    return (    
		<ul {…useBlockProps.save()}>
			<RichText.Content tagName="li" value={content} />
		</ul>
	);
}

Et du côté du block.json, on a modifié le sélecteur de l’attribut :

JSON

/src/17-deprecated/block.json

// ❌ Ancienne version
"attributes": {
    "content": {
        "type": "string",
        "source": "html",
        "selector": "p"
    }
}

// ✅ Nouvelle version
"attributes": {
    "content": {
        "type": "string",
        "source": "html",
        "selector": "li" // Le sélecteur change
    }
}

Du coup c’est cohérent pour la nouvelle version du bloc. Mais désormais, ce bloc ne saura pas interpréter les anciennes versions du HTML. C’est pour cela qu’il faut mettre en place la dépréciation dont voici le code :

JSX

/src/17-deprecated/index.js

import { registerBlockType } from "@wordpress/blocks";
import { useBlockProps, RichText } from "@wordpress/block-editor";

import "./style.scss";

import metadata from "./block.json";
import Edit from "./edit";
import save from "./save";

registerBlockType(metadata.name, {
	edit: Edit,
	save,
	deprecated: [{
        attributes: {
            content: {
                type: "string",
                source: "html",
                selector: "p",
            },
        },
        save(props) {
            const { attributes } = props;
            const { content } = attributes;

            return (
                <div {…useBlockProps.save()}>
                    <RichText.Content tagName="p" value={content} />
                </div>
            );
        },
    }],
});

Dans deprecated, on peut définir plusieurs informations :

attributes : l’ancienne version des attributs ;
migrate : nécessaire s’il y a un changement d’attribut ;
save : l’ancienne méthode d’enregistrement du HTML.

Dans notre cas, on a uniquement besoin de attributes et save. On aura besoin de migrate dans le prochain exemple.

Alors qu’est-ce qu’on fait ici ? Tout d’abord, on indique à quoi ressemblait l’ancienne version de l’attribut content, surtout au niveau du sélecteur.

Après tout, avant le changement, il était dans un <p> et non pas un <li>.

Dans save, on reporte l’ancienne version du HTML enregistré. C’est là où on est content d’avoir du code versionné !

Du coup, entre l’ancien HTML et l’ancienne définition de l’attribut, Gutenberg sait extraire content d’un bloc désuet. Avec ça, il est capable automatiquement de convertir le bloc avec le nouveau code.

Conseil

Pour plus de simplicité, commencez par écrire la dépréciation avant même d’entamer des modifications sur le bloc originel.

Dépréciation due au renommage des attributs

Maintenant, pour épicer un peu le tout, on va également changer le nom de l’attribut content par item.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Dans la nouvelle version du block.json, on a donc ceci :

JSON

/src/17-deprecated/block.json

// ❌ Ancienne version
"attributes": {
    "content": {
        "type": "string",
        "source": "html",
        "selector": "p"
    }
},
    
// ✅ Nouvelle version
"attributes": {
    "item": { // Le nom de l'attribut change
        "type": "string",
        "source": "html",
        "selector": "li" // En plus du sélecteur
    }
},

Voici du coup comment gérer ce cas au niveau du code :

JSX

/src/17-deprecated/index.js

import { registerBlockType } from "@wordpress/blocks";
import { useBlockProps, RichText } from "@wordpress/block-editor";

import "./style.scss";

import metadata from "./block.json";
import Edit from "./edit";
import save from "./save";

registerBlockType(metadata.name, {
	edit: Edit,
	save,
	deprecated: [{
        attributes: {
            content: {
                type: "string",
                source: "html",
                selector: "p",
            },
        },
        migrate(attributes) {
            const { content } = attributes;
            return {
                item: content,
            };
        },
        save(props) {
            const { attributes } = props;
            const { content } = attributes;

            return (
                <div {…useBlockProps.save()}>
                    <RichText.Content tagName="p" value={content} />
                </div>
            );
        },
    }],
});

Cette fois, on va utiliser toutes les propriétés de deprecated dont migrate.

Dans attributes, on récupère toujours l’ancienne version de l’attribut, avec son ancien nom content et son ancien sélecteur p.

Dans save, c’est toujours la même chose : on récupère l’ancienne version du code et les anciens attributs.

Le problème, c’est que le bloc ne peut pas savoir que content devient item dans la nouvelle version. Il va falloir migrer l’ancienne valeur vers la nouvelle.

C’est à ça que sert la fonction migrate : on va récupérer les anciens attributs afin de les assigner aux nouveaux. C’est pour cela qu’on assigne content (l’ancien attribut) à item (le nouvel attribut).

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

Conseil

Le principe de dépréciation est très simple : les versions dépréciées possèdent les anciens attributs, l’ancien HTML et éventuellement une fonction de migration des données si elles ont changé de nom. Gutenberg s’occupe du reste.

Des fichiers séparés pour chaque dépréciation

Afin de conserver un code propre et lisible, on peut déporter nos dépréciations dans des fichiers JS à part, comme on a appris à le faire pour la méthode edit et la méthode save ou plus récemment avec les transformations de blocs.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Mais on ne va pas faire un seul fichier pour toutes les versions antérieures. À la place, je vous propose de créer un fichier pour chaque version de bloc.

En reprenant notre exemple, on peut écrire ceci :

JSX

/src/17-deprecated/index.js

import { registerBlockType } from "@wordpress/blocks";

import "./style.scss";

import Edit from "./edit";
import save from "./save";
import metadata from "./block.json";

import v1 from "./v1"; // On importe les précédentes versions
import v2 from "./v2"; // Une version après l'autre
import v3 from "./v3"; // Et ainsi de suite…

registerBlockType(metadata.name, {
	edit: Edit,
	save,
	deprecated: [v3, v2, v1], // Et on les liste ici
});

Dans cet exemple, on importe les 3 précédentes versions du bloc, ce qui veut dire qu’on en est aujourd’hui à la quatrième version.

Les dépréciations sont exécutées dans l’ordre de leur déclaration. Du coup, il est en général judicieux de mettre les versions les plus récentes en début de liste.

Avec cette approche, on peut directement lister ces versions dans deprecated du fichier index.js grâce au tableau [].

Voici ce que ça donne avec notre dépréciation dans v1.js :

JSX

/src/17-deprecated/index.js

import { useBlockProps, RichText } from "@wordpress/block-editor";

const v1 = {
	attributes: {
		content: {
			type: "string",
			source: "html",
			selector: "p",
		},
	},
	migrate(attributes) {
		const { content } = attributes;
		return {
			item: content,
		};
	},
	save(props) {
		const { attributes } = props;
		const { content } = attributes;

		return (
			<div {…useBlockProps.save()}>
				<RichText.Content tagName="p" value={content} />
			</div>
		);
	},
};

export default v1;

On déclare ici simplement un objet dans une constante, que l’on exporte ensuite afin de pouvoir l’importer dans index.js.

De cette manière, index.js restera toujours simple à lire. Et on aura bien séparé les différentes méthodes et responsabilités du bloc dans des fichiers distincts.

Conseil

Pour un code plus clair, écrivez toujours les dépréciations dans des fichiers séparés.

Vous pouvez aller encore plus loin avec les dépréciations. Il est également possible de modifier les supports et manipuler les InnerBlocks grâce à elles. Si vous avez ces besoins, consultez la documentation WordPress :

InnerBlocks et dépréciations

Ce concept de dépréciation 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à utilisés par vos utilisateurs.

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

Dans le prochain cours, on va voir comment traduire nos blocs grâce aux outils d’internationalisation (i18n).