El modo Turbo de HUSKY no funciona: filtro en gris y productos que faltan
Cuando el modo Turbo de HUSKY no funciona, los síntomas parecen no tener relación entre sí: el filtro se queda en gris, una categoría no devuelve productos, los productos nuevos no aparecen nunca, los recuentos son incorrectos o no se puede desactivar el modo AJAX. Casi todos tienen su origen en una única decisión de diseño: en el modo Turbo el filtrado ocurre en el navegador del visitante, sobre un archivo de datos de productos creado de antemano. A continuación verás cómo se crea y se usa ese archivo, y la solución para cada síntoma.
Cómo funciona el modo Turbo y cuándo conviene usarlo
En el modo normal, cada clic en el filtro hace que el servidor ejecute una consulta de WooCommerce y cuente los productos de cada término. El modo Turbo traslada ese trabajo al navegador. HUSKY escribe todos los productos publicados y sus variaciones en un único archivo JSON (por defecto en wp-content/uploads/uploads_woof_turbo_mode/) con el ID, el título, el SKU, los precios, el estado del stock, los términos de cada taxonomía de producto y los valores de los campos del filtro Meta. El navegador lo descarga en cada página del front-end en la que se ejecuta el plugin (limita esas páginas con Inicie plugin en las siguientes páginas del sitio solamente (Init plugin on the next site pages only) en la pestaña Avanzadas (Advanced)), encuentra los productos que coinciden y dibuja los recuentos; el servidor solo renderiza los productos encontrados a partir de sus ID.
Por tanto, los resultados solo están tan actualizados como el archivo, un producto que no esté en él no se puede encontrar, solo se aplican las condiciones que el navegador entiende, y cada visitante descarga el catálogo completo, lo que con decenas de miles de productos y variaciones supone megabytes y un arranque lento en los móviles. El modo Turbo compensa en un servidor poco potente con un catálogo moderado que cambia poco. Si el servidor puede ejecutar las consultas, prueba primero el modo normal con las cachés descritas en cómo acelerar el filtrado de productos en catálogos grandes.
Actívalo en el orden correcto
- WooCommerce → Ajustes → Products Filter → Extensiones (Extensions): marca Modo Turbo (Turbo mode) y guarda.
- Avanzadas (Advanced) → Modo Turbo (Turbo mode): establece Activar modo Turbo (Enable turbo mode) en Sí (Yes) y guarda.
- Haz clic en ¡Actualizar ahora! (Update now!) bajo Reconstruir ahora los datos de productos (Reassemble products data now!) y mantén la página abierta hasta que aparezca Archivo actualizado (File updated!!!). Sin el archivo, el filtro no puede buscar.
- Elige el Período de WordPress Cron (WordPress Cron period) y Dónde guardar el archivo de datos de productos (Where to keep products data file), y guarda.
- En la pestaña Opciones (Options) configura Mostrar recuento (Show count), Recuento dinámico (Dynamic recount) y Ocultar términos vacíos (Hide empty terms), que en el modo Turbo son copias independientes (se explica más abajo); después vacía la caché de página y la de cualquier CDN.
El filtro está en gris y nunca se puede pulsar
La capa gris es un elemento con la clase woof_turbo_mode_overlay. Cubre el filtro desde el primer momento, y el script del modo Turbo la elimina cuando el archivo se ha cargado y los recuentos están dibujados. Si la capa permanece, ese script no ha terminado:
- Scripts retrasados, diferidos o combinados. Las funciones de optimización de WP Rocket, LiteSpeed Cache y plugins similares pueden iniciar los scripts tarde, en otro orden o no iniciarlos. El modo Turbo necesita
ext/turbo_mode/js/turbo_mode.jsyext/quick_search/js/alasql/alasql.min.jsdewp-content/plugins/woocommerce-products-filter/, después de jQuery. Excluye la carpeta del plugin del retraso, el diferido y la combinación, y vacía todas las cachés; el filtro con WP Rocket y las cachés explica las exclusiones. - Un error de JavaScript. Abre la consola del navegador (F12) y recarga. El primer error en rojo indica el script que detuvo al resto.
- Un archivo grande con una conexión lenta. En la pestaña Red (Network), comprueba el tamaño y el tiempo de
data_0000_xxx.json. Si la descarga mantiene el filtro en gris durante segundos, el catálogo es demasiado grande para el modo Turbo.
Ocultar la capa con CSS (.woof_turbo_mode_overlay{display:none;}) solo esconde el síntoma: el filtro se puede pulsar, pero sin un archivo cargado no puede buscar.
Cuando no se puede cargar el archivo, el filtro se sustituye por el aviso ¡Vaya! Parece que el filtro no puede abrir el archivo de búsqueda (Oh no! It looks like the filter can't open the search file.) Comprueba que:
- el archivo existe. Un archivo guardado en la carpeta del plugin (plugins\woocommerce-products-filter\ext\turbo_mode\data) se elimina con cada actualización del plugin, así que reconstrúyelo después de actualizar, o guárdalo en wp-uploads\uploads_woof_turbo_mode;
- ninguna regla del servidor ni plugin de seguridad bloquea los archivos
.jsonen uploads: abre directamente la dirección del archivo que ves en la pestaña Red (Network); - la dirección es correcta. El plugin solicita
wp-content/uploads/uploads_woof_turbo_mode/, de modo que en un subsitio de multisitio, o con la carpeta de uploads trasladada a otro lugar, la petición devuelve un 404. En ese caso, guarda el archivo en la carpeta del plugin.
No se encuentran productos, o faltan productos tras filtrar
El modo Turbo solo devuelve los productos que están en el archivo, comparados con los datos almacenados allí. Comprueba ambas cosas desde la consola del navegador, en una página con el filtro, una vez que se haya cargado:
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
Compara el primer número con tus productos publicados más las variaciones; con WP-CLI, wp post list --post_type=product,product_variation --post_status=publish --format=count te lo da. Si un producto devuelve undefined, no está en el archivo. Si está, revisa sus taxonomies y su stock.
El archivo está desactualizado
Los productos nuevos, las categorías, los atributos, los precios y el stock modificados llegan al filtro solo con la siguiente reconstrucción. Señales típicas: un producto nuevo aparece en la página de la tienda pero desaparece tras el primer clic en el filtro, los términos nuevos muestran un recuento de 0, las últimas páginas de la paginación están vacías, o un elemento de filtro Meta añadido después de la última reconstrucción no encuentra nada. Reconstruye el archivo después de las importaciones y después de cambiar los elementos del filtro.
El límite de 15.000
¡Actualizar ahora! (Update now!) se detiene tras 15.000 registros, y las variaciones cuentan. Una tienda con 2.000 productos variables de ocho variaciones cada uno ya tiene 18.000. El botón procesa primero los productos más recientes, así que los que se quedan fuera son los más antiguos. Si el contador junto al botón se detuvo en Productos y variantes: 15000 (Products and Variants: 15000), has alcanzado el límite. Auméntalo con el hook woof_turbo_mode_products_limit y reconstruye:
/*
* 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 reconstrucción programada no está limitada por este hook; procesa todo el catálogo.
No se encuentran los productos de las subcategorías
El archivo guarda solo las categorías marcadas en cada producto, y el navegador las compara literalmente; no conoce el árbol de categorías. WordPress muestra los productos de las subcategorías en una categoría padre, pero el modo Turbo no: un producto marcado solo en Zapatillas de running aparece en la página de Calzado hasta el primer clic en el filtro y luego desaparece, el término Calzado del filtro no lo encuentra y el recuento de Calzado lo deja fuera. Marca todos los niveles de la cadena (Calzado y Zapatillas de running) en esos productos, por ejemplo con la edición en lote de Productos → Todos los productos, y después reconstruye el archivo.
Productos ocultos y agotados
Los productos cuya Visibilidad en el catálogo (Catalog visibility) es Solo tienda (Shop only) u Oculto (Hidden) se consideran ocultos para la búsqueda, y el modo Turbo nunca los devuelve tras filtrar, diga lo que diga Escuchar catálogo de visibilidad (Listen catalog visibility). Un producto con Solo tienda (Shop only) aparece, por tanto, en la página de la tienda y desaparece tras el primer clic; establécelo en Tienda y resultados de búsqueda (Shop and search results) si debe poder filtrarse. Con Ocultar productos agotados del catálogo (Hide out of stock items from the catalog) de WooCommerce activado, los productos agotados se dejan fuera del archivo, y un producto que vuelve a tener stock sigue sin aparecer hasta la siguiente reconstrucción.
Idiomas con WPML
Con WPML, HUSKY escribe un archivo por idioma (data_0000_en.json, data_0000_de.json) y carga el del idioma actual. Un producto sin traducción no aparece en el archivo de ese idioma, así que reconstruye después de traducir.
Mantener el archivo de búsqueda actualizado
¡Actualizar ahora! (Update now!) construye el archivo en lotes de diez productos o variaciones, como máximo un lote por segundo, con un contador de Productos y variantes (Products and Variants). Cada lote reescribe el archivo entero, así que 15.000 registros tardan al menos 25 minutos. A diferencia de la reconstrucción programada, el botón elimina primero el archivo actual, y hasta que termina el sitio filtra con datos incompletos: ejecútalo en un momento tranquilo, mantén la página abierta y no desactives el modo Turbo a mitad del proceso.
Período de WordPress Cron (WordPress Cron period) define la reconstrucción automática: diario (daily), semanalmente (weekly) (el valor por defecto), bimensual (twicemonthly), mensualmente (monthly), min1 o sin actualización (without update). A pesar del nombre, no es un evento de WP-Cron. HUSKY mantiene su propio calendario (la opción woof_turbo_init_wpcrone_): cuando toca una reconstrucción, cada petición que carga WordPress con el plugin, como máximo una cada cinco segundos, añade los diez registros siguientes a un archivo temporal, que sustituye al archivo activo tras el último lote. Hasta entonces, los visitantes siguen recibiendo los datos anteriores. De ello se desprende que:
- WP Crontrol y herramientas similares no lo muestran, y
DISABLE_WP_CRONno lo detiene. - La velocidad depende de las peticiones que llegan a PHP; las páginas servidas desde una caché de página no cuentan. 20.000 registros necesitan al menos 2.000 peticiones separadas por cinco segundos, cerca de tres horas de tráfico constante, y en un sitio con poco tráfico, días.
- La primera reconstrucción automática llega un período completo después de guardar el calendario, así que haz clic en ¡Actualizar ahora! (Update now!) después de activarlo.
- El período se cuenta desde el final de la reconstrucción anterior. min1 inicia la siguiente un minuto después, de modo que el sitio se reconstruye continuamente; úsalo solo con catálogos pequeños.
- Si haces clic en ¡Actualizar ahora! (Update now!) durante una reconstrucción automática, también se elimina su archivo temporal; cuando termina la ejecución automática, sustituye tu archivo completo por la parte que construyó después. Si los productos vuelven a faltar horas después de una reconstrucción manual, haz clic en el botón una vez más.
En un sitio con poco tráfico, una tarea cron del servidor puede aportar las peticiones; la pregunta frecuente por qué fallan las actualizaciones automáticas por cron muestra la configuración y los límites de PHP. Llámala cada minuto, no una vez al día, porque cada llamada añade un lote. Si has limitado el plugin con Inicie plugin en las siguientes páginas del sitio solamente (Init plugin on the next site pages only), haz que solicite /wp-admin/admin-ajax.php, donde el plugin siempre se carga. Aun así, añade solo 600 registros por hora, de modo que, en catálogos que cambian en bloque, haz clic en ¡Actualizar ahora! (Update now!) después de cada importación.
Se pueden añadir otros períodos con el hook woof_turbo_mode_schedules, sin editar los archivos del plugin; después elige el nuevo período y guarda:
/*
* 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;
});
El archivo conserva la misma dirección tras cada reconstrucción. Si una CDN o el navegador almacenan en caché los archivos .json, los visitantes pueden seguir recibiendo datos antiguos: excluye la carpeta uploads_woof_turbo_mode de la caché de la CDN, o vacíala después de las reconstrucciones.
El modo Turbo necesita AJAX y tiene sus propios ajustes de recuento
Mientras el modo Turbo está activado, HUSKY restablece cuatro ajustes en cada carga de página: Intenta ajaxificar la tienda (Try to ajaxify the shop) pasa a Sí (Yes), y los ajustes normales Mostrar recuento (Show count), Recuento dinámico (Dynamic recount) y Ocultar términos vacíos (Hide empty terms) pasan a No. La pestaña Opciones (Options) muestra entonces las copias propias del modo Turbo de estos tres con los mismos nombres, y Recuento dinámico (Dynamic recount) ofrece Sí, para todos los dispositivos (Yes, for all devices) o Sí, solo para PC (Yes, only for PC).
- No se puede desactivar AJAX mientras el modo Turbo está activado. Establece Activar modo Turbo (Enable turbo mode) en No, guarda, y solo entonces cambia Intenta ajaxificar la tienda (Try to ajaxify the shop).
- Si la cuadrícula de productos del tema se rompe tras el filtrado AJAX (un producto por fila, columnas perdidas, paginación rota), el modo Turbo la hereda: consulta cómo fijar el número de columnas en el modo AJAX y problemas de paginación en el modo AJAX, o mantén el modo Turbo desactivado para ese tema.
- Tras desactivar el modo Turbo, vuelve a configurar Mostrar recuento (Show count), Recuento dinámico (Dynamic recount) y Ocultar términos vacíos (Hide empty terms): siguen en No, y por eso los contadores desaparecen en ese momento.
- Ocultar términos vacíos (Hide empty terms) funciona solo con Mostrar recuento (Show count) y Recuento dinámico (Dynamic recount) activados; desactivar Mostrar recuento (Show count) desactiva los otros dos.
- Número de recuento dinámico de caché para cada elemento en el filtro (Cache dynamic recount number for each item in filter), Términos de la caché (Cache terms) y Optimizar filtro de precios (Optimize price filter) desaparecen de Avanzadas → Opciones mientras el modo Turbo está activado; no se aplican a él.
Lo que el modo Turbo no puede hacer
- El elemento Desplegable Jerarquía (Hierarchy drop-down) no funciona con él, como se indica en la página de la extensión Turbo mode.
- Los recuentos y Ocultar términos vacíos (Hide empty terms) funcionan con los elementos estándar (casilla, radio, desplegables, color, imagen, etiqueta, deslizador). Los elementos creados con Smart Designer no tienen recuentos.
- En stock (In stock) solo mira el estado de stock propio de cada producto; el ajuste que comprueba las variaciones no tiene efecto, de modo que un filtro por talla aún puede mostrar variaciones agotadas.
- La búsqueda de texto compara las palabras escritas solo con los títulos de los productos, aunque el elemento de búsqueda de texto esté configurado para buscar en las descripciones u otros campos. El elemento SKU independiente sí funciona.
- Las condiciones añadidas en PHP no participan en la búsqueda, porque es el navegador quien decide qué productos coinciden. El código personalizado en
woof_products_queryopre_get_posts, las extensiones personalizadas y los plugins que limitan los productos por proveedor o grupo de clientes, como mucho pueden ocultar algunos productos encontrados después, lo que desajusta los recuentos y la paginación.
Si tu tienda necesita alguna de estas funciones, o sus precios y su stock cambian cada hora, desactiva el modo Turbo y acelera el modo normal con cachés.
Lista de comprobación
- Sin errores en rojo en la consola; los scripts del plugin excluidos del retraso, el diferido y la combinación.
woof_turbo_mode_file.lengthcoincide con los productos publicados más las variaciones; el contador no se detuvo en el límite.- Archivo reconstruido después de la última importación o cambio del filtro; caché de página y CDN vaciadas.
- Productos marcados en toda la cadena de categorías, con visibilidad Tienda y resultados de búsqueda (Shop and search results).
- Ajustes de recuento establecidos en las copias del modo Turbo, y de nuevo tras desactivar el modo Turbo.
Si el filtro sigue sin comportarse bien, abre un tema en el foro de soporte de HUSKY con el enlace de la página, los errores de la consola, el valor de woof_turbo_mode_file.length y el número de tus productos y variaciones.