Un développeur freelance avait livré une extension de dix blocs à une agence partenaire, persuadé que le travail était terminé une fois registerBlockType appelé pour chacun. Trois semaines plus tard, retour de terrain : les rédacteurs n’utilisaient que deux des dix blocs, ceux qui portaient une icône reconnaissable. Les huit autres, tous fonctionnellement corrects, restaient invisibles derrière l’icône générique par défaut, un simple bloc gris sans signe distinctif au milieu de dizaines d’options proposées par le thème et les extensions installées.
Cette anecdote illustre un point souvent sous-estimé : la qualité technique d’un bloc ne suffit pas à garantir son adoption. Trois propriétés de block.json, rarement documentées avec le même soin que les attributs ou le rendu, déterminent en grande partie si un bloc se fait remarquer dans l’inserteur ou s’y noie : icon, example et keywords.
icon : la première impression
La propriété icon accepte soit le nom d’un Dashicon existant (comme megaphone ou chart-bar), soit un objet décrivant un SVG complet avec sa couleur de premier plan et d’arrière-plan. Pour une identité visuelle cohérente, mieux vaut fournir un SVG dédié plutôt que de piocher parmi les Dashicons génériques, souvent déjà utilisés par des dizaines d’autres blocs sur un même site.
{
"icon": {
"src": "<svg viewBox='0 0 24 24'>...</svg>",
"foreground": "#2563eb",
"background": "#eff6ff"
}
}example : l’aperçu qui rassure
La propriété example définit un jeu d’attributs fictif utilisé pour générer un aperçu visuel au survol du bloc dans l’inserteur, avant même de l’insérer dans le contenu. Sans cette propriété, l’inserteur affiche soit un aperçu vide, soit rien du tout selon la nature du bloc, ce qui n’aide pas un rédacteur pressé à deviner à quoi ressemblera le résultat final.
{
"example": {
"attributes": {
"titre": "Offre de printemps",
"texteBouton": "En profiter"
}
}
}Un bloc dynamique dont le rendu dépend entièrement de render_callback peut aussi bénéficier d’example : l’aperçu appelle le même callback PHP avec les attributs fictifs fournis, ce qui donne un rendu fidèle plutôt qu’un espace vide.
keywords : la recherche qui pardonne
La barre de recherche de l’inserteur ne se limite pas au titre du bloc : elle interroge aussi le tableau keywords déclaré dans block.json. Un rédacteur qui tape « avis client » ne trouvera jamais un bloc nommé « Témoignage » si ce mot-clé n’a pas été explicitement ajouté à la liste, même si le sens est évident pour un humain.
{
"title": "Témoignage",
"keywords": [ "avis", "citation", "client", "review" ]
}- Trois à cinq mots-clés suffisent généralement, au-delà le gain de découvrabilité devient marginal.
- Les synonymes du métier du client comptent souvent plus que les termes techniques WordPress.
- Un mot-clé traduit dans
textdomainprofite aussi aux sites multilingues.
Un cas concret avant/après
Sur le projet de l’agence évoquée en introduction, l’ajout rétroactif de ces trois propriétés aux huit blocs délaissés a suffi à inverser la tendance en quelques semaines, sans aucune modification du rendu ni des attributs existants. Le tableau suivant résume l’effet observé sur l’utilisation déclarée par les rédacteurs lors d’un point de suivi mensuel.
| Propriété ajoutée | Effet observé |
|---|---|
| Icône SVG dédiée | Bloc repéré au premier coup d’œil dans la grille |
| example renseigné | Moins d’insertions annulées juste après ajout |
| keywords métier | Bloc trouvé via la recherche sans connaître son nom exact |
Ce que ces propriétés ne remplacent pas
Soigner ces trois propriétés n’a d’effet que si le nom et la description du bloc restent clairs par ailleurs : un titre vague comme « Section » ou « Module » continuera de se perdre parmi les autres, quelle que soit la qualité de son icône. De la même façon, un bloc mal catégorisé via la propriété category reste rangé dans un onglet que personne ne consulte, indépendamment de sa fiche.
Traitez la fiche d’un bloc comme une fiche produit, pas comme un détail technique : un rédacteur choisit un bloc sur ce qu’il voit et ce qu’il tape, jamais sur la qualité de votre code PHP.
Notre verdict
Ces trois propriétés ne demandent que quelques minutes à renseigner une fois le bloc fonctionnel, pour un gain d’adoption largement disproportionné par rapport à l’effort. Sur tout projet livré à des rédacteurs non techniques, elles devraient faire partie de la checklist de recette au même titre que la validation des attributs ou le test du rendu front, plutôt que d’être reléguées à un futur hypothétique passage de polish.
