Filtros por Facetas AJAX para PrestaShop: documentação

Este guia cobre a instalação, a configuração e a exploração do módulo Filtros por Facetas AJAX para PrestaShop 8 e 9. O módulo substitui a pesquisa por facetas nativa por uma navegação AJAX mais rápida, um slider de preço com histograma e um controlo fino da indexação SEO das páginas filtradas.

Instalação

A partir do seu back-office, abra Módulos > Gestor de módulos, clique em Instalar um módulo e carregue o ficheiro dffacetedfilter.zip. Na instalação, o módulo efetua automaticamente três ações:

• cria as suas tabelas e o seu separador de administração;
• sincroniza uma primeira vez as facetas a partir do seu catálogo;
• pré-aquece o índice de preços (dentro do limite de alguns segundos).

Primeira configuração

Vá a Catálogo > Filtros por facetas. Encontra aí a lista das facetas, um painel de síntese e as definições gerais e SEO.

Sincronizar as facetas

O botão Sincronizar a partir do catálogo cria automaticamente as facetas em falta a partir dos seus grupos de atributos, das suas características e das facetas integradas (preço, marca, promoções, disponibilidade, estado). As facetas existentes nunca são modificadas: pode relançar a sincronização sem risco depois de ter adicionado um atributo ou uma característica.

Reconstruir o índice de preços

O botão Reconstruir o índice de preços recalcula os limites de preço de todos os produtos, por lotes, com uma barra de progresso. Lance-o depois da instalação e depois de qualquer importação massiva de produtos.

Gerir as facetas

Cada linha da lista pode ser reordenada por arrastar e largar (a ordem define a ordem de apresentação no front-office e a ordem normalizada dos URLs), ativada ou desativada, e editada.

Opções de uma faceta

• Designação: o nome apresentado, traduzível por idioma.
• Apresentação: caixas de seleção, pastilhas de cor / textura, ou ligações simples. Os grupos de cores herdam automaticamente a apresentação em pastilhas.
• Seleção múltipla: autoriza a seleção simultânea de vários valores de uma mesma faceta, combinados por um OU.
• Mostrar os contadores: mostra o número de produtos em frente de cada valor.
• Ocultar os valores vazios: oculta os valores com zero produtos em vez de os mostrar a cinzento.
• Recolhida por defeito: a faceta aparece fechada, o visitante expande-a ao clicar.
• Valores antes de « Ver mais »: número de valores visíveis antes do botão de expansão (0 = mostrar tudo).

O slider de preço e o seu índice

A faceta Preço aparece sob a forma de um cursor duplo. Acima, um histograma de repartição dos produtos em doze intervalos ajuda o visitante a situar os preços. Estes dados provêm de um índice de preços dedicado, distinto das tabelas do PrestaShop, para se manter rápido mesmo num grande catálogo.

Manutenção do índice

O índice é atualizado em tempo real por hooks quando um produto, um preço específico ou uma declinação muda. Para uma reconstrução completa agendada, use o endpoint cron apresentado no back-office:

/module/dffacetedfilter/cron?token=O_SEU_TOKEN

A chamada processa o índice por fatias com um limite de tempo de cerca de 20 segundos; se restarem produtos, a resposta fornece o URL de continuação a chamar de novo. Uma chamada noturna diária basta na maioria dos casos.

A faceta Promoções

A faceta Em promoção filtra os produtos atualmente com desconto: produtos marcados « em saldos » ou cobertos por um preço específico ativo (desconto em curso, dentro do intervalo de datas, para a moeda, o país e o grupo atuais). É criada ativada por defeito na sincronização.

Disponibilidade e estado

Duas facetas integradas complementares são criadas desativadas, a ativar consoante as suas necessidades:

• Disponibilidade: um valor « Em stock » que tem em conta a sua definição de encomenda em rutura de stock.
• Estado: novo, usado, recondicionado.

Restringir uma faceta a categorias

Por defeito, uma faceta aparece em todas as páginas de listagem. O formulário de edição disponibiliza dois campos para mudar isso: uma regra de categorias e a árvore de categorias a que ela se aplica.

