Overview

This hook is useful if you use a Listing Builder template shortcode on a category, tag, taxonomy term, or search archive page.

With this hook in place, FacetWP will automatically pre-filter results based on the current category / tag / taxonomy term or search term(s), by injecting them into the shortcode template’s query arguments when filtering.

Examples

For example, on the category.php term archive template, you could place a template shortcode that fetches posts. Without this hook, on the /category/events archive page, after using facets, the filtered results will be fetched from all posts, including posts that do not have the category ‘events’. With this hook in place, the results will only contain posts within the category ‘events’.

Similarly, consider a search results page based on the search.php template that contains a template shortcode that fetches products. Without this hook, on the search results page with the URL /?s=hoodies, selecting facet choices will generate results from all products, including those that do not contain the search term ‘hoodies’. With this hook in place, the results will be pre-filtered with that search term, so users can use the facets on the page to further ‘drill down’ into those results.

Parameters

  • $use_archive | boolean | Should FacetWP pre-filter?

Usage

Add the following code to your (child) theme’s functions.php:

add_filter( 'facetwp_template_use_archive', '__return_true' );

Fixing query differences before and after filtering

As explained above, this hook pre-filters the results with the current category/tag/term or search terms by injecting them into the shortcode template’s query arguments when filtering.

But when you use a shortcode template on an archive (or search page), the native category/tag/term archive query (or search query) will still be used before filtering, because FacetWP’s automatic query detection by default will always prioritize the archive query (or search query) ahead of any other query on the page.

This may lead to differences before and after filtering caused by query arguments other than the current category/tag/term or search term(s).

For example, you may see a different number of paged results before and after filtering, caused by the posts_per_page query argument in the native archive/search query being different than the one in the shortcode query. Similarly, there may be differences caused by the order and orderby query arguments not being the same.

There are two ways of fixing this:

Ignore the archive/search query entirely

One way of fixing this is to use the facetwp_is_main_query hook to force FacetWP to ignore the archive / search query entirely, in combination with the above facetwp_template_use_archive hook.

The following code will do that for category/tag/term archives:

add_filter( 'facetwp_is_main_query', function( $is_main_query, $query ) {
  if ( $query->is_archive() && $query->is_main_query() ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

For a search page, use this instead:

add_filter( 'facetwp_is_main_query', function( $is_main_query, $query ) {
  if ($query->is_search() && $query->is_main_query() ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

Change the archive query with a pre-get-posts filter

An alternative way of fixing differences before and after filtering is to bring the native archive/search query arguments in line with the shortcode template’s query arguments with a pre_get_posts filter.

See also