Skip to main content

Search & Filtering

FacetWP v4.3.6 for faceted filtering and WP Search with Algolia v2.8.2 for instant search provide advanced product discovery.

Overview​

HHA Sports uses a dual search strategy:

  1. FacetWP - Faceted filtering on catalog/category pages
  2. Algolia - Instant search with autocomplete

Both integrate with BigCommerce products and work alongside each other.

FacetWP Integration​

Plugin: FacetWP v4.3.6
Location: wp-content/plugins/facetwp/
License: Commercial (FacetWP, LLC)

Purpose​

Provide faceted filtering for product catalogs with dynamic refinement based on attributes like brand, category, price, features, etc.

Features​

  • Multiple Facet Types - Checkboxes, dropdowns, sliders, etc.
  • Ajax Refresh - No page reload on filter changes
  • URL Parameters - SEO-friendly filter URLs
  • Result Count - Display number of matching products
  • Pagination - Integrated with filtered results
  • Template Overrides - Custom result displays

Add-On Plugins​

FacetWP Cache v1.x​

Location: wp-content/plugins/facetwp-cache/

Caches facet data and results for improved performance.

FacetWP Range List v1.x​

Location: wp-content/plugins/facetwp-range-list/

Custom facet type for displaying ranges as list items instead of sliders.

Theme Integration​

Location: wp-content/themes/suma-elementor/inc/integrations/class-facetwp.php

Theme customizations include:

  • Custom facet templates
  • Result count display
  • Pagination styling
  • Mobile optimizations
  • JavaScript configuration

FacetWP Configuration Object​

Theme provides configuration via SUMA.facetwp JavaScript object:

window.SUMA = {
    facetwp: {
        // Custom configuration
        // Loaded via wp_localize_script
    }
};

Custom Elementor Widgets​

Location: wp-content/themes/suma-elementor/inc/widgets/

FacetWP-specific widgets:

  • category-facets - Category filter display
  • facet-list - Generic facet list
  • facet-mobile-button - Mobile filter toggle
  • facet-pagination - Pagination controls

Common Facet Types​

Checkboxes​

Filter by multiple selections (brand, color, features, etc.)

Single selection (sort order, category)

Slider​

Numeric range (price, size)

Range List (Add-On)​

Discrete value selection (shoe sizes, shirt sizes)

Configuration​

Admin Location: Settings → FacetWP

Facet Setup​

  1. Create facets (Settings → FacetWP → Facets)
  2. Name, label, data source, facet type
  3. Display settings
  4. Advanced settings (URL, indexing)

Template​

  1. Create template (Settings → FacetWP → Templates)
  2. Query settings (post type, taxonomy, etc.)
  3. Template code (PHP/HTML)
  4. Pagination settings

Settings​

  • Prefix: URL parameter prefix (default: _)
  • Load Assets: Where to load FacetWP CSS/JS
  • Debug Mode: Enable for troubleshooting

Usage​

Display Facets​

<?php echo facetwp_display('facet', 'brand'); ?>
<?php echo facetwp_display('facet', 'price'); ?>
<?php echo facetwp_display('facet', 'category'); ?>

Display Template​

<?php echo facetwp_display('template', 'products'); ?>

Display Pagination​

<?php echo facetwp_display('pager'); ?>

JavaScript Events​

// Before facet refresh
$(document).on('facetwp-loaded', function() {
    // Custom code after results load
});

// Before facet refresh
$(document).on('facetwp-refresh', function() {
    // Custom code before results refresh
});

Filters & Hooks​

facetwp_preload_force_query​

Applied in theme: __return_true

Forces FacetWP to always run the query (for better integration with other plugins).

Custom Facet Templates​

Theme can override facet display via facetwp_facet_html filter.

Integration with BigCommerce​

FacetWP indexes BigCommerce product data:

  • Product taxonomies - Categories, brands, flags
  • Post meta - Price, SKU, custom fields
  • ACF fields - Custom product attributes

