Kaolin maintient une trentaine de blocs maison répartis sur ses différents projets clients. Sans organisation particulière, ces blocs se dispersaient dans les catégories natives « Texte » ou « Widgets » de l’inserteur, noyés parmi les blocs de cœur. Un rédacteur cherchant le bloc « bandeau promotionnel » devait faire défiler une longue liste avant de le repérer.
La solution est simple et ne nécessite aucun JavaScript : une catégorie de bloc personnalisée, enregistrée côté PHP, dans laquelle chaque bloc maison s’assigne via une seule ligne de son block.json.
Étape 1 : déclarer la catégorie avec block_categories_all
Le filtre block_categories_all (qui a remplacé block_categories pour prendre en compte le contexte de l’éditeur) permet d’ajouter une entrée à la liste des catégories affichées dans l’inserteur :
add_filter( 'block_categories_all', function ( $categories ) {
return array_merge(
[
[
'slug' => 'kaolin-blocs-maison',
'title' => __( 'Blocs Kaolin', 'kaolin-blocs' ),
'icon' => 'admin-tools',
],
],
$categories
);
} );Placer le tableau de la nouvelle catégorie avant $categories dans array_merge la fait apparaître en tête de l’inserteur, ce qui facilite son repérage immédiat par les rédacteurs habitués.
Étape 2 : une icône SVG dédiée plutôt qu’un dashicon générique
L’icône admin-tools utilisée ci-dessus est un dashicon générique, suffisant pour démarrer, mais une icône SVG propre à l’agence rend la catégorie plus immédiatement identifiable. Le paramètre icon accepte un élément SVG construit avec wp.blocks.registerBlockCollection ou directement un composant d’icône si la catégorie est déclarée côté JavaScript, mais pour une déclaration purement PHP comme ici, il est plus simple de fournir un identifiant de dashicon ou une chaîne SVG encodée :
'icon' => 'data:image/svg+xml;base64,' . base64_encode(
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 4h16v16H4z"/></svg>'
),
Étape 3 : assigner chaque bloc à la catégorie
Chaque bloc maison doit ensuite simplement référencer le slug de la catégorie dans son block.json, sans aucune autre modification :
{
"apiVersion": 3,
"name": "kaolin/bandeau-promo",
"title": "Bandeau promotionnel",
"category": "kaolin-blocs-maison",
"icon": "megaphone"
}Aucun changement côté JavaScript n’est nécessaire : la catégorie déclarée en PHP est immédiatement disponible pour être référencée par sa clé slug dans n’importe quel block.json, y compris ceux de plugins tiers si l’agence souhaite regrouper également des blocs d’extensions dans cette même catégorie.
Étape 4 : vérifier l’ordre d’affichage
L’ordre des catégories dans l’inserteur suit l’ordre du tableau retourné par le filtre. Pour une agence qui gère plusieurs catégories personnalisées (par exemple une par client, en plus d’une catégorie générale « Blocs Kaolin »), il est utile de documenter cet ordre dans le README du plugin, pour que la prochaine personne qui ajoute une catégorie sache où l’insérer sans perturber l’organisation existante.
- Une seule catégorie suffit pour la majorité des agences ; en multiplier les entrées finit par recréer le problème initial de dispersion.
- Le
slugde catégorie doit être unique et préfixé, comme pour un nom de bloc, afin d’éviter tout conflit avec une extension tierce. - Vérifier le rendu de l’icône dans l’inserteur avant de déployer, un SVG mal formé s’affiche silencieusement comme une icône vide.
Ce que ce mécanisme ne couvre pas
Les catégories de motifs (patterns) reposent sur un mécanisme entièrement différent, register_block_pattern_category, avec sa propre logique d’affichage dans l’onglet Motifs de l’inserteur. Confondre les deux mène à des catégories qui n’apparaissent jamais là où on les attend.
Une catégorie de blocs bien nommée est le premier geste de rangement qu’une agence peut offrir à ses rédacteurs.
En résumé
Avec un seul filtre PHP et une ligne de block.json par bloc, Kaolin a regroupé sa trentaine de blocs maison dans une catégorie unique, immédiatement reconnaissable en haut de l’inserteur, sans écrire la moindre ligne de JavaScript supplémentaire.