• Mostrar apenas nas categorias abaixo: a faceta aparece unicamente nas categorias marcadas e nas suas subcategorias. É a definição certa para mostrar « Número » apenas em Calçado, ou « Tamanho do ecrã » apenas em Tecnologia.
• Mostrar em todo o lado exceto nas categorias abaixo: a faceta aparece em toda a loja, exceto nas categorias marcadas e nas suas subcategorias. É a definição certa para ocultar « Tipo de vinho » em Vinhos Tintos e Vinhos Brancos, onde a faceta nada acrescenta, mantendo-a em todo o resto.

O SEO das facetas

É um dos pontos fortes do módulo: decide precisamente que páginas filtradas podem ser indexadas. Os URLs de filtros são legíveis e seguem o formato:

/categoria?dff=cor:vermelho,azul-marinho/preco:10,50/marca:nike

O parâmetro chama-se q em vez de dff no modo Creative Elements completo; o formato em si é idêntico. As facetas são separadas por uma barra, o slug da faceta e os seus valores por dois pontos, e os valores entre si por uma vírgula. A ordem das facetas e a ordenação dos valores são normalizadas para que uma mesma combinação produza sempre um único URL canónico.

Definições SEO

• Indexável (por faceta): uma faceta não indexável força a página filtrada em noindex, follow e acrescenta rel="nofollow" nas suas ligações.
• Número máx. de valores indexáveis: acima deste limiar de valores selecionados, a página passa a noindex, follow. O valor 1 é o mais seguro contra a explosão do orçamento de rastreio.
• Canonical automático nas páginas indexáveis: as páginas indexáveis recebem uma etiqueta canonical que aponta para o seu próprio URL de filtro normalizado. O canonical do tema é retirado do lado do front-office para evitar duplicados.
• Passar tudo a noindex: força o noindex, follow em todas as páginas filtradas, quaisquer que sejam as definições por faceta.

Modos AJAX

A definição Modo AJAX determina como a página se atualiza ao clicar num filtro:

• Tema (eventos nativos), recomendado: o módulo emite o evento nativo do PrestaShop e deixa o núcleo e o tema atualizar a lista, as facetas e o histórico do navegador. É o modo mais compatível com os temas baseados no classic.
• Autogerido: para os temas não padrão, o próprio módulo recupera a página em AJAX e substitui os blocos em causa. A usar apenas se o modo Tema não atualizar corretamente a página.

Manter os robôs longe dos filtros

Uma etiqueta noindex impede a indexação, não o carregamento: o robô tem de descarregar primeiro a página para ler a etiqueta. Para que deixe de carregar as combinações de filtros, não as pode descobrir. Duas definições tratam disso, em Catálogo > Filtros por facetas.

• Ligações de filtros rastreáveis: Apenas facetas indexáveis mantém uma ligação real nas facetas que declarou indexáveis e transforma as restantes em ligações geridas por JavaScript. Os seus clientes clicam exatamente como antes, mas os robôs deixam de encontrar essas combinações na página.
• Antigos URLs de filtros nativos (?q=): os URLs deixados pela pesquisa por facetas nativa do PrestaShop, do tipo ?q=Marca-..., podem receber uma resposta 410 Gone antes mesmo de começar uma consulta ao catálogo, ou um redirecionamento 301 para a listagem sem filtros. A 410 é a resposta menos dispendiosa para o servidor e aquela que faz os motores abandonarem o URL. Esta definição não se aplica nem no modo Creative Elements completo, onde q é o parâmetro do módulo, nem na página de pesquisa.

Painel de filtros móvel e filtros ativos

Abaixo de certa largura de ecrã, a barra de filtros é ocultada e abre-se como painel a partir de um botão « Filtros ». A definição Painel de filtros abaixo de (px) fixa esse limiar: 767 corresponde aos telemóveis, 1024 serve quando o seu layout também desloca a coluna de filtros em tablet. O painel fecha-se com o botão « Ver os resultados », com um clique fora ou com a tecla Escape.

A definição Etiqueta dos filtros ativos escolhe o que cada filtro ativo mostra: a faceta e o valor (« Cor: Vermelho ») ou apenas o valor (« Vermelho »). Os leitores de ecrã recebem sempre ambos.

