How to Build Custom Faceted Search for Big WordPress Sites

How to Build Custom Faceted Search for Big WordPress Sites

Sites that use lots of categories to organize lots of content need faceted search. Without a way to filter through that mountain of content, and pinpoint exactly what they are looking for, visitors may grow frustrated and seek out other options online.

eCommerce sites are the obvious application for faceted search. Ebay, Amazon, Zappos, Etsy, and virtually every other successful eCommerce site has rolled out a powerful faceted search tool.

However, eCommerce isn’t the only place you can see faceted search in action. Social networks, large blogs, and directories – really any site that has a lot of content that can be strictly categorized – can all benefit from a thoughtfully designed faceted search feature.

There are a few different faceted search plugins available for WordPress, and we’ve talked about them before on more than one occasion. But what if none of the available plugins can do exactly what you want them to do?

Building a completely custom faceted search solution from scratch is going to be out of the question for most of us. However, WP Advanced Search is a free framework that will do the heavy lifting for you so that you can build a completely custom and powerful faceted search tool even if you aren’t a full-fledged WordPress developer.

Faceted search at Amazon can be as broad or as specific as you need it to be.
Faceted search at Amazon can be as broad or as specific as you need it to be.

Who can use WP Advanced Search?

WP Advanced Search (WPAS) is a PHP framework.

Wait! Don’t leave!

This tutorial and the WPAS framework are within reach for both WordPress developers and implementers. Sure, developers will have an easier go when getting started with WPAS, but implementers who have played around with PHP just a little and who understand how WordPress works can also learn to use this framework effectively.

What is WP Advanced Search, Really?

What WPAS does is take all of the heavy lifting out of creating a custom faceted search tool. All of the functions that power the facets and search feature are there. All you have to do is pull the pieces together.

Just build a search form and create a template or two to display the search form and the results, and you’ll have a faceted search feature that is exactly what you’re looking for.

Still sounds scary? It really isn’t.

It might take some time to get things set up and working, but the available documentation is excellent and in this tutorial I’ll walk you through the process one step at a time.

Speaking of the documentation, you really should go ahead and familiarize yourself with the WPAS documentation site. This tutorial and the demo search forms, which are available at the documentation site, just touch the tip of the iceberg of what can be done with WPAS. If you get stuck or want to implement a search facet that isn’t covered in this tutorial, the documentation will probably have the information you need to finish the job.

The WP Advanced Search Website.
The WP Advanced Search Website.

Setting up a Development Site

First things first, you’ll need to set up a development site.

Using WPAS does involve editing theme files, so you really shouldn’t try to implement this tool on a live site. Instead, here’s what you should do:

  • Identify a site where you want to add faceted search and migrate a copy of your site to a private development environment so that you can’t accidentally break a live production site.
  • Implement WPAS on your development site and get your search form set up and working.
  • Create a complete backup of your live production site.
  • Copy the appropriate theme files from your development site to your production site.
  • Implement your new faceted search tool on your production site.

Note:  Don’t try to implement this tool on a live production site, for obviously reasons. Play it safe and try out this tool where you aren’t going to break anything.

The WP Advanced Search Github page.
The WP Advanced Search Github page.

Get the Framework

WPAS is hosted at Github. You can download the latest release here.

The framework is designed to be installed directly into your active theme. If the active theme isn’t a child theme, setup and activate a child theme now.

To install the framework extract the zip file you downloaded from Github directly into the active theme directory. Then, rename the extracted file wp-advanced-search. When you’re done, your child theme directory should look something like this.

Screenshot of windows explorer with faceted search installed

The last step in the framework installation process is to add a single line of PHP to your theme’s functions.php file. Here’s the line:

Just drop that line of code in functions.php right after the opening PHP tag at the top of the file. When you’re done, functions.php should look like this.

Require once

WPAS is now installed and ready to use.

How Does WP Advanced Search Work

There are four moving parts that have to come together to make a WPAS faceted search tool work:

  • The WPAS framework has to be installed on the active theme. Check.
  • A search form has to be created and added to the active theme’s functions.php file.
  • The search form must be displayed using a search page template.
  • A search results template must be available to display the search results.

Step one, WPAS framework installation, is done. On to step two: Creating a search form.

Moving on to creating a search form...
Moving on to creating a search form…

Creating a Search Form

Search forms are created by writing a search function and dropping it into the active theme’s functions.php file. That might sound intimidating, but don’t worry, you don’t have to figure this step out on your own. Basic search form functions are ready and waiting for you.

You have a few different options when it comes to creating your first search form. There is a very basic search form included in the setup instructions at the WPAS documentation site, but I recommend skipping it entirely. Instead, take a look at the three different live demos.

  • The Standard Search Demo displays results on the search page but requires a page refresh to process the search and display results.
  • The AJAX Search Demo looks like the standard demo, but it loads results without requiring that the page refresh.
  • The Results on Separate Page Demo displays the search form on one page and loads search results in a separate page.

