Depuis que les blocs Panier et Checkout sont devenus l’expérience par défaut des nouvelles boutiques WooCommerce, la personnalisation de ces pages ne passe plus uniquement par des hooks PHP ou des surcharges de templates classiques : une part croissante de leur comportement est pilotée côté client via l’Interactivity API, introduite dans le cœur de WordPress avec la version 6.5 en avril 2024. Pour un développeur habitué aux hooks PHP historiques de WooCommerce, cette évolution change la façon d’aborder certaines personnalisations.
Ce n’est pas un remplacement complet : les hooks PHP côté serveur (calcul des totaux, validation de commande, frais conditionnels) restent pleinement d’actualité. Ce qui change, c’est la couche d’interactivité front-end, auparavant gérée par du JavaScript impératif dispersé, désormais structurée par un modèle déclaratif cohérent.
Ce que l’Interactivity API change concrètement
Avant l’Interactivity API, personnaliser le comportement dynamique d’un bloc Panier (par exemple réagir instantanément à un changement de quantité sans recharger toute la page) demandait d’écrire du JavaScript qui manipulait directement le DOM, souvent fragile face aux mises à jour du bloc d’origine. L’Interactivity API introduit un modèle déclaratif où l’état et les interactions sont définis via des directives HTML (data-wp-on, data-wp-bind, data-wp-context), pendant qu’un store JavaScript centralisé gère la logique, dans un format bien plus proche de ce que proposent les frameworks front-end modernes, mais sans dépendance à un framework tiers.
Ajouter un comportement personnalisé sur le bloc Panier
Pour ajouter, par exemple, un message d’incitation qui apparaît dynamiquement quand le sous-total du panier approche un seuil de livraison offerte, la logique s’appuie sur un store enregistré via wp_interactivity_state côté serveur puis manipulé côté client :
// PHP : enregistrement du module d'interactivité et de son état initial
wp_interactivity_state( 'mon-agence/seuil-livraison', [
'seuilLivraisonOfferte' => 50,
] );
// JavaScript (store.js), chargé comme module
import { store, getContext } from '@wordpress/interactivity';
store( 'mon-agence/seuil-livraison', {
state: {
get montantRestant() {
const contexte = getContext();
return Math.max( 0, contexte.seuilLivraisonOfferte - contexte.sousTotal );
},
},
} );
Le fragment HTML correspondant, injecté via un filtre de bloc côté PHP, utilise les directives déclaratives pour afficher dynamiquement le montant restant sans recharger la page à chaque changement de quantité dans le panier :
<div data-wp-interactive="mon-agence/seuil-livraison" data-wp-context='{"sousTotal": 32}'>
<p data-wp-bind--hidden="!state.montantRestant">
Plus que <span data-wp-text="state.montantRestant"></span> € pour la livraison offerte !
</p>
</div>
Filtrer les blocs Checkout côté serveur
Le bloc Checkout expose ses propres points d’extension, distincts des hooks PHP historiques du tunnel de commande shortcode. Le filtre woocommerce_blocks_checkout_block_registration et l’API ExtendSchema permettent d’ajouter des champs personnalisés qui apparaissent nativement dans l’interface React du bloc, sans avoir à modifier son balisage :
add_action( 'woocommerce_blocks_loaded', function () {
woocommerce_store_api_register_endpoint_data( [
'endpoint' => \Automattic\WooCommerce\StoreApi\Schemas\V1\CheckoutSchema::IDENTIFIER,
'namespace' => 'mon-agence-checkout',
'data_callback' => function () {
return [ 'instructions_livraison' => '' ];
},
'schema_callback' => function () {
return [
'instructions_livraison' => [
'description' => 'Instructions de livraison particulières',
'type' => 'string',
'context' => [ 'view', 'edit' ],
],
];
},
] );
} );
Ce mécanisme s’appuie sur la Store API sous-jacente : les blocs Panier et Checkout ne discutent plus avec le serveur via des rechargements de page complets, mais via des appels REST vers /wc/store/v1/, ce qui explique pourquoi les anciens hooks pensés pour un rendu PHP synchrone (comme certains hooks de template shortcode) n’ont plus d’effet direct sur ces blocs.
Coexistence avec l’ancien tunnel shortcode
Les boutiques ayant fortement personnalisé leur tunnel de commande avec le shortcode historique [woocommerce_checkout] ne sont pas obligées de migrer immédiatement : WooCommerce continue de maintenir les deux systèmes en parallèle. La bascule vers les blocs mérite cependant d’être anticipée, car les surcharges de templates PHP classiques (fichiers copiés dans woocommerce/checkout/) n’ont aucun effet sur l’expérience basée sur les blocs, qui repose sur un rendu React côté client alimenté par la Store API.
Sur les projets récents, nous recommandons de traiter la bascule vers les blocs Panier et Checkout comme un chantier à part entière, avec ses propres tests, plutôt que comme une simple mise à jour transparente : les mécanismes de personnalisation sous-jacents ont réellement changé de nature.
En résumé
L’Interactivity API apporte aux blocs Panier et Checkout de WooCommerce un modèle de personnalisation front-end plus structuré que le JavaScript impératif d’autrefois, mais elle demande d’apprendre un nouveau vocabulaire : directives déclaratives, store d’état partagé, extension de schéma via la Store API. Pour un développeur venant des hooks PHP historiques, c’est un investissement d’apprentissage réel, mais qui ouvre la voie à des personnalisations de tunnel de commande plus réactives et mieux intégrées à l’écosystème de blocs natif de WordPress.
