Custom WooCommerce Search Plugin - User Guide

Overview

The Custom WooCommerce Search plugin provides an advanced, feature-rich search interface for WooCommerce stores. It includes smart filtering, multiple taxonomy support, price range filtering, and a modern responsive design.

Features

• Smart Search: Real-time product search with autocomplete suggestions
• Advanced Filtering: Filter by categories, make, model, part type, and price ranges
• Quick Filters: Pre-defined filter buttons for common searches (On Sale, OEM Parts, New Arrivals, Bestsellers)
• Multiple View Modes: Switch between grid and list views for search results
• Responsive Design: Works perfectly on desktop, tablet, and mobile devices
• Recent Searches: Quick access to your recent search terms
• AJAX Powered: Fast, seamless search without page reloads
• Pagination: Navigate through large result sets efficiently

Installation

Method 1: Manual Installation

1. Download the plugin files to your computer
2. Navigate to your WordPress admin dashboard
3. Go to Plugins → Add New → Upload Plugin
4. Choose the plugin ZIP file and click Install Now
5. Click Activate Plugin

Method 2: FTP/Manual Upload

1. Extract the plugin ZIP file
2. Upload the custom-woocommerce-search folder to /wp-content/plugins/
3. Navigate to Plugins in your WordPress admin
4. Find "Custom WooCommerce Search" and click Activate

Setup and Configuration

Basic Setup

1. After activation, the plugin is ready to use
2. No additional configuration is required for basic functionality

Adding the Search Form

Method 1: Using Shortcode

Add the following shortcode to any page, post, or widget:

[custom_woocommerce_search]

Method 2: Using PHP Template

Add this PHP code to your theme template files:

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

Shortcode Parameters

You can customize the search form using these parameters:

[custom_woocommerce_search placeholder="Search for auto parts..." show_filters="yes" category="electronics"]

• placeholder: Custom placeholder text for the search input (default: "Search products...")
• show_filters: Show/hide advanced filters (default: "yes", options: "yes"/"no")
• category: Pre-select a specific category (default: empty)

Usage Guide

Basic Search

1. Type your search terms in the search box
2. Click the search button or press Enter
3. Results will appear instantly below the search form
4. Use pagination to navigate through multiple pages of results

Using Quick Filters

The search form includes four quick filter buttons:

• 🔥 On Sale: Shows only products that are currently on sale
• ⚙️ OEM Parts: Displays original equipment manufacturer parts
• ✨ New Arrivals: Shows recently added products
• ⭐ Bestsellers: Displays the most popular products

Click any quick filter to instantly apply it to your search.

Advanced Filtering

Accessing Advanced Filters

1. Click the "Advanced Filters" button below the search bar
2. The filter panel will slide down with multiple filtering options

Filter Options

Categories

• Select multiple product categories
• Shows the number of products in each category
• Use the multiselect dropdown to choose multiple options

Make

• Filter by vehicle manufacturer (e.g., Ford, Toyota, BMW)
• Select multiple makes simultaneously

Model

• Filter by specific vehicle models
• Works in combination with Make filter

Part Type

• Filter by part categories (e.g., Engine, Brakes, Suspension)
• Select multiple part types

Price Range

• Custom Range: Set minimum and maximum prices
• Predefined Ranges:
  • All Prices
  • Under $50
  • $50 - $100
  • $100 - $200
  • Over $200

Sort Options

• Default Sorting
• Most Popular
• Year: Oldest First
• Year: Newest First
• Price: Low to High
• Price: High to Low

Applying Filters

1. Select your desired filter options
2. Click "Apply Filters" to update results
3. Or click "Reset" to clear all filters

View Modes

Switch between two display modes:

• Grid View: Products displayed in a card grid (default)
• List View: Products displayed in a vertical list

Click the view toggle buttons in the results header to switch modes.

Recent Searches

The plugin displays your recent searches below the search bar:

• Click any recent search term to instantly search again
• Recent searches are stored locally in your browser

Customization

CSS Customization

To customize the appearance, add CSS to your theme's stylesheet:

/* Change primary color */
.cws-search-container {
    --primary-color: #your-color;
}

/* Modify button styles */
.cws-search-button {
    background: #your-color;
}

/* Adjust grid layout */
.cws-results {
    grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
}

JavaScript Customization

The plugin exposes several JavaScript events you can hook into:

// Before search starts
$(document).on('cws:before_search', function(event, searchTerm) {
    console.log('Searching for:', searchTerm);
});

// After search completes
$(document).on('cws:after_search', function(event, results) {
    console.log('Search results:', results);
});

// When filters are applied
$(document).on('cws:filters_applied', function(event, filters) {
    console.log('Applied filters:', filters);
});

Troubleshooting

Common Issues

Search not working

• Ensure WooCommerce is activated
• Check that products exist in your store
• Verify JavaScript is enabled in your browser

Filters not showing

• Check that taxonomies exist (make, model, part_type)
• Ensure products are assigned to the taxonomies
• Verify show_filters="yes" is set in shortcode

Styling issues

• Check for CSS conflicts with your theme
• Try disabling other plugins to identify conflicts
• Use browser developer tools to inspect elements

Performance issues

• Consider limiting the number of results per page
• Optimize product images and descriptions
• Enable caching on your WordPress site

Getting Help

1. Check the WordPress debug log for errors
2. Test with a default WordPress theme
3. Disable other plugins to isolate conflicts
4. Contact your developer or plugin support

Developer Documentation

Plugin Structure

custom-woocommerce-search/
├── custom-woocommerce-search.php    # Main plugin file
├── assets/
│   ├── script.js                    # Frontend JavaScript
│   └── style.css                    # Frontend CSS
└── README.md                        # This documentation

Hook Reference

Filters

• cws_search_results: Modify search results array
• cws_search_query_args: Modify WP_Query arguments
• cws_filter_options: Modify filter dropdown options

Actions

• cws_before_search_form: Content before search form
• cws_after_search_form: Content after search form
• cws_before_results: Content before search results
• cws_after_results: Content after search results

AJAX Endpoints

The plugin uses WordPress AJAX for search functionality:

• Action: cws_search_products
• Method: POST
• Parameters: search, categories, make, model, part_type, min_price, max_price, page, orderby

Version History

Version 1.0.0

• Initial release
• Basic search functionality
• Advanced filtering system
• Responsive design
• AJAX-powered search

License

This plugin is licensed under the GPL v2 or later.

Support

For support, feature requests, or bug reports, please contact your development team or plugin provider.

---

Last updated: January 2026