block_categories_all range vos blocs maison dans une catégorie dédiée

Pourquoi les cinq blocs d’une extension maison se retrouvent-ils dispersés entre la catégorie « Texte » et la catégorie générique « Widgets » dans l’inserteur, plutôt que rassemblés au même endroit ? La réponse tient à un oubli fréquent : chaque bloc a bien reçu une clé category dans sa déclaration, mais cette catégorie n’a jamais été créée, WordPress la remplaçant alors silencieusement par une catégorie existante approchante.

Ce tutoriel détaille, étape par étape, comment créer une catégorie dédiée et y rattacher plusieurs blocs d’une même extension, pour une expérience d’inserteur bien plus claire côté rédacteur.

Étape 1 : déclarer la nouvelle catégorie

Le filtre block_categories_all, introduit avec WordPress 5.8, permet d’ajouter une entrée au tableau des catégories existantes. Chaque catégorie est un tableau associatif avec trois clés : slug, title et icon :

add_filter( 'block_categories_all', function( $categories, $context ) {
    return array_merge(
        $categories,
        [
            [
                'slug'  => 'agence-exemple',
                'title' => 'Blocs Agence Exemple',
                'icon'  => 'building',
            ],
        ]
    );
}, 10, 2 );

Le paramètre icon accepte n’importe quel nom d’icône du jeu dashicons déjà présent dans l’administration WordPress, sans dépendance supplémentaire à charger.

Étape 2 : rattacher un bloc à cette catégorie

Dans le fichier block.json de chaque bloc concerné, la clé category doit correspondre exactement au slug déclaré à l’étape précédente :

{
    "apiVersion": 2,
    "name": "agence-exemple/temoignage",
    "title": "Témoignage",
    "category": "agence-exemple",
    "icon": "format-quote",
    "attributes": {
        "citation": { "type": "string" }
    }
}

Sans cette catégorie déclarée en amont via le filtre, WordPress ignore silencieusement une valeur de category inconnue et bascule le bloc dans la catégorie générique « Blocs formatés », sans aucun message d’avertissement visible dans l’éditeur.

Étape 3 : contrôler l’ordre d’apparition

L’ordre des catégories dans l’inserteur suit l’ordre du tableau retourné par le filtre. Pour positionner sa catégorie personnalisée juste après les catégories natives les plus utilisées plutôt qu’en toute fin de liste, on insère l’entrée à un index précis plutôt que de se contenter d’un array_merge() en fin de tableau :

add_filter( 'block_categories_all', function( $categories, $context ) {
    $nouvelle = [
        'slug'  => 'agence-exemple',
        'title' => 'Blocs Agence Exemple',
        'icon'  => 'building',
    ];

    array_splice( $categories, 2, 0, [ $nouvelle ] );

    return $categories;
}, 10, 2 );

Étape 4 : vérifier le résultat dans l’éditeur

Une fois les deux étapes précédentes en place, ouvrir l’inserteur de blocs doit désormais afficher une section « Blocs Agence Exemple » regroupant l’ensemble des blocs de l’extension, avec l’icône choisie affichée en en-tête de section. Un test avec la recherche de l’inserteur permet aussi de vérifier que les blocs restent trouvables par leur nom, indépendamment de leur catégorie.

Points de vigilance

• Le slug de catégorie doit rester unique sur l’ensemble du site : une collision avec une extension tierce provoquerait un mélange de blocs sans rapport dans la même section.
• Le filtre doit s’exécuter avant le chargement de l’éditeur : un hook init classique, sans priorité particulière, suffit dans la grande majorité des cas.
• Une catégorie sans aucun bloc rattaché n’apparaît simplement pas dans l’inserteur : pas besoin de la retirer conditionnellement.

Un bénéfice concret pour les rédacteurs

Sur un site qui utilise à la fois des blocs natifs, des blocs d’une extension e-commerce et des blocs maison, regrouper ces derniers dans une catégorie clairement identifiée réduit sensiblement le temps de recherche dans l’inserteur, en particulier pour un rédacteur qui découvre l’interface. C’est un détail d’expérience utilisateur souvent négligé au profit de la seule fonctionnalité des blocs eux-mêmes.

Sur toutes nos extensions internes qui comptent plus de deux blocs, une catégorie dédiée fait désormais partie du gabarit de départ, au même titre que le fichier block.json lui-même.

En résumé

Créer une catégorie dédiée demande peu de code, mais améliore sensiblement le confort d’usage de l’inserteur pour toute extension qui compte plusieurs blocs personnalisés. Le filtre block_categories_all reste l’unique point d’entrée pour cette personnalisation, à combiner systématiquement avec la clé category de chaque bloc concerné.