Mobile Optimization​

facet-mobile-button widget - Toggle filter panel on mobile

Typical implementation:

  1. Hide facets on mobile by default
  2. Show floating button to open filter panel
  3. Slide-in panel with facets
  4. Apply filters and close panel

Caching Considerations​

FacetWP Cache add-on caches:

  • Facet choices (what options are available)
  • Result counts (how many products match)
  • Query results (matching product IDs)

Cache invalidated on:

  • Product import/update
  • Manual cache clear
  • Configured expiration time

Algolia Integration​

Plugin: WP Search with Algolia v2.8.2
Location: wp-content/plugins/wp-search-with-algolia/
Author: WebDevStudios
License: GPLv2 / MIT

Purpose​

Provide instant search with autocomplete, typo tolerance, and synonym support using Algolia's hosted search service.

Features​

  1. Instant Search - Results as you type
  2. Autocomplete - Dropdown suggestions
  3. Typo Tolerance - Handles misspellings
  4. Faceted Search - Filter results on search page
  5. Synonyms - Configure word equivalents
  6. Analytics - Search performance tracking
  7. Multi-Index - Search multiple content types

Theme Integration​

Location: wp-content/themes/suma-elementor/inc/integrations/class-algolia.php

Theme customizations:

  • Custom search templates
  • Result styling
  • InstantSearch configuration
  • Autocomplete customization

Conditional Loading​

Theme loads Algolia scripts only on search pages:

if (defined('ALGOLIA_VERSION') && is_search()) {
    wp_enqueue_script('algolia-instantsearch');
    wp_enqueue_style('algolia-instantsearch');
}

Custom Elementor Widgets​

Location: wp-content/themes/suma-elementor/inc/widgets/

Algolia-specific widgets:

  • algolia-autocomplete - Search autocomplete dropdown
  • algolia-catalog - Product catalog search
  • algolia-instantsearch - Live search results
  • algolia-posts - Post search results
  • algolia-search - Generic search interface
  • suma-search-form - Custom search form

Suma Patches Integration​

Location: wp-content/plugins/suma-patches/inc/class-algolia.php

Additional Algolia customizations in Suma Patches plugin.

Configuration​

Admin Location: Algolia Search → Settings

API Credentials​

  1. Application ID - Algolia app ID
  2. Search-Only API Key - Public search key
  3. Admin API Key - Private indexing key

Indexing​

  1. Indices - Which content to index (products, posts, pages)
  2. Searchable Attributes - Which fields to search
  3. Custom Ranking - Relevance ordering
  4. Synonyms - Configure word equivalents

Autocomplete​

  1. Max Suggestions - Number of results in dropdown
  2. Powered By - Display Algolia branding
  3. Customize Templates - HTML/JS templates

InstantSearch​

  1. Enable - Turn on instant search
  2. Customize - Layout, styling, filters
  3. Facets - Available filters

Usage​

Autocomplete​

Replace default WordPress search with Algolia autocomplete:

<?php echo do_shortcode('[algolia_autocomplete]'); ?>

Or use Elementor widget: algolia-autocomplete

InstantSearch​

Display instant search results:

<?php echo do_shortcode('[algolia_instantsearch]'); ?>

Or use Elementor widget: algolia-instantsearch

JavaScript API​

// Custom autocomplete sources
wp.algolia.autocomplete.sources.push({
    source: function(query, callback) {
        // Custom source logic
    }
});

// InstantSearch configuration
wp.algolia.instantsearch.config = {
    // Custom config
};

Indexing​

Manual Indexing​

Admin Location: Algolia Search → Indexing

Click "Re-index" for each index.

Automatic Indexing​

Plugin automatically indexes when:

  • Posts/products created or updated
  • Content deleted
  • Bulk operations

WP-CLI Commands​

# Re-index all
wp algolia reindex

# Index specific content type
wp algolia reindex --indices=posts

# Clear index
wp algolia clear

Integration with BigCommerce​

