HUSKY - WooCommerce Product Filter Professional

Modo Turbo do HUSKY não funciona: filtro acinzentado e produtos ausentes

Quando o Modo Turbo do HUSKY não funciona, os sintomas parecem não ter relação entre si: o filtro fica acinzentado, uma categoria não retorna produtos, produtos novos nunca aparecem, as contagens estão erradas ou o modo AJAX não consegue ser desativado. Quase todos têm origem em uma única decisão de projeto: no Modo Turbo, a filtragem acontece no navegador do visitante, a partir de um arquivo de dados de produtos criado com antecedência. Veja abaixo como esse arquivo é gerado e usado, e a solução para cada sintoma.

Como o Modo Turbo funciona e quando vale a pena usá-lo

No modo normal, cada clique no filtro faz o servidor executar uma consulta do WooCommerce e contar os produtos de cada termo. O Modo Turbo transfere esse trabalho para o navegador. O HUSKY grava todos os produtos publicados e suas variações em um único arquivo JSON (por padrão em wp-content/uploads/uploads_woof_turbo_mode/) com o ID, o título, o SKU, os preços, o status de estoque, os termos de cada taxonomia de produto e os valores dos campos do filtro Meta. O navegador baixa esse arquivo em todas as páginas do front-end em que o plugin é executado (limite essas páginas com Inicializar o plugin somente nas páginas a seguir (Init plugin on the next site pages only) na aba Avançado (Advanced)), encontra os produtos correspondentes e desenha as contagens; o servidor apenas renderiza os produtos encontrados a partir dos IDs.

Assim, os resultados são tão atuais quanto o arquivo, um produto ausente dele não pode ser encontrado, só são aplicadas as condições que o navegador entende, e cada visitante baixa o catálogo inteiro, o que, com dezenas de milhares de produtos e variações, significa megabytes e uma abertura lenta em celulares. O Modo Turbo compensa em um servidor fraco com um catálogo moderado que muda pouco. Se o servidor consegue executar as consultas, experimente primeiro o modo normal com os caches descritos em como acelerar a filtragem de produtos em catálogos grandes.

Ative na ordem certa

  1. WooCommerce → Configurações → Products Filter → Extensões (Extensions): marque Modo Turbo (Turbo mode) e salve.
  2. Avançado (Advanced) → Modo Turbo (Turbo mode): defina Ativar o Modo Turbo (Enable turbo mode) como Sim (Yes) e salve.
  3. Clique em Atualizar agora! (Update now!) em Remontar os dados dos produtos agora! (Reassemble products data now!) e mantenha a página aberta até aparecer Arquivo atualizado!!! (File updated!!!). Sem o arquivo, o filtro não consegue pesquisar.
  4. Escolha o Período do WordPress Cron (WordPress Cron period) e Onde guardar o arquivo de dados dos produtos (Where to keep products data file), e salve.
  5. Na aba Opções (Options), defina Mostrar contagem (Show count), Recontagem dinâmica (Dynamic recount) e Ocultar termos vazios (Hide empty terms), que no Modo Turbo são cópias separadas (explicado abaixo); depois limpe o cache de páginas e o de qualquer CDN.

O filtro fica acinzentado e nunca se torna clicável

A camada cinza é um elemento com a classe woof_turbo_mode_overlay. Ela cobre o filtro desde o primeiro instante, e o script do Modo Turbo a remove depois que o arquivo é carregado e as contagens são desenhadas. Se a camada permanece, esse script não terminou:

  • Scripts adiados, diferidos ou combinados. Os recursos de otimização do WP Rocket, do LiteSpeed Cache e de plugins semelhantes podem iniciar os scripts tarde, fora de ordem ou nem iniciá-los. O Modo Turbo precisa de ext/turbo_mode/js/turbo_mode.js e ext/quick_search/js/alasql/alasql.min.js, de wp-content/plugins/woocommerce-products-filter/, depois do jQuery. Exclua a pasta do plugin das opções de adiar, diferir e combinar e depois limpe todos os caches; o filtro com WP Rocket e cache explica as exclusões.
  • Um erro de JavaScript. Abra o console do navegador (F12) e recarregue a página. O primeiro erro em vermelho indica o script que interrompeu os demais.
  • Um arquivo grande em uma conexão lenta. Na aba Rede (Network), verifique o tamanho e o tempo de data_0000_xxx.json. Se o download mantém o filtro cinza por vários segundos, o catálogo é grande demais para o Modo Turbo.

