{ attributes.libelle }
; }, }, ]; ``` ## La fonction migrate pour convertir les anciennes valeurs Une entrée `deprecated` peut aller plus loin qu'une simple compatibilité d'affichage, grâce à une fonction `migrate` qui convertit les anciens attributs vers le nouveau schéma, de façon à ce que le contenu ancien profite lui aussi, une fois converti, des nouvelles fonctionnalités du bloc : ``` const deprecated = [ { attributes: { libelle: { type: 'string', source: 'html', selector: 'p', }, }, migrate( attributes ) { return { titre: attributes.libelle, description: '', }; }, save( { attributes } ) { return{ attributes.libelle }
; }, }, ]; ``` > L'essentiel à retenir : Chaque entrée deprecated décrit un ancien schéma d'attributs et son ancien save ; WordPress teste les entrées dans l'ordre jusqu'à trouver une correspondance valide ; Une fonction migrate peut convertir automatiquement les anciens attributs vers les nouveaux Une fois la correspondance trouvée et la migration appliquée, WordPress réenregistre automatiquement le bloc avec le `save` actuel, dès la prochaine sauvegarde de l'article concerné, sans intervention manuelle de l'utilisateur. ## L'ordre des entrées, un détail qui compte WordPress teste les entrées du tableau `deprecated` dans l'ordre où elles apparaissent, la plus récente étant conventionnellement placée en premier. Cet ordre a une importance réelle sur un bloc qui a connu plusieurs migrations successives : placer une ancienne entrée avant une plus récente peut, dans de rares cas de chevauchement de structure, faire correspondre le contenu à la mauvaise version. ### Quand aucune entrée ne correspond Si aucune entrée du tableau `deprecated`, ni le `save` actuel, ne parvient à reproduire le HTML enregistré, WordPress affiche le bloc en état invalide, avec une proposition de récupération ou de conversion en HTML brut. C'est le signal qu'une entrée `deprecated` manque, ou que sa condition `isEligible` optionnelle ne couvre pas correctement le cas rencontré. - Toujours ajouter une entrée `deprecated` avant de modifier le `save` d'un bloc déjà utilisé en production. - Tester la migration sur un contenu réel exporté du site concerné, pas seulement sur un exemple minimal. - Vérifier que la fonction `migrate`, si présente, couvre bien tous les champs de l'ancien schéma, y compris ceux laissés vides. > Un conseil qui évite bien des messages d'erreur en production : ne jamais supprimer une entrée `deprecated` tant qu'un contenu publié peut encore s'appuyer sur elle, même des années après son ajout. ## En résumé Le tableau `deprecated` transforme une modification potentiellement destructrice du `save` d'un bloc en une évolution transparente pour l'utilisateur final, à condition de documenter fidèlement chaque ancienne structure et, si nécessaire, de fournir une fonction `migrate` qui convertit les anciens attributs vers le nouveau schéma. Négliger cette étape expose directement le contenu existant à un état invalide dès la prochaine modification du bloc.