Le mode Turbo de HUSKY ne fonctionne pas : filtre grisé et produits manquants
Quand le mode Turbo de HUSKY ne fonctionne pas, les symptômes semblent sans rapport : le filtre reste grisé, une catégorie ne renvoie aucun produit, les nouveaux produits n’apparaissent jamais, les décomptes sont faux, ou le mode AJAX ne peut pas être désactivé. Presque tous découlent d’un seul choix de conception : en mode Turbo, le filtrage se fait dans le navigateur du visiteur, à partir d’un fichier de données produits construit à l’avance. Voici comment ce fichier est créé et utilisé, et le remède pour chaque symptôme.
Comment fonctionne le mode Turbo, et quand l’utiliser
En mode normal, chaque clic sur le filtre oblige le serveur à exécuter une requête WooCommerce et à compter les produits de chaque terme. Le mode Turbo déplace ce travail vers le navigateur. HUSKY écrit tous les produits publiés et leurs variations dans un seul fichier JSON (par défaut dans wp-content/uploads/uploads_woof_turbo_mode/) avec l’ID, le titre, l’UGS, les prix, l’état du stock, les termes de chaque taxonomie de produit et les valeurs des champs du filtre Meta. Le navigateur le télécharge sur chaque page publique où le plugin s’exécute (limitez ces pages avec Initialiser le plugin uniquement sur les pages suivantes du site (Init plugin on the next site pages only) dans l’onglet Avancé (Advanced)), trouve les produits correspondants et affiche les décomptes ; le serveur ne fait que générer le rendu des produits trouvés à partir de leurs ID.
Les résultats ne sont donc aussi à jour que le fichier, un produit absent du fichier ne peut pas être trouvé, seules les conditions que le navigateur comprend sont appliquées, et chaque visiteur télécharge tout le catalogue, ce qui représente avec des dizaines de milliers de produits et de variations plusieurs mégaoctets et un démarrage lent sur mobile. Le mode Turbo est rentable sur un serveur peu puissant avec un catalogue de taille modérée qui change rarement. Si le serveur peut exécuter les requêtes, essayez d’abord le mode normal avec les caches décrits dans comment accélérer le filtrage de produits dans les grands catalogues.
L’activer dans le bon ordre
- WooCommerce → Réglages → Products Filter → Extensions : cochez Mode Turbo (Turbo mode) et enregistrez.
- Avancé (Advanced) → Mode Turbo (Turbo mode) : réglez Activer le mode Turbo (Enable turbo mode) sur Oui (Yes) et enregistrez.
- Cliquez sur Mettre à jour maintenant ! (Update now!) sous Reconstruire les données produits maintenant (Reassemble products data now!) et gardez la page ouverte jusqu’à l’apparition de Fichier mis à jour (File updated!!!). Sans le fichier, le filtre ne peut pas chercher.
- Choisissez la Période du cron WordPress (WordPress Cron period) et Où conserver le fichier de données produits (Where to keep products data file), puis enregistrez.
- Dans l’onglet Options, réglez Afficher le décompte (Show count), Recomptage dynamique (Dynamic recount) et Masquer les termes vides (Hide empty terms), qui existent en mode Turbo sous forme de copies distinctes (expliqué plus bas), puis videz le cache des pages et tout cache de CDN.
Le filtre est grisé et ne devient jamais cliquable
La couche grise est un élément portant la classe woof_turbo_mode_overlay. Elle recouvre le filtre dès le premier instant, et le script du mode Turbo la retire une fois le fichier chargé et les décomptes affichés. Si la couche reste, ce script n’est pas allé au bout :
- Scripts retardés, différés ou combinés. Les fonctions d’optimisation de WP Rocket, LiteSpeed Cache et de plugins similaires peuvent lancer les scripts tard, dans le désordre ou pas du tout. Le mode Turbo a besoin de
ext/turbo_mode/js/turbo_mode.jset deext/quick_search/js/alasql/alasql.min.jssitués danswp-content/plugins/woocommerce-products-filter/, après jQuery. Excluez le dossier du plugin du retardement, du report et de la combinaison, puis videz tous les caches ; le filtre avec WP Rocket et la mise en cache explique les exclusions. - Une erreur JavaScript. Ouvrez la console du navigateur (F12) et rechargez la page. La première erreur en rouge désigne le script qui a bloqué les autres.
- Un gros fichier sur une connexion lente. Dans l’onglet Réseau (Network), vérifiez la taille et la durée de chargement de
data_0000_xxx.json. Si le téléchargement laisse le filtre grisé pendant plusieurs secondes, le catalogue est trop volumineux pour le mode Turbo.
Masquer la couche avec du CSS (.woof_turbo_mode_overlay{display:none;}) ne fait que cacher le symptôme : le filtre devient cliquable, mais sans fichier chargé il ne peut pas chercher.
Quand le fichier ne peut pas être chargé, le filtre est remplacé par l’avis Oh non ! Il semble que le filtre ne puisse pas ouvrir le fichier de recherche. (Oh no! It looks like the filter can't open the search file.) Vérifiez que :
- le fichier existe. Un fichier conservé dans le dossier du plugin (plugins\woocommerce-products-filter\ext\turbo_mode\data) est supprimé à chaque mise à jour du plugin ; reconstruisez-le donc après les mises à jour, ou conservez-le dans wp-uploads\uploads_woof_turbo_mode ;
- aucune règle du serveur ni aucun plugin de sécurité ne bloque les fichiers
.jsondans uploads : ouvrez directement l’adresse du fichier indiquée dans l’onglet Réseau (Network) ; - l’adresse est correcte. Le plugin demande
wp-content/uploads/uploads_woof_turbo_mode/; sur un sous-site d’un multisite, ou avec le dossier uploads déplacé ailleurs, la requête renvoie donc une erreur 404. Conservez alors le fichier dans le dossier du plugin.
Aucun produit trouvé, ou produits manquants après le filtrage
Le mode Turbo ne renvoie que les produits présents dans le fichier, comparés aux données qui y sont stockées. Vérifiez les deux depuis la console du navigateur, sur une page avec le filtre, une fois celui-ci chargé :
woof_turbo_mode_file.length // records in the file: products + variations
woof_turbo_mode_file.find(p => p.id == 123) // what is stored for product 123
Comparez le premier nombre avec vos produits publiés plus leurs variations ; avec WP-CLI, wp post list --post_type=product,product_variation --post_status=publish --format=count le donne. Si un produit renvoie undefined, il n’est pas dans le fichier. S’il y est, examinez ses taxonomies et son stock.
Le fichier est périmé
Les nouveaux produits, les catégories modifiées, les attributs, les prix et le stock n’atteignent le filtre qu’à la prochaine reconstruction. Signes typiques : un nouveau produit est listé sur la page de la boutique mais disparaît après le premier clic sur le filtre, les nouveaux termes affichent un décompte de 0, les dernières pages de pagination sont vides, ou un élément du filtre Meta ajouté après la dernière reconstruction ne trouve rien. Reconstruisez le fichier après les imports et après toute modification des éléments du filtre.
La limite de 15 000
Mettre à jour maintenant ! (Update now!) s’arrête après 15 000 enregistrements, et les variations comptent. Une boutique avec 2 000 produits variables de huit variations chacun en compte déjà 18 000. Le bouton traite d’abord les produits les plus récents, donc les produits laissés de côté sont vos plus anciens. Si le compteur à côté du bouton s’est arrêté sur Produits et variantes : 15000 (Products and Variants: 15000), vous avez atteint la limite. Relevez-la avec le hook woof_turbo_mode_products_limit et reconstruisez :
/*
* HUSKY Turbo mode: let "Update now" write up to 40,000 products and variations.
* Child theme functions.php or a code snippets plugin.
*/
add_filter('woof_turbo_mode_products_limit', function ($limit) {
return 40000;
});
La reconstruction planifiée n’est pas plafonnée par ce hook ; elle traite tout le catalogue.
Les produits des sous-catégories ne sont pas trouvés
Le fichier ne stocke que les catégories cochées sur chaque produit, et le navigateur les compare littéralement ; il ne connaît pas l’arborescence des catégories. WordPress affiche les produits des sous-catégories dans une catégorie parente, mais pas le mode Turbo : un produit coché uniquement dans Chaussures de course apparaît sur la page Chaussures jusqu’au premier clic sur le filtre, puis disparaît ; le terme Chaussures du filtre ne le trouve pas, et le décompte de Chaussures l’ignore. Cochez chaque niveau de la chaîne (Chaussures et Chaussures de course) sur ces produits, par exemple avec la modification groupée dans Produits → Tous les produits, puis reconstruisez le fichier.
Produits masqués et en rupture de stock
Les produits dont la Visibilité dans le catalogue (Catalog visibility) est Boutique uniquement (Shop only) ou Masqué (Hidden) sont considérés comme masqués de la recherche, et le mode Turbo ne les renvoie jamais après le filtrage, quelle que soit la valeur de Tenir compte de la visibilité dans le catalogue (Listen catalog visibility). Un produit Boutique uniquement (Shop only) apparaît donc sur la page de la boutique et disparaît après le premier clic ; réglez-le sur Boutique et résultats de recherche (Shop and search results) s’il doit être filtrable. Lorsque l’option WooCommerce Masquer les produits en rupture de stock du catalogue (Hide out of stock items from the catalog) est activée, les produits en rupture de stock sont exclus du fichier, et un produit de nouveau en stock reste absent jusqu’à la prochaine reconstruction.
Langues WPML
Avec WPML, HUSKY écrit un fichier par langue (data_0000_en.json, data_0000_de.json) et charge le fichier de la langue courante. Un produit sans traduction est absent du fichier de cette langue ; reconstruisez donc après avoir traduit.
Garder le fichier de recherche à jour
Mettre à jour maintenant ! (Update now!) construit le fichier par lots de dix produits ou variations, au plus un lot par seconde, avec un compteur Produits et variantes (Products and Variants). Chaque lot réécrit le fichier entier, donc 15 000 enregistrements prennent au moins 25 minutes. Contrairement à la reconstruction planifiée, le bouton supprime d’abord le fichier actuel, et tant qu’il n’a pas terminé, le site filtre avec des données incomplètes : lancez-le à un moment calme, gardez la page ouverte et ne désactivez pas le mode Turbo en cours de route.
Période du cron WordPress (WordPress Cron period) définit la reconstruction automatique : quotidienne (daily), hebdomadaire (weekly) (la valeur par défaut), deux fois par mois (twicemonthly), mensuelle (monthly), min1 ou sans mise à jour (without update). Malgré son nom, ce n’est pas un événement WP-Cron. HUSKY tient son propre calendrier (l’option woof_turbo_init_wpcrone_) : quand une reconstruction est due, chaque requête qui charge WordPress avec le plugin, au plus une toutes les cinq secondes, ajoute les dix enregistrements suivants à un fichier temporaire, qui remplace le fichier en service après le dernier lot. Les visiteurs gardent les données précédentes jusque-là. Ce qui en découle :
- WP Crontrol et les outils similaires ne la listent pas, et
DISABLE_WP_CRONne l’arrête pas. - La vitesse dépend des requêtes qui atteignent PHP ; les pages servies par un cache de pages ne comptent pas. 20 000 enregistrements demandent au moins 2 000 requêtes espacées de cinq secondes, soit près de trois heures de trafic soutenu, et plusieurs jours sur un site peu fréquenté.
- La première reconstruction automatique arrive une période complète après l’enregistrement du calendrier ; cliquez donc sur Mettre à jour maintenant ! (Update now!) après l’activation.
- La période se compte à partir de la fin de la reconstruction précédente. min1 lance la suivante une minute plus tard, si bien que le site se reconstruit en permanence ; réservez-le aux petits catalogues.
- Un clic sur Mettre à jour maintenant ! (Update now!) pendant une reconstruction automatique supprime aussi son fichier temporaire ; quand l’exécution automatique se termine, elle remplace votre fichier complet par la partie qu’elle a construite ensuite. Si des produits disparaissent de nouveau quelques heures après une reconstruction manuelle, cliquez encore une fois sur le bouton.
Sur un site à faible trafic, une tâche cron du serveur peut fournir les requêtes ; la FAQ pourquoi les mises à jour cron automatiques échouent montre la configuration et les limites de PHP. Appelez-la chaque minute, et non une fois par jour, car chaque appel ajoute un lot. Si vous avez limité le plugin avec Initialiser le plugin uniquement sur les pages suivantes du site (Init plugin on the next site pages only), faites-lui demander /wp-admin/admin-ajax.php, où le plugin se charge toujours. Même ainsi, elle n’ajoute que 600 enregistrements par heure ; pour les catalogues modifiés en masse, cliquez donc sur Mettre à jour maintenant ! (Update now!) après chaque import.
D’autres périodes peuvent être ajoutées avec le hook woof_turbo_mode_schedules, sans modifier les fichiers du plugin ; choisissez ensuite la nouvelle période et enregistrez :
/*
* HUSKY Turbo mode: add "every 12 hours" to WordPress Cron period.
* Child theme functions.php or a code snippets plugin.
*/
add_filter('woof_turbo_mode_schedules', function ($schedules) {
$schedules['every_12_hours'] = array(
'name' => 'every 12 hours',
'value' => 12 * HOUR_IN_SECONDS,
);
return $schedules;
});
Le fichier garde la même adresse après chaque reconstruction. Si un CDN ou le navigateur met en cache les fichiers .json, les visiteurs peuvent continuer à recevoir d’anciennes données : excluez le dossier uploads_woof_turbo_mode de la mise en cache du CDN, ou purgez-le après les reconstructions.
Le mode Turbo exige AJAX et a ses propres réglages de décompte
Tant que le mode Turbo est activé, HUSKY réinitialise quatre réglages à chaque chargement de page : Essayer d’ajaxifier la boutique (Try to ajaxify the shop) passe à Oui (Yes), et les réglages habituels Afficher le décompte (Show count), Recomptage dynamique (Dynamic recount) et Masquer les termes vides (Hide empty terms) passent à Non (No). L’onglet Options affiche alors les copies propres au mode Turbo de ces trois réglages sous les mêmes noms, et Recomptage dynamique (Dynamic recount) propose Oui, pour tous les appareils (Yes, for all devices) ou Oui, uniquement pour PC (Yes, only for PC).
- AJAX ne peut pas être désactivé tant que le mode Turbo est activé. Réglez Activer le mode Turbo (Enable turbo mode) sur Non (No), enregistrez, et seulement ensuite modifiez Essayer d’ajaxifier la boutique (Try to ajaxify the shop).
- Si la grille de produits du thème se casse après le filtrage AJAX (un produit par ligne, colonnes perdues, pagination cassée), le mode Turbo en hérite : voyez définir le nombre de colonnes en mode AJAX et les problèmes de pagination en mode AJAX, ou laissez le mode Turbo désactivé pour ce thème.
- Après avoir désactivé le mode Turbo, réglez de nouveau Afficher le décompte (Show count), Recomptage dynamique (Dynamic recount) et Masquer les termes vides (Hide empty terms) : ils sont toujours sur Non (No), ce qui explique que les compteurs disparaissent à ce moment-là.
- Masquer les termes vides (Hide empty terms) ne fonctionne qu’avec Afficher le décompte (Show count) et Recomptage dynamique (Dynamic recount) activés ; désactiver Afficher le décompte (Show count) désactive les deux autres.
- Cache du nombre de recomptage dynamique pour chaque élément du filtre (Cache dynamic recount number for each item in filter), Cache des termes (Cache terms) et Optimiser le filtre de prix (Optimize price filter) disparaissent de Avancé → Options tant que le mode Turbo est activé ; ils ne s’y appliquent pas.
Ce que le mode Turbo ne sait pas faire
- L’élément Liste déroulante hiérarchique (Hierarchy drop-down) ne fonctionne pas avec lui, comme l’indique la page de l’extension Mode Turbo.
- Les décomptes et Masquer les termes vides (Hide empty terms) fonctionnent pour les éléments standard (case à cocher, bouton radio, listes déroulantes, couleur, image, étiquette, curseur). Les éléments créés avec Smart Designer n’ont aucun décompte.
- En stock (In stock) ne regarde que l’état du stock propre à chaque produit ; le réglage qui vérifie les variations n’a aucun effet, si bien qu’un filtre par taille peut encore afficher des variations en rupture de stock.
- La recherche textuelle compare les mots saisis aux seuls titres des produits, même si l’élément de recherche textuelle est configuré pour chercher dans les descriptions ou d’autres champs. L’élément UGS distinct fonctionne.
- Les conditions ajoutées en PHP ne participent pas à la recherche, puisque c’est le navigateur qui décide quels produits correspondent. Le code personnalisé sur
woof_products_queryoupre_get_posts, les extensions personnalisées et les plugins qui limitent les produits par vendeur ou par groupe de clients peuvent tout au plus masquer certains produits trouvés après coup, ce qui désynchronise les décomptes et la pagination.
Si votre boutique a besoin de l’une de ces fonctions, ou si ses prix et son stock changent toutes les heures, désactivez le mode Turbo et accélérez plutôt le mode normal grâce à la mise en cache.
Liste de contrôle
- Aucune erreur rouge dans la console ; les scripts du plugin exclus du retardement, du report et de la combinaison.
woof_turbo_mode_file.lengthcorrespond aux produits publiés plus les variations ; le compteur ne s’est pas arrêté à la limite.- Fichier reconstruit après le dernier import ou la dernière modification du filtre ; cache des pages et CDN purgés.
- Produits cochés dans toute la chaîne de catégories, avec la visibilité Boutique et résultats de recherche (Shop and search results).
- Réglages de décompte définis dans les copies du mode Turbo, puis de nouveau après la désactivation du mode Turbo.
Si le filtre se comporte encore mal, ouvrez un sujet sur le forum d’assistance HUSKY en indiquant le lien de la page, les erreurs de la console, la valeur de woof_turbo_mode_file.length et le nombre de vos produits et variations.