Les champs standard de WordPress suffisent jusqu’à votre premier projet sur mesure. Dès que vous devez afficher des caractéristiques produit sur une fiche, ajouter une galerie à une page ou insérer un bloc de conditions de livraison, vous vous heurtez aux limites de l’éditeur: titre, texte, catégories, point final.

Il existe une solution, et ce n’est pas ACF Pro à 149 $ par an. Les boîtes méta personnalisées ajoutent des champs arbitraires directement dans l’interface d’édition d’un article, sans constructeur visuel et sans une dizaine de modules superflus. CMB2 fait exactement cela: il fournit une API PHP pour décrire des boîtes méta dans du code qui réside dans le contrôle de version, pas dans la base de données.

Voici le flux de travail complet: de l’installation du plugin à l’affichage des données en front. À la fin de cet article, vous disposerez d’un fichier de boîte méta fonctionnel qui s’adapte à tout type de contenu, des pages aux produits WooCommerce.

💡 Aperçu rapide:

• Installez CMB2 depuis le répertoire WordPress.org: le plugin est gratuit et s’installe en deux clics.
• Créez un fichier metaboxes.php dans le dossier de votre thème et décrivez les champs requis via le hook cmb2_admin_init.
• Incluez le fichier dans functions.php avec une simple ligne require_once et vérifiez la boîte méta dans le panneau d’administration.
• Affichez les données sauvegardées en front via get_post_meta() avec un échappement approprié.

Qu’est-ce que CMB2: du code plutôt qu’un constructeur visuel

CMB2 est une bibliothèque pour développeurs qui crée des boîtes méta, des champs personnalisés et des formulaires dans WordPress. Par défaut, elle prend en charge des dizaines de types de champs: texte, éditeur WYSIWYG, téléchargement de fichier, sélecteur de date, sélecteur de couleur, boutons radio, listes déroulantes, répéteurs et groupes.

La principale différence avec ACF: CMB2 n’a pas de constructeur visuel. Toutes les boîtes méta sont décrites dans des fichiers PHP au sein de votre thème. Pour les développeurs, c’est un avantage: la configuration réside dans Git, elle ne peut pas être supprimée accidentellement via le panneau d’administration, et la migration entre la préproduction et la production se résume à un déploiement de code. Parallèlement, CMB2 est entièrement gratuit, tandis qu’ACF Pro vous coûtera environ 149 $ par an pour les champs répétables et les groupes.

La bibliothèque est activement maintenue depuis 2014. Sur WordPress.org, le plugin affiche une note de 5 étoiles et plus de 300 000 installations actives. Le dépôt GitHub reçoit des mises à jour régulières: la dernière version a traité la compatibilité avec PHP 8.4 et WordPress 6.7. Ce n’est pas un projet abandonné qui sera délaissé dans six mois.

Étape 1: Installer le plugin

Allez dans Extensions → Ajouter, tapez «CMB2» dans la zone de recherche et cliquez sur «Installer». Après l’activation, le plugin charge son moteur mais ne modifie rien par lui-même dans le panneau d’administration: les boîtes méta n’apparaîtront qu’après que vous les aurez décrites dans le code.

Si vous incluez CMB2 manuellement dans votre thème sans l’installer via le panneau d’administration, ajoutez ce qui suit au début de functions.php:

1
require_once __DIR__ . '/cmb2/init.php';

