Shielding Shop Filters

Lightweight AJAX product category filtering for WooCommerce + Oxygen Builder. Drop-in replacement for FacetWP when you only need category filtering.

Features

• Grouped category filters — categories are organized under three section headers: Product Room, EMF Type, and Product Use Type
• Hierarchical display with expand/collapse for subcategories
• Multi-select category checkboxes with AJAX product grid refresh
• Bookmarkable/shareable URLs with selected filters
• Browser back/forward navigation support
• Debounced filtering (300ms) to batch rapid clicks
• Loading state with opacity transition
• "Clear All" button
• Pagination support
• Works with WooCommerce's default product templates
• No jQuery dependency

Installation

1. Upload the shielding-shop-filters folder to /wp-content/plugins/
2. Activate the plugin in wp-admin > Plugins
3. Deactivate FacetWP to avoid conflicts
4. Place the filter shortcode on your shop page (see below)

Usage in Oxygen Builder

1. Open the Shop page template in Oxygen
2. Add a Shortcode element where you want the filters to appear (typically in a sidebar or above the product grid)
3. Enter: [ssf_category_filters]
4. Save and publish

Category Groups

The filter widget displays categories under three hardcoded parent groups (in order):

Parent categories that have sub-children (e.g., Office → Commercial Office / Home Office) display with a [−]/[+] toggle to expand or collapse the subcategories. Groups start expanded by default.

To change the displayed groups, edit the FILTER_GROUPS constant in shielding-shop-filters.php.

Shortcode Options

[ssf_category_filters hide_empty="yes" orderby="name" show_counts="yes" exclude=""]

Customization

Change products per page

Add to your theme's functions.php:

add_filter( 'ssf_products_per_page', function() {
    return 24; // default is 12
});

Adjust product grid selector

If Oxygen uses a custom wrapper class for the product grid, edit the GRID_SELECTORS array in assets/ssf-filters.js:

const GRID_SELECTORS = [
    '.your-custom-class',
    '.products',
    // ...
];

Style overrides

Override any styles by targeting the .ssf-filters classes in your Oxygen stylesheet or custom CSS.

URL Format

Filtered URLs look like:

/shop/?_product_categories=biohacking-room,bedroom

These are shareable and bookmarkable. The plugin reads the URL parameter on page load and pre-selects the matching checkboxes.

Compatibility

• WordPress 5.8+
• WooCommerce 5.0+
• PHP 7.4+
• Oxygen Builder 3.x / 4.x
• OxyExtras Infinite Scroller (Products List mode) — re-initializes after filter changes
• jQuery is loaded as a dependency for OxyExtras infinite scroll re-init

Troubleshooting

Products don't update when clicking filters:

• Check the browser console for errors
• Verify the product grid selector matches your Oxygen layout (inspect the product grid element and check its class)
• Make sure FacetWP is deactivated

Filters don't appear:

• Make sure you added the [ssf_category_filters] shortcode to the Oxygen template
• Check that product categories exist and have products assigned
• Verify the parent category slugs (room, emf-type, use) exist in your WooCommerce product categories

A group is missing:

• The parent category slug may have changed. Check your WooCommerce product categories and update the FILTER_GROUPS constant in the PHP file.

Pagination not working:

• The plugin creates a pagination container after the product grid if one doesn't exist
• If using custom Oxygen pagination, you may need to adjust the PAGINATION_SELECTORS in the JS file

OxyExtras infinite scroll not loading more products:

• Ensure the Infinite Scroller component is set to "Products List" mode
• The plugin re-initializes infinite scroll after each filter change; if it still fails, check the browser console for errors
• Verify jQuery is loaded (required for the re-init)