Each demo comes with complete source code. So it’s actually easier to get one of the demos set up than it is to figure out how to set up the basic search form included in the setup instructions.

Whichever search form you decide to use, you have complete control to customize it by referring to the documentation. So don’t get too hung up on whether or not the search form is exactly what you want it to be.

I settled on the AJAX demo, and the rest of this tutorial demonstrates how to implement that demo.

Using the available documentation, I made a couple of adjustments to the search form and then added it to my theme’s functions.php file. Here’s what the resulting functions.php looked like.

If you take a close look at the original AJAX search form source code you’ll see that I made two noteworthy modifications to the original search form:

  1. I removed field and param from post_type in the wp_query parameter and added post. The original form queried pages as well as two custom post types: fields and parameters. I want the form to query just good old-fashioned posts and pages.
  2. Towards the bottom of the search form, I added a taxonomy field so that I could filter the results by category.

Displaying the Search Form

Once you have settled on a search form, you’ll need somewhere to display it. So the next step is to create a template for your search form.

Displaying your search from is easy. All you need to do is use a basic page template that pulls in your site’s header and footer and then insert the search form between the two. One way to get a basic template to work with is to copy the page.php template from your parent theme and delete everything between get_header() and get_footer().

Since I was working with the AJAX demo, I used the source code from the AJAX demo and dropped it into a basic page template. I then saved that file to the child theme root directory using a unique and meaningful name

Here’s what my search template looks like.

Did you notice the empty div at the end of the template? Since the AJAX search form displays both the search form and the results on the same page, the search form template needs to include a place for the search results to be displayed. That empty div is where the results will be displayed.

Creating a Search Results Template

If you used the Standard Search Demo then you only have two files to worry about: functions.php and your search page template. Congrats! You’re done! Just create a new page using your search page template and test it out.

However, if you are working with either the AJAX Demo or displaying the results on a separate page, you’ll need to create one more file: a template file for looping through posts and displaying the search results. The AJAX Demo provides the code you need to create the template file for the search results, but the Results on Separate Page Demo does not.

If you are using the Results on Separate Page Demo and need a template to display the search results, use the results template from the AJAX demo and drop it into a basic page template that includes get_header() and get_footer(). Then set that page as the target page for your search form – something you’ll need to do by editing the search form code in functions.php.

If you opted for the AJAX Demo, as I did, the search results template is provided for you. Here it is:

Since this template will be used to return and display results directly on the search page, it does not include get_header() and get_footer(), just the loop that will display our search results.

I made no changes to this template other than to adjust the comments at the top of the file. So this step is a simple copy-and-paste exercise. Just make sure that the name of your search results template is included correctly in the search form function in functions.php.

Make sure your search function targets your search results template.
Make sure your search function targets your search results template.

By this point, a little confusion is understandable. To clear things up, here’s a look at the contents of my child theme directory.

Child theme files

All three files that we’ve looked at–functions.php, the search form template which I named ajax-advanced-search.php, and the search results template template-ajax-results.php–are just dropped right into the child theme directory.

With those three files in place, we’re ready to display and try out the new search feature.

Test and Style Your Form

To display your search form, create a new page using the search form template.


What you name the page and any other content you add to the page isn’t important as long as you pick the right template. Do that, and assuming there are not errors in your code your search form will be displayed. Now’s the time to try out your search form and fine tune it by referring to the documentation. Test out new fields, different field formats, and other field parameters until you’re satisfied.

Once you have your form set up and working you’ll want to take some time to style the search form and results using your child theme’s style.css file or your favorite CSS plugin.

In the end, here’s how my faceted search form turned out.

The AJAX search tool I created.
The AJAX search tool I created.

This is Just the Beginning

WPAS can be used to build just about any type of faceted search tool.

WPAS plays nice with advanced custom fields, so you can create complex taxonomies to filter results with precision. Or imagine if you combined a basic text search field on your site’s homepage with a separate results’ page that included a faceted search form and AJAX-powered updates – then you’d have a truly impressive faceted search tool that didn’t clutter up your homepage, and it’s one you could build yourself.

This really is only the beginning of what you can do with WPAS.

Did you get one of the demos up and running on your development site? How could you use this tool to make it easier for your site's visitors to find what they're looking for? Let us know what you think in the comments below.

Jon Penland

Jon Penland Jon manages operations for Kinsta, a managed WordPress hosting provider. He enjoys hiking and adventuring in northeast Georgia with his wife and kids when he isn't figuring out the ins and outs of supporting WordPress-powered businesses.