Deux points importants. Premièrement: init.php doit se charger le plus tôt possible, en dehors de tout hook. Ne l’enveloppez pas dans une vérification if ( ! class_exists(...; CMB2 gère lui-même les conflits de chargement en double. Deuxièmement: avec une inclusion manuelle, vous devrez mettre à jour CMB2 manuellement, contrairement aux mises à jour automatiques via le panneau d’administration.

Étape 2: Écrire le fichier de boîte méta

Créez un dossier cmb2-metaboxes à la racine de votre thème enfant et un fichier metaboxes.php à l’intérieur. Ce fichier contiendra toutes vos définitions de champs.

Voici un code fonctionnel qui ajoute un éditeur de texte, une description courte et un sélecteur de badge aux produits WooCommerce. Copiez-le dans metaboxes.php:

1
add_action( 'cmb2_admin_init', 'sdstudio_register_metaboxes' );
2
 
3
function sdstudio_register_metaboxes() {
4
 
5
    $prefix = '_sdstudio_';
6
 
7
    $cmb = new_cmb2_box( array(
8
        'id'           => 'product_extra_info',
9
        'title'        => __( 'Дополнительная информация о товаре', 'cmb2' ),
10
        'object_types' => array( 'product' ),
11
        'context'      => 'normal',
12
        'priority'     => 'high',
13
        'show_names'   => true,
14
    ) );
15
 
16
    $cmb->add_field( array(
17
        'name'    => __( 'Описание для карусели на главной', 'cmb2' ),
18
        'desc'    => __( 'Текст, который будет показан в слайдере товаров.', 'cmb2' ),
19
        'id'      => $prefix . 'carousel_desc',
20
        'type'    => 'wysiwyg',
21
        'options' => array(
22
            'textarea_rows' => 5,
23
        ),
24
    ) );
25
 
26
    $cmb->add_field( array(
27
        'name' => __( 'Короткое описание', 'cmb2' ),
28
        'desc' => __( 'Одна строка — для карточки товара в сетке.', 'cmb2' ),
29
        'id'   => $prefix . 'short_desc',
30
        'type' => 'textarea_small',
31
    ) );
32
 
33
    $cmb->add_field( array(
34
        'name' => __( 'Бейдж товара', 'cmb2' ),
35
        'desc' => __( 'Метка «Новинка», «Хит» или «Распродажа».', 'cmb2' ),
36
        'id'   => $prefix . 'badge',
37
        'type' => 'select',
38
        'show_option_none' => true,
39
        'options'          => array(
40
            'new'   => __( 'Новинка', 'cmb2' ),
41
            'hit'   => __( 'Хит', 'cmb2' ),
42
            'sale'  => __( 'Распродажа', 'cmb2' ),
43
        ),
44
    ) );
45
 
46
}

Voici ce qui se passe: le hook cmb2_admin_init se déclenche au chargement du panneau d’administration et enregistre la boîte méta sur la page d’édition de produit. new_cmb2_box() crée un conteneur avec le titre «Informations produit supplémentaires», et trois appels à add_field() y ajoutent des champs: un éditeur WYSIWYG, un champ texte compact et une liste déroulante avec des options prédéfinies. Chaque champ reçoit un id unique avec le préfixe _sdstudio_ pour éviter les conflits avec d’autres plugins.

Si vous avez besoin de pages standard au lieu de WooCommerce, remplacez 'object_types' => array( 'product' ) par 'object_types' => array( 'page' ). Pour plusieurs types de contenu, listez-les: array( 'page', 'post' ).

Pour la liste complète des types de champs, consultez la documentation officielle de CMB2 sur GitHub. Des dizaines d’options sont disponibles par défaut: du simple texte et des éditeurs WYSIWYG aux téléchargements de fichiers, sélecteurs de couleur, boutons radio et taxonomies. Choisissez le type adapté à votre tâche spécifique en vous basant sur la documentation, pas sur des suppositions.

Étape 3: L’inclure dans functions.php

Vous devez maintenant charger le fichier que vous avez créé. Ouvrez functions.php dans votre thème enfant et ajoutez une seule ligne avant la balise fermante ?>, ou à la fin du fichier s’il n’y a pas de balise fermante:

1
require_once __DIR__ . '/cmb2-metaboxes/metaboxes.php';

Avant d’ajouter le code, sauvegardez functions.php. Une erreur de syntaxe dans require_once plantera le site avec une erreur PHP fatale, et vous ne pourrez restaurer le fichier que via FTP ou le panneau de votre hébergeur. Après avoir sauvegardé, ouvrez n’importe quel produit dans le panneau d’administration et vérifiez que la boîte méta «Informations produit supplémentaires» apparaît sous l’éditeur de contenu.

Remplissez les champs de test et cliquez sur «Mettre à jour». CMB2 sauvegarde automatiquement les données dans la table wp_postmeta. Aucun appel supplémentaire au hook save_post n’est requis: la bibliothèque intercepte la sauvegarde de l’article et traite ses champs elle-même.

Étape 4: Afficher les données en front

Les données sont sauvegardées dans la base de données; vous devez maintenant les montrer aux visiteurs. Ouvrez le fichier de thème responsable de la page produit, généralement single-product.php ou content-single-product.php. Ajoutez le code à l’intérieur de la boucle WordPress:

1
<?php
2
$carousel_desc = get_post_meta( get_the_ID(), '_sdstudio_carousel_desc', true );
3
$badge         = get_post_meta( get_the_ID(), '_sdstudio_badge', true );
4
 
5
if ( ! empty( $carousel_desc ) ) : ?>
6
    <div class="product-carousel-desc">
7
        <?php echo wp_kses_post( $carousel_desc ); ?>
8
    </div>
9
<?php endif; ?>
10
 
11
<?php if ( ! empty( $badge ) ) : ?>
12
    <span class="product-badge product-badge--<?php echo esc_attr( $badge ); ?>">
13
        <?php echo esc_html( $badge ); ?>
14
    </span>
15
<?php endif; ?>
16

Détail: get_post_meta() récupère la valeur par l’ID du champ. Pour un champ WYSIWYG, utilisez wp_kses_post(), qui autorise les balises HTML permises et filtre celles potentiellement dangereuses. Pour un texte simple ou une liste de sélection, esc_html() suffit: elle convertit les caractères spéciaux en entités HTML et prévient les failles XSS.

Si la boîte méta est créée pour des pages ('object_types' => array( 'page' )), placez ce même code dans page.php ou content-page.php. Le mécanisme est le même: get_post_meta() à l’intérieur de la boucle, échappement selon le type de champ.

Vidéo: CMB2 de l’installation à une boîte méta fonctionnelle

Dans ce tutoriel de 20 minutes, l’auteur parcourt le flux de travail complet: installation, création de champs, inclusion de fichier et affichage des données en front. Utile à regarder si les instructions textuelles ont laissé des zones d’ombre.

⁉️🤔 Foire aux questions

En quoi CMB2 diffère-t-il d’ACF?

ACF fournit un constructeur de champs visuel directement dans le panneau d’administration: vous pouvez assembler une boîte méta sans écrire une seule ligne de code. CMB2 exige de décrire les champs dans des fichiers PHP au sein de votre thème. Pour les développeurs qui stockent la configuration dans Git, CMB2 est plus pratique: les boîtes méta ne dépendent pas de l’état de la base de données, elles ne peuvent pas être supprimées accidentellement via le panneau d’administration, et la migration entre la préproduction et la production se résume à un déploiement de code. ACF Pro coûte à partir de 149 $ par an pour les champs répétables et les groupes; CMB2 est gratuit.

Peut-on utiliser CMB2 sans installer le plugin?

Oui. Copiez le dossier CMB2 dans votre thème et incluez init.php dans functions.php, comme indiqué à l’étape 1. Cette approche est pratique pour les thèmes premium qui doivent fonctionner immédiatement après l’activation sans exiger que l’utilisateur installe un plugin tiers. L’inconvénient: vous devrez mettre à jour CMB2 manuellement à chaque nouvelle version.

Les champs CMB2 fonctionnent-ils dans l’éditeur Gutenberg?

Oui, les boîtes méta CMB2 s’affichent sous l’éditeur Gutenberg de la manière habituelle, dans la section située sous le contenu. Cependant, par défaut, elles ne s’intègrent pas dans les blocs de l’éditeur. Si vous avez besoin d’intégrer un champ directement dans un bloc, un développement supplémentaire via l’API CMB2 et register_block_type() sera nécessaire.

Que faire si la boîte méta n’apparaît pas dans le panneau d’administration?

Vérifiez trois choses. Premièrement: est-ce que object_types correspond au type de contenu en cours d’édition? Pour les produits WooCommerce, il faut 'product', pas 'post'. Deuxièmement: y a-t-il une erreur de syntaxe PHP? Activez WP_DEBUG dans wp-config.php et consultez le journal. Troisièmement: le préfixe de l’id du champ entre-t-il en conflit avec un autre plugin? Utilisez un préfixe unique comme _sdstudio_.

Puis-je créer des groupes de champs répétables?

Oui. CMB2 prend en charge les champs répétables via le drapeau 'repeatable' => true et les groupes répétables via $cmb->add_group_field(). Un groupe vous permet d’ajouter un bloc «Caractéristique: valeur» et de créer de nouvelles instances avec un bouton «Ajouter une ligne» directement dans le panneau d’administration.

CMB2 fonctionne-t-il avec le multisite?

Oui, le plugin est entièrement compatible avec WordPress Multisite. Les boîtes méta peuvent être enregistrées globalement dans le functions.php du thème réseau actif ou individuellement pour chaque site. L’appel à get_post_meta() fonctionne de la même manière dans les deux modes.

CMB2 ou ACF: quelle approche choisir pour votre projet

CMB2 résout exactement une tâche: créer des boîtes méta personnalisées via du code, avec la configuration stockée dans les fichiers du thème plutôt que dans la base de données. Le choix dépend de votre flux de travail, pas d’un abstrait «lequel est le meilleur».

• Si vous êtes développeur et stockez toute la configuration du projet dans Git, optez pour CMB2. Les boîtes méta résident dans metaboxes.php, se déploient avec votre thème et ne nécessitent pas de synchronisation de base de données entre la préproduction et la production.

• Si vous avez besoin d’un constructeur visuel, de champs flexibles répétables et de blocs Gutenberg prêts à l’emploi sans écrire de code, optez pour ACF Pro. L’abonnement à partir de 149 $ par an est rentabilisé par la vitesse de prototypage.

• Si votre projet utilise déjà CMB2 et que les boîtes méta fonctionnent de manière fiable, conservez-le. La bibliothèque n’est pas abandonnée, ne nécessite pas de migration urgente et reçoit régulièrement des mises à jour de compatibilité.

Essayez les deux approches sur un site de test: construisez la même boîte méta avec CMB2 et avec ACF. La différence d’approche deviendra évidente en 20 minutes. Quel outil utilisez-vous? Partagez votre avis dans les commentaires.