Ocultar a camada com CSS (.woof_turbo_mode_overlay{display:none;}) apenas esconde o sintoma: o filtro se torna clicável, mas, sem um arquivo carregado, não consegue pesquisar.

Quando o arquivo não pode ser carregado, o filtro é substituído pelo aviso Oh no! It looks like the filter can't open the search file. Verifique se:

  • o arquivo existe. Um arquivo mantido na pasta do plugin (plugins\woocommerce-products-filter\ext\turbo_mode\data) é apagado a cada atualização do plugin, então reconstrua-o depois das atualizações, ou mantenha-o em wp-uploads\uploads_woof_turbo_mode;
  • nenhuma regra do servidor ou plugin de segurança bloqueia arquivos .json em uploads: abra diretamente o endereço do arquivo que aparece na aba Rede;
  • o endereço está correto. O plugin solicita wp-content/uploads/uploads_woof_turbo_mode/, portanto, em um subsite de multisite, ou com a pasta de uploads movida para outro lugar, a solicitação retorna 404. Nesse caso, mantenha o arquivo na pasta do plugin.

Nenhum produto encontrado ou produtos ausentes após a filtragem

O Modo Turbo retorna apenas os produtos que estão no arquivo, comparados com os dados armazenados nele. Verifique os dois pelo console do navegador, em uma página com o filtro, depois que ele for carregado:

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

Compare o primeiro número com seus produtos publicados mais as variações; com o WP-CLI, wp post list --post_type=product,product_variation --post_status=publish --format=count fornece esse valor. Se um produto retorna undefined, ele não está no arquivo. Se estiver, observe seus campos taxonomies e stock.

O arquivo está desatualizado

Produtos novos, categorias, atributos, preços e estoque alterados só chegam ao filtro na próxima reconstrução. Sinais típicos: um produto novo aparece na página da loja, mas some após o primeiro clique no filtro, termos novos mostram contagem 0, as últimas páginas da paginação ficam vazias, ou um elemento do filtro Meta adicionado depois da última reconstrução não encontra nada. Reconstrua o arquivo após importações e após alterar os elementos do filtro.

O limite de 15.000

Atualizar agora! (Update now!) para após 15.000 registros, e as variações contam. Uma loja com 2.000 produtos variáveis de oito variações cada já tem 18.000. O botão processa primeiro os produtos mais recentes, então os que ficam de fora são os mais antigos. Se o contador ao lado do botão parou em Produtos e variantes: 15000 (Products and Variants: 15000), você atingiu o limite. Aumente-o com o hook woof_turbo_mode_products_limit e reconstrua:

