# Enregistrer une catégorie de bloc personnalisée dans l’inserteur

> Une agence qui accumule des blocs maison mélangés aux catégories natives gagne à regrouper ses blocs dans une catégorie dédiée, avec filtre et icône propres.

- Auteur : Clément Hadrot
- Publié le : 2024-10-29
- Mis à jour le : 2024-10-29
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/categorie-bloc-personnalisee-inserteur/

## L’essentiel

- block_categories_all pour ajouter une catégorie côté serveur
- Une icône SVG dédiée pour la repérer d'un coup d'œil
- Assigner category dans block.json, rien de plus

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>'
),
```

> L'essentiel à retenir : block_categories_all pour ajouter une catégorie côté serveur ; Une icône SVG dédiée pour la repérer d'un coup d'œil ; Assigner category dans block.json, rien de plus

## É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 `slug` de 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.