Étude de cas : migrer son extension vers Gutenberg

Retour d’expérience d’une migration d’une extension (avec metabox) vers Gutenberg.

DisclaimerZ

Bien sûr c’est une vision personnelle !

Nous sommes encore entre la phase 1 et la phase 2 de Gutenberg, d’après ce qu’à annoncé ce week-end Matt Mullenweg au WordCamp US, une phase 3 et une phase 4 sont mêmes en préparation (gros level up en perspective).

À l’heure où j’écris je n’ai pas forcément terminé totalement cette migration (80%) car je m’interroge sur les différentes façons de découper en composants et organiser le code en JSX, je tatonne aussi sur la présentation des instructions. J’ai voulu éviter l’écueil de la précipitation pour coller au calendrier de la sortie de WordPress 5.

Remarque : on peut aussi voir ça autrement => je n’étais tout simplement pas prêt pour cette sortie 🙂 mais enfin je n’ai ni choisi ni voté pour ce calendrier.

Contexte

Je maintiens une petite extension sur WordPress.org qui permet de paramétrer finement ses twitter cards, j’ai souhaité travailler sur cette extension car elle a un nombre suffisant d’installations actives (+ 10000) et comporte quelques “réglages avancés” comme une page d’options ainsi qu’une métabox.

La traduction était importante, déjà de manière générale, mais le plugin est de plus dispo en anglais, français, espagnol et catalan.

“Difficultés” d’entrée de jeu

  • l’historique ! des métadonnées existantes à conserver (postmeta)
  • une métabox existante
  • un affichage sélectif suivant les types de contenu (CPT)
  • niveau React débutant, JavaScript intermédiaire

Objectifs de cette refonte – migration

  • Gutenberg comme une opportunité d’améliorer l’expérience
  • fixer des bugs
  • avoir une VRAIE prévisualisation dans le BO de la card Twitter
  • ajouter des instructions, tutoriels pour faciliter la mise en place notamment avec Gut.

Cheminement et étapes

Au cours de cette migration, pas mal d’erreurs, de changements, de corrections de trajectoire. Les branches GIT sont là pour ça 🙂

Un conseil tout de même : l’approche RTFM dans ce billet. Non pas qu’on ne puisse pas faire de blocs Gutenberg sans connaître React mais c’est tout de même mieux, en particulier si vous souhaitez aller au-delà du bloc de base.

Voici les étapes que j’ai connues :

Warning ! vulgarités en approche 🙂

  1. bidouillages avec les composants Gutenberg
  2. premiers blocs d’exemple avec ma collection gutextra
  3. tentative d’application à mon plugin existant
  4. sauf que ça marche pas, “ragequit” 🙂
  5. re-tentative
  6. re “ragequit” 🙂
  7. re-re-tentative, un bloc fonctionnel ! wouhou
  8. les données s’affichent dans le contenu 🙁
  9. ah mais oui Riad en parle dans son billet, on peut sauvegarder en postmeta
  10. ça y est j’ai mon bloc, putain ça marche pas
  11. ah mais oui il faut déclarer les postmeta avec register_meta()
  12. wouhou le bloc fonctionne, les anciennes données sont conservées et éditables
  13. mais putain, ça veut pas marcher avec les custom post types (CPT) (҂` ロ ´)凸
  14. ah en fait c’est pas Gutenberg c’est la REST API
  15. si le CPT a pas le support pour la REST (show in rest à true) c’est mort
  16. si pas de support “custom-fields” dans mon cas c’est mort aussi (҂` ロ ´)凸
  17. bon je force l’ajout des supports, ah mais le RGPD, ah non en fait ce sont des metadonnées publiques (affichées dans la section head), #osef
  18. ça y est tout a l’air de coller, ah en fait non faudrait que le bloc s’affiche d’emblée quand on arrive sur un nouveau post ou qu’on en édite un (~ metabox)
  19. impasse ! au final ce que je veux faire c’est pas du tout un bloc, c’est totalement hors post content. Mauvaise approche !
wasted penguin GIF

Solutions et choix techniques

Quand l’utilisateur arrivait sur son écran d’édit je m’étais débrouillé pour qu’il ait ça :

mais du coup ça ne marchait pas avec les posts existants et pour cause, car pas conçu pour ça. De plus, il fallait d’abord cliquer sur le bloc pour voir apparaître les réglages à droite :