Compatibilidade com o Creative Elements

O Creative Elements (WebshopWorks) não lê o bloco de facetas renderizado por um módulo. Os seus widgets Filtros e Filtros ativos, e o seu botão Filtros móvel, reconstroem o seu próprio código a partir da coleção de facetas nativa transportada pelo resultado de pesquisa. Desde a versão 1.3 o módulo publica essa coleção: os três widgets funcionam e conservam todos os seus controlos de design, pastilhas de cor e slider de preço incluídos.

As duas definições

Em Catálogo > Filtros por facetas > Compatibilidade com o Creative Elements:

• Modo de compatibilidade: Completo, quando o Creative Elements está instalado, Completo, sempre, Parcial ou Desativado. O modo completo usa os widgets de filtros do Creative Elements e URLs em ?q=; o modo parcial mantém os URLs em ?dff= e usa os blocos do módulo (ver abaixo).
• Bloco de filtros renderizado por: Automático entrega a barra lateral ao Creative Elements nas listagens cujo modelo ele controla, e conserva o bloco do módulo em todo o resto. Escolha Este módulo se o seu modelo de listagem do Creative Elements não tiver widget Filtros e preferir a barra lateral da DataFirefly.

No modo completo, o parâmetro de URL passa a q

O Creative Elements tem o parâmetro q escrito de forma fixa, tanto nos seus widgets como no script do seu slider de preço. No modo completo o módulo alinha-se portanto por q em vez de dff:

/categoria?q=cor:vermelho,azul-marinho/preco:10,50/marca:nike

O formato em si não muda, apenas o nome do parâmetro. Os URLs já gerados com dff são redirecionados com um 301 para o seu equivalente em q: nada do que foi indexado ou guardado nos favoritos se perde.

Modo parcial: manter os URLs em dff

No modo parcial, o módulo não publica as suas facetas para os widgets de filtros do Creative Elements, que ficam vazios, e os URLs mantêm o parâmetro ?dff=. Em vez disso, coloca os blocos do módulo no seu modelo de listagem com o widget Módulo do Creative Elements: selecione o módulo e escreva um destes nomes de hook.

• displayDffFacets: a barra de filtros (também é o que aparece se o campo hook ficar vazio);
• displayDffActiveFilters: os filtros ativos e a ligação « Limpar tudo »;
• displayDffFiltersButton: um botão « Filtros » que abre o painel móvel.

Para manter o controlo sobre o design do botão, também pode usar um widget Botão do Creative Elements e dar-lhe a classe CSS dff-open-filters no separador Avançado: passa a abrir o mesmo painel. Os widgets do Creative Elements de lista de produtos, paginação, ordenação e contador continuam a funcionar normalmente. Em contrapartida, o aspeto dos filtros define-se pela cor de destaque do módulo e pelo seu próprio CSS, e não pelo separador Estilo do Creative Elements.

Bom saber

• Mantenha o modo AJAX « Tema ». O Creative Elements assenta no evento nativo do PrestaShop e devolve os seus próprios blocos renderizados; o modo autogerido não saberia substituí-los.
• A partir do Creative Elements 3.x, as ligações das facetas deixam de ser ligações reais e passam a elementos governados por JavaScript. É uma boa notícia para o seu orçamento de rastreio: as combinações de filtros deixam de ser descobertas por um robô. Em contrapartida, a filtragem passa a depender estritamente de JavaScript dentro da sua interface.
• Evite o caráter / na designação da sua faceta Preço: o slider do Creative Elements constrói o seu URL no navegador a partir dessa designação.

Cache dos contadores

O cálculo dos contadores disjuntivos pode ser custoso num grande catálogo. O módulo guarda o seu resultado em cache durante uma curta duração configurável (300 segundos por defeito). Esta cache é invalidada automaticamente a cada alteração do catálogo e a cada modificação de uma faceta. Um botão Limpar a cache dos contadores está disponível no back-office.

Estatísticas de utilização

