facetwp_template_use_archive
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.
Remove facet choices that are not children of the current term
If you have a category/tag/taxonomy term archive page with a facet on it that uses the same hierarchical category/tag/taxonomy as its data source, the facet will display all choices (terms) for which there are posts on the page. However, posts can have multiple terms selected, so this can include terms anywhere in the taxonomy’s term hierarchy, not only children of the archive’s current term.
A common question is how to let the facet display only child terms of the archive’s current term (with or without the current term itself)? This can be accomplished by using the facetwp_facet_render_args to remove all terms from the facet that are not a child term of the current term of the archive template.
If you retain the current term in the facet by setting by setting $keep_current_term to true, you can then also pre-select the current term, if needed also after a reset.