add_filter( 'admin_body_class', ... ) : ce filtre existe depuis longtemps dans le cœur de WordPress, mais reste nettement moins connu que son équivalent public body_class, alors qu’il rend le même service côté écran d’administration. Il permet d’ajouter une classe CSS à la balise <body> de l’interface d’administration, sans surcharger un fichier du cœur ni dupliquer une feuille de style entière pour un seul cas particulier.
La différence la plus importante avec body_class tient à la nature de la valeur manipulée : ce dernier travaille sur un tableau de classes, tandis qu’admin_body_class reçoit et retourne une simple chaîne de caractères, déjà partiellement composée par WordPress. Cette différence de type est la source la plus fréquente d’erreur chez qui découvre ce filtre en pensant pouvoir y ajouter directement un élément de tableau.
Comment WordPress construit cette chaîne de classes
Sur chaque écran d’administration, WordPress compose une chaîne de classes qui reflète le contexte courant : l’identifiant de l’écran, le type de contenu affiché le cas échéant, la locale, ou encore le fait que la barre d’outils soit repliée. Cette chaîne passe ensuite par le filtre admin_body_class, juste avant d’être injectée dans l’attribut class de la balise <body> du gabarit d’administration.
Ajouter une classe selon le type de contenu affiché
La fonction get_current_screen(), appelée depuis le filtre, renseigne le type de contenu concerné via sa propriété post_type. Un site qui gère un type de contenu rapport-audit peut ainsi cibler uniquement les écrans qui s’y rapportent :
add_filter( 'admin_body_class', function ( $classes ) {
$ecran = get_current_screen();
if ( $ecran && 'rapport-audit' === $ecran->post_type ) {
$classes .= ' agence-ecran-rapport-audit ';
}
return $classes;
} );
Cibler un rôle plutôt qu’un type de contenu
La même mécanique s’applique à un rôle utilisateur plutôt qu’à un écran précis, utile par exemple pour appliquer une palette de couleurs distincte aux comptes disposant d’un accès restreint :
add_filter( 'admin_body_class', function ( $classes ) {
$utilisateur = wp_get_current_user();
if ( in_array( 'contributeur_externe', (array) $utilisateur->roles, true ) ) {
$classes .= ' agence-role-contributeur-externe ';
}
return $classes;
} );Un fichier CSS chargé uniquement dans l’administration, via admin_enqueue_scripts, peut ensuite cibler cette classe directement : body.agence-role-contributeur-externe #adminmenu { background: #2c3338; }, sans jamais avoir besoin de modifier un gabarit du cœur.
Le piège de l’espace manquant
La chaîne reçue par le filtre se termine déjà par un espace, et la classe ajoutée doit elle aussi être entourée d’espaces avant d’être concaténée. Omettre cet espace fusionne silencieusement deux classes en une seule chaîne invalide, comme toplevel_page_reglagesagence-role-contributeur-externe, qu’aucun sélecteur CSS ne peut plus cibler correctement :
- Toujours concaténer avec un espace de part et d’autre de la classe ajoutée, jamais une simple juxtaposition de chaînes.
- Vérifier le résultat directement dans l’inspecteur du navigateur, sur la balise
<body>de l’écran concerné, avant de chercher une erreur côté feuille de style. - Ne jamais retourner autre chose qu’une chaîne : un tableau ou une valeur nulle casse l’affichage de tous les écrans d’administration suivants.
Sur nos projets, la vérification systématique après un ajout à
admin_body_classconsiste à ouvrir l’inspecteur du navigateur et à chercher la classe attendue, entourée de ses espaces, avant même d’ouvrir le fichier CSS.
Composer plusieurs filtres sans effacer les autres
Comme pour tout filtre, plusieurs extensions peuvent accrocher chacune leur propre fonction sur admin_body_class, WordPress les exécutant dans l’ordre de leur priorité. Retourner systématiquement la chaîne reçue, enrichie plutôt que remplacée, évite d’effacer une classe déjà ajoutée par une extension exécutée plus tôt dans la chaîne de filtres.
En résumé
admin_body_class permet de cibler précisément un écran, un type de contenu ou un rôle d’utilisateur en CSS d’administration, sans toucher à un fichier du cœur ni charger une feuille de style pour l’ensemble de l’interface. Sa seule contrainte réelle tient à sa nature de chaîne plutôt que de tableau : chaque classe ajoutée doit être entourée d’espaces pour rester exploitable par un sélecteur CSS.