Impasse donc et pas hyper pratique même quand ça marchait. Envahissant dans une autre perspective : la zone Gutenberg (phase 1) concerne le post content, le plugin de card s’occupe de métadonnées. Ça n’avait pas trop de sens d’aller taper dans la zone de contenu même si désormais les données du bloc étaient enregistrées en postmeta.

Du coup il fallait une autre approche et j’ai abouti sur les custom sidebars. Alors attention je ne parle pas des widgets ici mais des sidebars au sens Gutenberg :

Cette solution m’a paru mieux adaptée :

  1. laisser la métabox telle quelle (et donc au final ne pas se prendre la tête avec toute cette migration) était hors de propos
  2. une sidebar dédiée permettrait de grouper tous les réglages 
  3. l’icône la rendrait accessible à tout moment sans pour autant parasiter l’affichage et donc la création du plus important : le contenu !

Re-souci

Bon, l’approche semblait déjà meilleure, si vous souhaitez voir le code c’est ici.

Mais re-souci donc, j’avais mis tous mes réglages ainsi que la preview dans une sidebar, le rendu était médiocre, la preview de la card était compressée à droite de l’écran :

ça tombait à l’eau. Heureusement, il y a plein de composants pratiques dont la modale. Plutôt que d’aller s’enfermer à droite, autant proposer un bouton qui ouvre une popup et à l’intérieur pouvoir paramétrer et visualiser le rendu potentiel :

Tout ça pour ça ?!

À l’heure où j’écris la version 5 (avec Gutenberg) de WordPress est sortie, j’attends encore de voir ce que je peux améliorer avant de pousser une version majeure. De toute façon tout le monde tatonne.

Au moins là, il y a des sections bien distinctes entre réglages généraux, réglages de l’image et preview ce qui était l’objectif et surtout je ne pollue pas la zone de contenu avec un bloc qui n’a rien à y faire.

Rester compatible avec le classic

Evidemment, une bonne part ne va pas migrer tout de suite vers WordPress 5 donc autant rester compatible avec l’éditeur classique. 

J’ai opté pour une approche incitative : plus de fonctionnalités si tu passes à Gutenberg, sinon l’existant perdure et la mise à jour t’apporte au moins quelques bugfix.

Tips gut

Quelques gists qui pourraient vous servir notamment pour la traduction :

Récupérer l’objet featured image

https://gist.github.com/jmau111/8bba5c7191201cc4d8439e3d1c4274ea

i18n et Gutenberg

https://gist.github.com/jmau111/fc2daad404aa332a2b89ba935cb2249b

Conclusion

Gutenberg demande un peu de temps mais qui ne sera pas perdu. C’est un investissement. Formez-vous ! De bonnes ressources sont à disposition, notamment dans la communauté FR, et pour tous les niveaux et besoins.

Soyez persévérant(e)s ! J’ai bien conscience que tout le monde n’a pas le temps, d’ailleurs je ne l’avais pas vraiment non plus. On peut trouver de l’aide, notamment de Riad Benguella sur le slack fr qui répond à nos questions de newbies.

Cependant on peut s’enthousiasmer pour Gutenberg tout en ayant en tête les sujets problématiques, d’ailleurs en guise de synthèse je vous recommande l’article du Smashing (de très grande qualité).

Gutenberg représente plus que jamais une série d’opportunités : progresser dans des nouveaux langages et technos mais surtout s’interroger sur les interfaces qu’on propose et chercher à les améliorer.

Autrement dit, rejeter en bloc l’idée de Gutenberg de même qu’ignorer les interrogations et réticences exprimées, parfois vivement, par les acteurs de l’écosystème et les premiers testeurs conduirait à une impasse.

Gutenberg est là, dans le core WordPress 5, il va falloir composer avec pour le meilleur comme pour le pire, j’ai confiance en cet écosystème pour s’adapter et les prochaines phases annoncées au WordCamp US sont assez rassurantes.

Réagir

J'utilise un système de commentaires un peu expérimental basé sur les issues GitHub. Il suffit d'autoriser l'application Utteranc sur votre compte GitHub.

Remarque : si vous n'êtes pas d'accord pour donner cette autorisation, il est possible de commenter directement sur GitHub. Rendez-vous alors sur les issues de https://github.com/jmau111/julien-maury.com. Elles sont titrées avec l'URL du billet ;)