O painel, no topo da página de administração, resume a atividade dos últimos 30 dias: produtos indexados, número de visualizações de páginas filtradas, parte do orçamento de rastreio mantida fora do índice (páginas filtradas servidas em noindex) e uma classificação das facetas mais usadas. O tráfego dos robôs é excluído destes números, que descrevem portanto o comportamento dos seus clientes. Pode desativar o registo das estatísticas nas definições de desempenho.

Páginas suportadas

As facetas aplicam-se às páginas de categoria, marca, fornecedor, novidades, mais vendidos, promoções e resultados de pesquisa (respeitando a classificação nativa do PrestaShop). A faceta Marca é automaticamente ocultada numa página de marca, e a faceta de restrição por categoria numa página de pesquisa.

Desativar a pesquisa por facetas nativa

O módulo tem prioridade sobre o ps_facetedsearch, mas recomendamos desativar este último para evitar um duplo trabalho de indexação. Um aviso lembra-o disso no back-office se continuar ativo.

Resolução de problemas

• As facetas não aparecem: lance uma sincronização, verifique que pelo menos uma faceta está ativa e que está numa página de listagem suportada.
• O slider de preço está ausente: reconstrua o índice de preços; a faceta Preço fica oculta enquanto o índice estiver vazio para a categoria apresentada.
• A página não se atualiza em AJAX: passe o modo AJAX a « Autogerido » se o seu tema não seguir o padrão do PrestaShop.
• Após um clique as caixas não ficam marcadas e um segundo filtro substitui o primeiro: corrigido na 1.4.3. O bloco de facetas não era atualizado após a filtragem AJAX. Na consola do navegador, dffFaceted.listening() deve devolver true.
• No telemóvel os filtros aparecem por baixo da lista de produtos: corrigido na 1.4.1 para os temas Bootstrap 5 como o Hummingbird. Verifique também a definição do limiar do painel.
• A ordem das facetas não é guardada: corrigido na 1.3.1. Antes dessa versão, o PrestaShop enviava os dados do arrastar e largar sob uma chave que o módulo não lia; a notificação anunciava um sucesso mas nada era escrito.
• Uma faceta aparece numa categoria que desmarquei: desmarcar não oculta. Marque essa categoria e escolha a regra « Mostrar em todo o lado exceto nas categorias abaixo ».
• Os widgets do Creative Elements ficam vazios: no modo completo, verifique que o modo de compatibilidade está numa das opções « Completo » e que o módulo está no modo AJAX « Tema ». No modo parcial isso é normal: esses widgets são substituídos pelos blocos do módulo colocados com o widget Módulo.
• A barra de filtros aparece duas vezes: o seu modelo do Creative Elements contém um widget Filtros e o módulo renderiza também o seu. Ponha Bloco de filtros renderizado por em Automático ou Widget do Creative Elements.
• Demasiadas páginas indexadas: baixe o número máx. de valores indexáveis, torne não indexáveis as facetas de forte cardinalidade (cor, tamanho), ou ative « Passar tudo a noindex » enquanto retoma o controlo.

O código-fonte é fornecido sem cifragem. Beneficia de 12 meses de atualizações de compatibilidade e de um suporte em 24 h.

Novidades da versão 1.4

Modo Creative Elements parcial

Os URLs mantêm ?dff=, e os filtros, filtros ativos e botão móvel do módulo colocam-se no layout com o widget Módulo do Creative Elements. Ver a secção Compatibilidade com o Creative Elements.

Controlo do rastreio

As ligações de facetas podem ser reservadas às facetas indexáveis, e os antigos URLs ?q= da pesquisa nativa podem receber uma 410 antes de qualquer consulta ao catálogo. Ver a secção Manter os robôs longe dos filtros.

Painel móvel e filtros ativos

O painel de filtros móvel deixou de depender das classes utilitárias do tema, ausentes dos temas Bootstrap 5 como o Hummingbird, e segue um limiar de largura configurável. Os filtros ativos podem mostrar apenas o valor.

Atualização AJAX

O módulo atualiza ele próprio as facetas e os filtros ativos após cada filtragem, sem depender dos seletores do tema. Foram corrigidos dois defeitos que impediam essa atualização: a subscrição aos eventos do PrestaShop acontecia demasiado cedo para resultar (1.4.3), e a mudança automática para o modo autónomo ao fim de 900 ms deixava os widgets do page builder no estado anterior (1.4.1).

