Gérer la dépréciation de vos blocs • Formation WordPress Capitaine WP

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.

Sommaire du cours

Le problème lorsque vous changez le HTML
Cas n°1 : Dépréciation du bloc lors d’un changement de HTML
Cas n°2 : Dépréciation des attributs
Gérer plusieurs dépréciations
Envoyer la dépréciation dans un fichier séparé

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 :

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

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

import { useBlockProps } from '@wordpress/block-editor'

// On centralise les attributs si ce sont les mêmes entre 2 version du bloc
const attributes = {
    title: {
        type: 'string',
      	source: 'text',
      	selector: 'title',
    }
};

registerBlockType( 'capitainewp/depreciation', {
	attributes, // Définis au dessus
    edit: Edit,
    save( props ) { // Nouvelle version avec un h2
        return ( 
            <div {…useBlockProps.save()}>
            	<h2>{ props.attributes.title }</h2>
            </div>
        )
    }, 
    deprecated: [ // Ancienne version 
        {
            attributes: attributes, // On conserve les mêmes attributs

            save( props ) { // Ce qui était enregistré avant
                return (
                    <div {…useBlockProps.save()}>
                    	<p className="title">{ props.attributes.title }</p>
                    </div>
                )
            },
        }
    ]
} );

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

registerBlockType( 'gutenberg/block-with-deprecated-version', {

    //  title, description, keywords …
    attributes: {
        content: { // le nouveau nom
            type: 'string',
      		source: 'text',
      		selector: 'content',
        }
    },
    
    edit: Edit,

    save( props ) {
        return (
			<div {…blockProps.save() }>
    			<div className="content">{ props.attributes.content }</div>
            </div>
        )
    },

    deprecated: [
        {
            attributes: {
                text: { // L'ancien nom
                    type: 'string',
      				source: 'text',
      				selector: 'text',
                }
            },

            migrate( { text } ) { // La fonction permettant de migrer text vers content
                return {
                    content: text
                };
            },

            save( props ) { // L'ancien HTML
                return (
                    <div {…blockProps.save() }>
                    	<p className="text">{ props.attributes.text }</p>
                    </div>
                )
            },
        }
    ]
} )

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

registerBlockType( 'gutenberg/block-with-deprecated-version', {

    attributes: {
        content: { // le nouveau nom
            type: 'string',
      		source: 'text',
      		selector: 'content',
        }
    },
    
    edit: Edit,

    save( props ) {
        const { content } = props.attributes
        return (
			<div { …blockProps.save() }>
    			<div className="content">{content}</div>
            </div>
        )
    },

    deprecated: [
      	// version N - 1
        {  
            attributes: { … },
            migrate( {} ) { return … },
            save( props ) { return … },
        },
        
        // version N - 2
        { 
            attributes: { … },
            migrate( {} ) { return … },
            save( props ) { return … },
        }
        // …
    ]
} )

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

import { registerBlockType } from '@wordpress/blocks'

import Edit from './edit'
import Save from './save'
import deprecated from './deprecated' // On importe le fichier deprecated.js

registerBlockType( 'capitainewp/depreciation', {
	attributes: {
        title: {
            type: 'string',
            source: 'text',
            selector: 'title',
        }
	},
	edit: Edit,
	save,
	deprecated // On appelle la dépréciation ici
})

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

JSX

index.js

import { useBlockProps } from '@wordpress/block-editor'

const deprecated = [
	// Version N - 1
    { 
		attributes: {
			title: {
                type: 'string',
                source: 'text',
                selector: 'title',
            }
		},
		save( props ) {
			const { title } = props.attributes

			return (
				<div {…useBlockProps.save()}>
                	<p className="title">{title}</p>
                </div>
			)
		},
	}
	// Version N - 2 …
]

export default deprecated

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.