AJAX filters

Los filtros AJAX permiten a los clientes acotar la lista de productos sin recargar la página. Los productos se actualizan en vivo tras seleccionar los filtros.

Activación del módulo

Ve a WooCommerce > Polski > Módulos de la tienda y activa la opción AJAX Filters. El módulo proporciona los filtros como bloque de Gutenberg, shortcode y widget.

Tipos de filtros disponibles

Categorías

Filtro jerárquico con un árbol de categorías desplegable. Junto a cada categoría se muestra el número de productos. Las categorías vacías se ocultan de forma predeterminada.

Opciones:

• Mostrar como árbol o como lista plana
• Selección múltiple (casillas) o única (radio)
• Contraer/expandir subcategorías

Marcas (fabricantes)

Filtro por fabricante/marca. Requiere el módulo Fabricante activo en Polski for WooCommerce. Muestra una lista de marcas con el número de productos.

Precio

Control deslizante de rango de precios con campos mín./máx. El rango se ajusta automáticamente a los productos mostrados en ese momento.

Opciones:

• Control deslizante
• Campos de texto mín./máx.
• Rangos de precio (p. ej. 0-50 PLN, 50-100 PLN, 100+ PLN)

Configuración de los rangos de precio:

add_filter('polski/ajax_filters/price_ranges', function (): array {
    return [
        ['min' => 0, 'max' => 50, 'label' => 'Up to 50 PLN'],
        ['min' => 50, 'max' => 100, 'label' => '50 - 100 PLN'],
        ['min' => 100, 'max' => 200, 'label' => '100 - 200 PLN'],
        ['min' => 200, 'max' => 0, 'label' => 'Above 200 PLN'],
    ];
});

Estado de stock

Filtro que permite mostrar solo los productos disponibles en stock. Opciones:

• En stock - productos con stock_status = instock
• Bajo pedido - productos con stock_status = onbackorder
• Sin stock - productos con stock_status = outofstock (ocultos de forma predeterminada)

Oferta

Casilla Solo productos en oferta - filtra únicamente los productos con un precio de oferta activo.

Atributos de producto

Filtros dinámicos generados automáticamente a partir de los atributos de WooCommerce (color, talla, material, etc.). Cada atributo global puede usarse como filtro.

Tipos de visualización de atributos:

• Lista de casillas - predeterminado
• Muestras de color - para atributos con colores definidos
• Botones - selección compacta (p. ej. tallas S, M, L, XL)
• Desplegable - lista desplegable

Comportamiento AJAX

Tras cambiar cualquier filtro:

1. Se envía una solicitud AJAX con los parámetros seleccionados
2. Se muestra un discreto spinner/skeleton en la lista de productos
3. La lista de productos se actualiza sin recargar la página
4. Los contadores de productos en los filtros se actualizan
5. Las opciones de filtro no disponibles se atenúan (pero no se ocultan)
6. La URL en el navegador se actualiza con los parámetros GET (History API)

Fallback GET (sin JavaScript)

El módulo admite un modo de fallback sin JavaScript. Cuando JS está desactivado o no está disponible:

• Los filtros funcionan como un formulario HTML estándar con parámetros GET
• Tras el envío, la página se recarga con la lista de productos filtrada
• Los parámetros de filtro se guardan en la URL, p. ej.: ?pa_color=red&min_price=50&max_price=200
• Las URL filtradas son compatibles con SEO y pueden ser indexadas por los motores de búsqueda

El modo de fallback funciona de forma automática - no requiere configuración adicional.

Bloque de Gutenberg

El bloque Polski - AJAX Filters está disponible en el editor de Gutenberg. Colócalo en la barra lateral de la página de la tienda.

Opciones del bloque:

• Tipos de filtro - elige qué filtros mostrar
• Orden de los filtros - ordenación por arrastrar y soltar
• Estilo - compacto, expandido, acordeón
• Botón de reinicio - mostrar/ocultar el botón “Borrar filtros”
• Contadores - mostrar/ocultar el número de productos de cada opción
• Contracción - secciones contraídas/expandidas de forma predeterminada

Shortcode [polski_ajax_filters]

Parámetros

Parámetro	Tipo	Predeterminado	Descripción
filters	string	all	Tipos de filtro (separados por comas)
style	string	expanded	Estilo: expanded, compact, accordion
show_count	string	yes	Mostrar contadores de productos
show_reset	string	yes	Mostrar botón de reinicio
columns	int	1	Número de columnas de filtros
ajax	string	yes	Modo AJAX (no = solo GET)

Ejemplo de uso

[polski_ajax_filters filters="category,price,pa_color,stock" style="accordion" show_count="yes"]

Filtrado solo por atributos

[polski_ajax_filters filters="pa_color,pa_size,pa_material" style="compact"]

Colocación en la barra lateral del tema

En el archivo sidebar.php o en los widgets:

echo do_shortcode('[polski_ajax_filters filters="category,price,stock,sale"]');

Integración con la paginación

Los filtros AJAX funcionan con la paginación de WooCommerce. Tras cambiar un filtro, el usuario vuelve a la página 1 de los resultados. La paginación también funciona en modo AJAX - navegar entre páginas no restablece los filtros seleccionados.

Filtros activos

Los filtros activos se muestran sobre la lista de productos como etiquetas (chips). Cada etiqueta tiene un botón X para eliminar un solo filtro. El botón Borrar todo restablece todos los filtros a la vez.

// Cambiar la posición de la barra de filtros activos
add_filter('polski/ajax_filters/active_position', function (): string {
    return 'above_products'; // o 'below_filters', 'both'
});

Rendimiento

Las consultas de filtro utilizan los índices de la base de datos de WooCommerce (product_meta_lookup). Para tiendas con un gran número de productos (10.000+), se recomienda usar una caché de objetos (Redis/Memcached).

Los resultados del filtrado se almacenan en caché en la Transient API con una clave basada en el hash de los parámetros de filtro. La caché se vacía cuando cambian el precio, el estado de stock o los atributos de un producto.

Estilos CSS

• .polski-ajax-filters - contenedor de filtros
• .polski-ajax-filters__section - sección de un solo filtro
• .polski-ajax-filters__title - encabezado de la sección
• .polski-ajax-filters__option - opción de filtro (casilla/radio)
• .polski-ajax-filters__count - contador de productos
• .polski-ajax-filters__reset - botón de reinicio
• .polski-ajax-filters__active - barra de filtros activos

Resolución de problemas

Los filtros no actualizan la lista de productos - asegúrate de que el selector CSS de la lista de productos sea correcto. De forma predeterminada, el módulo busca .products o ul.products. Los temas personalizados pueden usar un selector diferente.

Los contadores muestran 0 - comprueba que los productos tengan atributos, categorías y estado de stock asignados. Un atributo vacío no se contará.

El control deslizante de precio no funciona - comprueba si hay un conflicto de jQuery UI con otro plugin en la página.

Informar de problemas: github.com/wppoland/polski/issues

Esta página tiene únicamente fines informativos y no constituye asesoramiento legal. Consulta a un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) proporcionado sin garantía.