Overview

This hook is useful if you are using a Listing Builder listing template 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 Listing Builder listing’s query arguments when filtering.

Examples

For example, on the category.php term archive template, you could place a Listing Builder listing template 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 Listing Builder listing template 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:

How to use custom PHP code?

PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info

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 Listing Builder listing’s query arguments when filtering.

But when you use a Listing Builder listing 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 Listing Builder listing 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:

How to use custom PHP code?

PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info

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:

How to use custom PHP code?

PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info

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 Listing Builder listing’s query arguments with a pre_get_posts filter.

See also