Les Block Variations de Gutenberg, c’est probablement l’une des fonctionnalités les plus sous-estimées de WordPress… et pourtant, elles peuvent vous faire gagner un temps fou ! Plutôt que de développer un bloc complet from scratch, pourquoi ne pas créer des variations intelligentes de blocs existants ? On va voir ensemble comment transformer cette API méconnue en véritable atout pour vos projets WordPress.
Les Block Variations : le pouvoir de Gutenberg révélé
Gutenberg, c’est un peu comme un immense jeu de construction… mais parfois, on aimerait bien personnaliser certaines pièces sans devoir tout recréer from scratch. Et c’est exactement là que les Block Variations entrent en scène ! Cette API méconnue (et pourtant si puissante) vous permet de créer des versions modifiées de blocs existants en quelques lignes de code.
Comprendre les variations de blocs dans l’écosystème WordPress
Une Block Variation, c’est en quelque sorte un « raccourci configuré » d’un bloc existant. Au lieu de partir d’un bloc vierge, vous proposez à vos utilisateurs une version pré-configurée avec des attributs spécifiques, des styles particuliers ou même un contenu initial.
Concrètement ? Prenez le bloc Colonne par exemple : WordPress propose déjà plusieurs variations (deux colonnes, trois colonnes, etc.). Chaque variation utilise le même bloc de base, mais avec des configurations différentes. C’est exactement ce principe que vous pouvez exploiter pour vos propres besoins.
Les variations apparaissent directement dans l’inserter de Gutenberg, aux côtés des blocs classiques. Vos utilisateurs peuvent donc les sélectionner d’un simple clic, sans se soucier de la configuration technique sous-jacente.
Différences avec les blocs custom : quand choisir les variations
Alors, variation ou bloc personnalisé ? Cette question revient souvent, et la réponse dépend vraiment de votre cas d’usage.
Les variations brillent quand vous voulez modifier légèrement un bloc existant. Par exemple, créer une version « testimonial » du bloc Quote avec des styles spécifiques, ou proposer des mises en page prédéfinies pour le bloc Groupe. Dans ces cas, pourquoi réinventer la roue ?
Les blocs custom, eux, sont nécessaires quand vous avez besoin de fonctionnalités totalement nouvelles. Si vous voulez créer un bloc de slider avec des contrôles avancés, une timeline interactive ou un système de tabs… là, il faudra développer from scratch.
Et puis, soyons honnêtes : les variations, c’est bien plus simple à maintenir ! Pas de JSX complexe, pas de build process… Juste quelques lignes de JavaScript et hop, c’est parti. La performance aussi est au rendez-vous : vous réutilisez le code existant plutôt que d’ajouter du poids supplémentaire.
Créer sa première variation de bloc : exemple pratique
Bon, maintenant qu’on a vu la théorie, passons à la pratique ! Je vais vous montrer comment créer une variation du bloc Colonnes avec une mise en page prédéfinie. C’est un exemple parfait pour comprendre le fonctionnement des Block Variations API.
Notre objectif ? Créer une variation « Article avec sidebar » avec deux colonnes : 70% pour le contenu principal et 30% pour la barre latérale. Et on va même ajouter du contenu par défaut (parce que c’est plus pratique pour l’utilisateur final).
Le code JavaScript complet
Voici le code complet pour notre variation :
wp.domReady(function () {
wp.blocks.registerBlockVariation('core/columns', {
name: 'article-with-sidebar',
title: 'Article avec sidebar',
description: 'Mise en page 70/30 pour article avec barre latérale',
keywords: ['article', 'sidebar', 'layout'],
category: 'layout',
icon: 'columns',
attributes: {
align: 'wide'
},
innerBlocks: [
[
'core/column',
{
width: '70%'
},
[
['core/heading', { content: 'Titre de l\'article' }],
['core/paragraph', { content: 'Commencez votre article ici...' }]
]
],
[
'core/column',
{
width: '30%'
},
[
['core/heading', { level: 3, content: 'À propos' }],
['core/paragraph', { content: 'Informations sur l\'auteur ou liens utiles.' }]
]
]
],
scope: ['inserter']
});
});
Décortiquons chaque propriété
Alors, que fait chacune de ces propriétés ?
name : L’identifiant unique de notre variation. Important : utilisez toujours des tirets, pas d’espaces (sinon WordPress va bouder).
title et description : Ce que verra l’utilisateur dans l’inserter de blocs. Soyez clairs et descriptifs !
attributes : Ici on définit que notre variation utilise l’alignement « wide » par défaut. Vous pouvez modifier n’importe quel attribut du bloc parent.
innerBlocks : C’est le cœur de notre variation. On définit la structure complète avec les blocs enfants. La syntaxe peut paraître un peu lourde au début, mais elle suit la logique [nom_du_bloc, attributs, blocs_enfants].
scope : Détermine où apparaît la variation. ['inserter'] signifie qu’elle n’apparaît que dans l’inserter, pas dans les transformations (plus propre selon moi).
Enregistrer la variation dans votre projet
Pour un thème, ajoutez ce code dans votre functions.php :
function mon_theme_block_variations() {
wp_enqueue_script(
'mon-theme-variations',
get_template_directory_uri() . '/js/block-variations.js',
array('wp-blocks', 'wp-dom-ready'),
'1.0.0'
);
}
add_action('enqueue_block_editor_assets', 'mon_theme_block_variations');
Pour un plugin, dans votre fichier principal :
function mon_plugin_block_variations() {
wp_enqueue_script(
'mon-plugin-variations',
plugin_dir_url(__FILE__) . 'js/block-variations.js',
array('wp-blocks', 'wp-dom-ready'),
'1.0.0'
);
}
add_action('enqueue_block_editor_assets', 'mon_plugin_block_variations');
Attention : n’oubliez pas les dépendances wp-blocks et wp-dom-ready, sinon ça ne marchera pas (j’ai mis du temps à comprendre ça la première fois) !
Et voilà ! Votre variation apparaîtra dans l’inserter de blocs, dans la catégorie Layout. L’utilisateur pourra l’insérer d’un clic et aura directement sa mise en page 70/30 avec du contenu de départ. Pratique, non ?
Cas d’usage avancés et bonnes pratiques
Maintenant qu’on maîtrise les bases, passons aux choses sérieuses ! Les Block Variations peuvent vraiment transformer votre workflow WordPress si on les utilise intelligemment. Bon, je vais être honnête : au début, j’ai tendance à créer des variations pour tout et n’importe quoi… mais avec l’expérience, on apprend à les utiliser à bon escient.
Variations de boutons avec styles prédéfinis
Les boutons, c’est l’exemple parfait pour comprendre la puissance des variations. Au lieu de laisser vos clients bricoler les couleurs et styles, on peut leur proposer des presets cohérents :
wp.blocks.registerBlockVariation('core/button', {
name: 'cta-primary',
title: 'Bouton CTA Principal',
description: 'Bouton d\'appel à l\'action principal du site',
attributes: {
className: 'btn-cta-primary',
style: {
color: {
background: '#ff6b6b',
text: '#ffffff'
},
border: {
radius: '8px'
}
},
text: 'Découvrir maintenant'
},
isDefault: false,
scope: ['inserter']
});
// Version outline
wp.blocks.registerBlockVariation('core/button', {
name: 'btn-outline',
title: 'Bouton Contour',
attributes: {
className: 'btn-outline',
style: {
color: {
background: 'transparent',
text: '#333333'
},
border: {
color: '#333333',
width: '2px',
style: 'solid',
radius: '4px'
}
},
text: 'En savoir plus'
}
});
Attention cependant : pensez à ajouter le CSS correspondant dans votre thème pour que les classes personnalisées s’affichent correctement !
Optimisation et architecture du code
Pour un code maintenable, l’organisation c’est crucial. Voici comment je structure mes variations dans un plugin ou thème :
/js/block-variations/
├── index.js (point d'entrée)
├── buttons/
│ ├── cta-variations.js
│ └── social-variations.js
├── layouts/
│ ├── columns-variations.js
│ └── group-variations.js
└── utils/
└── common-attributes.js
Et dans votre functions.php ou fichier principal du plugin :
function enqueue_block_variations() {
// Chargement conditionnel
if (is_admin() && function_exists('get_current_screen')) {
$screen = get_current_screen();
if ($screen && $screen->is_block_editor()) {
wp_enqueue_script(
'custom-block-variations',
get_theme_file_uri('/js/block-variations/index.js'),
['wp-blocks', 'wp-dom-ready'],
'1.0.0'
);
}
}
}
add_action('admin_enqueue_scripts', 'enqueue_block_variations');
Pour l’optimisation performance, le lazy loading des variations peut être très utile sur les gros sites. Plutôt que de charger toutes les variations d’un coup, on peut les charger à la demande selon le contexte.
Gestion des conflits et compatibilité
Bon, parlons du vrai problème : la compatibilité. Les Block Variations peuvent entrer en conflit avec d’autres plugins, surtout si vous utilisez le même nom de variation.
Première règle : préfixez TOUJOURS vos noms de variations :
// ❌ Mauvais - trop générique
name: 'hero-section'
// ✅ Bon - préfixé avec votre marque
name: 'monsite-hero-section'
Pour tester la compatibilité, j’ai développé cette petite fonction utile :
function registerVariationSafely(blockName, variation) {
wp.domReady(() => {
const existingVariations = wp.blocks.getBlockVariations(blockName) || [];
const conflictingVariation = existingVariations.find(v => v.name === variation.name);
if (conflictingVariation) {
console.warn(`Variation ${variation.name} already exists for ${blockName}`);
return;
}
wp.blocks.registerBlockVariation(blockName, variation);
});
}
Et puis, testez toujours vos variations avec les plugins populaires : Yoast, Elementor (même si ça utilise pas Gutenberg), WooCommerce, etc. Ces plugins modifient souvent le comportement de l’éditeur.
Pour finir, pensez à documenter vos variations ! Un simple README avec les variations disponibles et leurs use cases, ça évite bien des problèmes en équipe.