Novidades da versão 1.3.1

Duas correções assinaladas em produção.

A ordem das facetas é guardada. O PrestaShop envia os dados do arrastar e largar sob o identificador sem o prefixo id_, ou seja facet, e não sob o nome da tabela. O módulo lia a chave errada e não escrevia nada, enquanto o navegador continuava a mostrar uma confirmação. A ordem é agora reconstruída por completo a partir da lista recebida, o que torna a escrita idempotente, e a chamada devolve um estado real.

Regra de categorias « exceto ». A restrição por categorias era apenas uma lista branca: podia-se limitar uma faceta a certas categorias, nunca excluí-la delas. Ver a secção Restringir uma faceta a categorias acima.

Novidades da versão 1.3

Compatibilidade com o Creative Elements

O módulo publica agora as suas facetas sob a forma de coleção nativa, a estrutura que o page builder espera. Os seus widgets Filtros, Filtros ativos e Limpar, e o seu botão Filtros móvel, funcionam com o módulo e conservam todos os seus controlos de design. Ver a secção Compatibilidade com o Creative Elements acima, em particular a mudança de nome do parâmetro de URL.

Desempenho sob o tráfego dos robôs

A navegação por facetas desmorona-se sob o tráfego automatizado porque cada combinação distinta é uma falha de cache. Esta versão elimina o trabalho por pedido que não depende da seleção:

• Mapas de valores partilhados: os valores possíveis de cada faceta dependem do catálogo, não da seleção. São carregados a partir de uma única entrada de cache em vez de uma consulta e vários acessos a disco por faceta em cada página.
• Cache dos contadores protegida: acima de três facetas ou seis valores, uma combinação é calculada mas já não guardada. São essas que os robôs geram, nunca são relidas e guardá-las apenas inchava a tabela. Ambos os limiares são configuráveis.
• Visibilidade do catálogo: a subconsulta de controlo dos grupos de clientes, antes repetida dentro de cada consulta de contagem, desaparece nas páginas de categoria quando nenhuma categoria ativa está restringida para os grupos do visitante.
• Landing pages sem consulta: o conjunto dos destinos ativos é mantido sob a forma de índice compacto, pelo que a resposta negativa, de longe a mais frequente, não custa nada.
• Estatísticas: nenhuma escrita para os robôs.

Novidades da versão 1.2

Landing pages SEO

Em Catálogo > Filtros por facetas > Landing pages SEO, transforme uma combinação de filtros precisa (por exemplo Sapatos × Cor: vermelho × Marca: Nike) numa verdadeira página de destino: meta title, meta description, H1 e introdução editorial, por idioma. Para visar uma combinação, copie o valor do parâmetro dff (ou q no modo Creative Elements completo) a partir de um URL filtrado da sua loja e cole-o no formulário.

Todas as landings ativas são listadas num sitemap XML dedicado, com alternates hreflang, pronto a submeter na Search Console:

/module/dffacetedfilter/sitemap

Outras novidades

• Faceta Subcategorias: propõe as subcategorias diretas da categoria apresentada; a listagem inclui então automaticamente toda a subárvore.
• Ordenação de valores por faceta: posição de catálogo, alfabética ou número de produtos decrescente.
• Amostras de cor em grelha ou lista: cada faceta de cor pode surgir como grelha horizontal de amostras ou lista vertical com etiquetas e contadores.
• Ocultar facetas com um único valor: uma faceta cujo único valor cobre toda a listagem não acrescenta poder de filtragem; esta definição retira-a automaticamente.
• Cor de destaque: escolha no seletor a cor das caixas marcadas, interruptores, slider e distintivos; o contraste do texto é calculado automaticamente.
• AJAX resiliente: se o tema não responder ao evento nativo, o módulo muda automaticamente para o modo autogerido; a posição de scroll é preservada após cada filtragem e os filtros móveis abrem num modal em ecrã inteiro.
• 8 idiomas no front: PT, EN, FR, ES, DE, IT, PL, NL incluídos no módulo.