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

> Pourquoi vos blocs personnalisés se retrouvent-ils noyés dans la catégorie générique « Blocs formatés » ? Une catégorie dédiée les regroupe en quelques lignes de PHP.

- Auteur : WordPress Développement
- Publié le : 2022-01-17
- Mis à jour le : 2022-01-17
- Catégorie : Blocs Gutenberg
- URL : https://www.wpmoderne.fr/blocs/block-categories-all-categorie-dediee-blocs-maison/

## L’essentiel

- register_block_type accepte une clé category dès la déclaration
- Une catégorie inexistante doit d'abord être ajoutée via block_categories_all
- L'ordre des catégories retournées influence leur position dans l'inserteur

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

> L'essentiel à retenir : register_block_type accepte une clé category dès la déclaration ; Une catégorie inexistante doit d'abord être ajoutée via block_categories_all ; L'ordre des catégories retournées influence leur position dans l'inserteur

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é.