/*
 * 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;
});

A reconstrução agendada não é limitada por esse hook; ela processa o catálogo inteiro.

Produtos em subcategorias não são encontrados

O arquivo armazena apenas as categorias marcadas em cada produto, e o navegador as compara literalmente; ele não conhece a árvore de categorias. O WordPress mostra os produtos das subcategorias em uma categoria pai, mas o Modo Turbo não: um produto marcado apenas em Tênis de corrida aparece na página Calçados até o primeiro clique no filtro e depois desaparece, o termo Calçados do filtro não o encontra, e a contagem de Calçados o deixa de fora. Marque todos os níveis da cadeia (Calçados e Tênis de corrida) nesses produtos, por exemplo com a edição em massa em Produtos → Todos os produtos, e depois reconstrua o arquivo.

Produtos ocultos e sem estoque

Produtos cuja Visibilidade no catálogo (Catalog visibility) é Somente loja (Shop only) ou Oculto (Hidden) contam como ocultos da pesquisa, e o Modo Turbo nunca os retorna após a filtragem, seja qual for o valor de Considerar a visibilidade no catálogo (Listen catalog visibility). Um produto com Somente loja (Shop only) aparece, portanto, na página da loja e some após o primeiro clique; defina-o como Loja e resultados de pesquisa (Shop and search results) se ele deve poder ser filtrado. Com a opção do WooCommerce Ocultar itens sem estoque do catálogo (Hide out of stock items from the catalog) ativada, os produtos sem estoque ficam fora do arquivo, e um produto que volta ao estoque continua ausente até a próxima reconstrução.

Idiomas do WPML

Com o WPML, o HUSKY grava um arquivo por idioma (data_0000_en.json, data_0000_de.json) e carrega o arquivo do idioma atual. Um produto sem tradução não consta no arquivo desse idioma, então reconstrua depois de traduzir.

Como manter o arquivo de pesquisa atualizado

Atualizar agora! (Update now!) monta o arquivo em lotes de dez produtos ou variações, no máximo um lote por segundo, com um contador Produtos e variantes (Products and Variants). Cada lote reescreve o arquivo inteiro, então 15.000 registros levam pelo menos 25 minutos. Ao contrário da reconstrução agendada, o botão apaga primeiro o arquivo atual, e até ele terminar o site filtra com dados incompletos: execute-o em um horário tranquilo, mantenha a página aberta e não desative o Modo Turbo no meio do processo.

Período do WordPress Cron (WordPress Cron period) define a reconstrução automática: diário (daily), semanal (weekly) (o padrão), duas vezes por mês (twicemonthly), mensal (monthly), min1 ou sem atualização (without update). Apesar do nome, não se trata de um evento do WP-Cron. O HUSKY mantém seu próprio agendamento (a opção woof_turbo_init_wpcrone_): quando uma reconstrução está pendente, cada requisição que carrega o WordPress com o plugin, no máximo uma a cada cinco segundos, adiciona os próximos dez registros a um arquivo temporário, que substitui o arquivo em uso após o último lote. Até lá, os visitantes continuam recebendo os dados anteriores. O que decorre disso:

  • O WP Crontrol e ferramentas semelhantes não o listam, e DISABLE_WP_CRON não o interrompe.
  • A velocidade depende das requisições que chegam ao PHP; páginas servidas por um cache de páginas não contam. 20.000 registros exigem pelo menos 2.000 requisições com cinco segundos de intervalo, perto de três horas de tráfego constante, e em um site com pouco movimento, dias.
  • A primeira reconstrução automática ocorre um período completo depois de você salvar o agendamento, então clique em Atualizar agora! (Update now!) após ativar.
  • O período é contado a partir do fim da reconstrução anterior. min1 inicia a próxima um minuto depois, de modo que o site se reconstrói o tempo todo; use-o apenas em catálogos pequenos.
  • Atualizar agora! (Update now!), se clicado durante uma reconstrução automática, também apaga o arquivo temporário dela; quando a execução automática termina, ela substitui seu arquivo completo pela parte que construiu depois. Se produtos voltarem a sumir horas depois de uma reconstrução manual, clique no botão mais uma vez.

Em um site com pouco tráfego, uma tarefa cron do servidor pode fornecer as requisições; o FAQ por que as atualizações automáticas via cron falham mostra a configuração e os limites do PHP. Chame-a a cada minuto, não uma vez por dia, porque cada chamada adiciona um lote. Se você limitou o plugin com Inicializar o plugin somente nas páginas a seguir (Init plugin on the next site pages only), faça-a solicitar /wp-admin/admin-ajax.php, onde o plugin sempre é carregado. Mesmo assim, ela adiciona apenas 600 registros por hora, portanto, em catálogos que mudam em massa, clique em Atualizar agora! (Update now!) após cada importação.

Outros períodos podem ser adicionados com o hook woof_turbo_mode_schedules, sem editar arquivos do plugin; depois escolha o novo período e salve:

/*
 * 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;
});

O arquivo mantém o mesmo endereço após cada reconstrução. Se uma CDN ou o navegador fizer cache de arquivos .json, os visitantes podem continuar recebendo dados antigos: exclua a pasta uploads_woof_turbo_mode do cache da CDN ou limpe-o após as reconstruções.

O Modo Turbo exige AJAX e tem suas próprias configurações de contagem

Enquanto o Modo Turbo está ativado, o HUSKY redefine quatro configurações a cada carregamento de página: Tentar usar AJAX na loja (Try to ajaxify the shop) passa a Sim (Yes), e as opções comuns Mostrar contagem (Show count), Recontagem dinâmica (Dynamic recount) e Ocultar termos vazios (Hide empty terms) passam a Não (No). A aba Opções (Options) então mostra as cópias próprias do Modo Turbo para essas três, com os mesmos nomes, e Recontagem dinâmica (Dynamic recount) oferece Sim, para todos os dispositivos (Yes, for all devices) ou Sim, somente para PC (Yes, only for PC).

  • O AJAX não pode ser desativado enquanto o Modo Turbo estiver ativo. Defina Ativar o Modo Turbo (Enable turbo mode) como Não (No), salve e só então altere Tentar usar AJAX na loja (Try to ajaxify the shop).
  • Se a grade de produtos do tema quebrar após a filtragem por AJAX (um produto por linha, colunas perdidas, paginação quebrada), o Modo Turbo herda o problema: veja como definir o número de colunas no modo AJAX e problemas de paginação no modo AJAX, ou mantenha o Modo Turbo desativado para esse tema.
  • Depois de desativar o Modo Turbo, defina novamente Mostrar contagem (Show count), Recontagem dinâmica (Dynamic recount) e Ocultar termos vazios (Hide empty terms): elas continuam em Não (No), e é por isso que os contadores desaparecem nesse momento.
  • Ocultar termos vazios (Hide empty terms) só funciona com Mostrar contagem (Show count) e Recontagem dinâmica (Dynamic recount) ativadas; desativar Mostrar contagem (Show count) desativa as outras duas.
  • Cache do número de recontagem dinâmica para cada item no filtro (Cache dynamic recount number for each item in filter), Cache de termos (Cache terms) e Otimizar o filtro de preço (Optimize price filter) desaparecem de Avançado → Opções enquanto o Modo Turbo está ativo; elas não se aplicam a ele.

O que o Modo Turbo não consegue fazer

  • O elemento Lista suspensa hierárquica (Hierarchy drop-down) não funciona com ele, como indica a página da extensão Modo Turbo.
  • As contagens e Ocultar termos vazios (Hide empty terms) funcionam para os elementos padrão (caixa de seleção, botão de opção, listas suspensas, cor, imagem, rótulo, controle deslizante). Elementos criados com o Smart Designer não recebem contagens.
  • Em estoque (In stock) considera apenas o status de estoque do próprio produto; a configuração que verifica as variações não tem efeito, então um filtro por tamanho ainda pode mostrar variações sem estoque.
  • A pesquisa de texto compara as palavras digitadas apenas com os títulos dos produtos, mesmo que o elemento de pesquisa de texto esteja configurado para procurar nas descrições ou em outros campos. O elemento separado de SKU funciona.
  • Condições adicionadas em PHP não participam da pesquisa, porque é o navegador que decide quais produtos correspondem. Códigos personalizados em woof_products_query ou pre_get_posts, extensões personalizadas e plugins que limitam produtos por vendedor ou grupo de clientes podem, no máximo, ocultar alguns produtos encontrados depois, o que desalinha as contagens e a paginação.

Se sua loja precisa de algum desses recursos, ou se os preços e o estoque mudam a cada hora, desative o Modo Turbo e acelere o modo normal com cache.

Lista de verificação

  • Nenhum erro em vermelho no console; os scripts do plugin excluídos de adiar, diferir e combinar.
  • woof_turbo_mode_file.length corresponde aos produtos publicados mais as variações; o contador não parou no limite.
  • Arquivo reconstruído após a última importação ou alteração do filtro; cache de páginas e CDN limpos.
  • Produtos marcados em toda a cadeia de categorias, com a visibilidade Loja e resultados de pesquisa (Shop and search results).
  • Configurações de contagem definidas nas cópias do Modo Turbo e novamente após desativá-lo.

Se o filtro continuar se comportando mal, abra um tópico no fórum de suporte do HUSKY com o link da página, os erros do console, o valor de woof_turbo_mode_file.length e o número de produtos e variações da sua loja.