Algolia indexes BigCommerce products:

  • Product title
  • Product description
  • SKU
  • Brand
  • Categories
  • Price
  • Custom fields

Searchable Attributes (configured in Algolia dashboard):

  • post_title
  • content
  • taxonomies.bigcommerce_brand
  • taxonomies.bigcommerce_category
  • meta.sku

Search Page​

Default WordPress Search: Replaced with Algolia InstantSearch

Template: search.php or custom template

Features:

  • Instant results as you type
  • Faceted filters (brand, category, price)
  • Pagination
  • Result count
  • Sorting options

Autocomplete Customization​

Template Location: Theme or plugin override

Customize HTML/CSS for autocomplete dropdown:

  • Suggestion templates
  • Section headers
  • Powered by Algolia logo
  • Keyboard navigation

Synonyms​

Algolia Dashboard: Configure synonyms for better results

Examples:

  • bow sight ⇔ bowsight
  • range finder ⇔ rangefinder
  • sight pins ⇔ pins

Analytics​

Algolia Dashboard: View search analytics

Metrics:

  • Top searches
  • No results searches
  • Click-through rate
  • Conversion rate

Search Strategy Comparison​

When to Use FacetWP​

✅ Use FacetWP for:

  • Product catalog/category pages
  • Faceted filtering (brand, price, features)
  • Complex attribute combinations
  • Known category browsing
  • Visual product exploration

When to Use Algolia​

✅ Use Algolia for:

  • Site-wide search
  • Search bar autocomplete
  • Typo-tolerant search
  • Synonym support
  • Fast results (hosted service)
  • Analytics and insights

Using Both Together​

Recommended Setup:

  1. Homepage/Header: Algolia autocomplete search
  2. Category Pages: FacetWP faceted filtering
  3. Search Results Page: Algolia InstantSearch
  4. Product Catalogs: FacetWP with category navigation

Both can coexist without conflict as they target different use cases.

Performance Considerations​

FacetWP Performance​

Optimization Tips:

  1. Enable FacetWP Cache add-on
  2. Limit number of facets on page
  3. Use efficient facet types (avoid slider for large ranges)
  4. Index only necessary data
  5. Preload queries with facetwp_preload_force_query

Caching:

  • FacetWP Cache add-on (installed)
  • Page caching (exclude FacetWP URLs)
  • Object caching (Redis/Memcached)

Algolia Performance​

Built-in Speed:

  • Algolia is hosted service (fast by design)
  • CDN distribution
  • Optimized indexing
  • Real-time updates

Optimization Tips:

  1. Limit searchable attributes
  2. Use custom ranking appropriately
  3. Index only published content
  4. Configure typo tolerance levels
  5. Use distinct for duplicate prevention

Troubleshooting​

FacetWP Issues​

Facets Not Updating​

  1. Check FacetWP indexing complete
  2. Verify facet data source correct
  3. Clear FacetWP cache
  4. Check for JavaScript errors
  5. Ensure AJAX requests succeeding

Slow Performance​

  1. Enable FacetWP Cache
  2. Reduce number of facets
  3. Optimize database queries
  4. Check server resources
  5. Review facet configuration

No Results Displaying​

  1. Verify template query correct
  2. Check post type and taxonomy settings
  3. Review indexed data
  4. Check facet selections are valid
  5. Test without any facets selected

Algolia Issues​

Search Not Working​

  1. Verify API credentials correct
  2. Check indices exist in Algolia dashboard
  3. Ensure content indexed
  4. Review searchable attributes
  5. Check for JavaScript errors

Autocomplete Not Showing​

  1. Verify autocomplete enabled
  2. Check search input has correct attributes
  3. Ensure Algolia scripts loaded
  4. Review browser console for errors
  5. Test with default theme

Index Out of Sync​

  1. Re-index content manually
  2. Check automatic indexing enabled
  3. Review indexing log for errors
  4. Verify API credentials have write access
  5. Clear and rebuild indices