Overview

This hook is useful if FacetWP is unable to auto-detect the correct query (such as when there’s a custom query on a page).

This hook is not relevant for shortcode templates (made with the Listing Builder).

Parameters

  • $is_main_query | boolean | Whether FacetWP should use the current query
  • $query | object | The WP_Query object

How it works

On WP archive templates, or when using a custom WP Query, FacetWP will automatically try to find the right query. FacetWP uses the following logic to determine whether a query should be used:

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
$is_main_query = ( $query->is_archive || $query->is_search || ( $query->is_main_query() && ! $query->is_singular ) );

FacetWP uses the first query that matches the above criteria. While this works great most of the time, we understand that this won’t work 100% of the time with all themes. This hook is useful when the above logic isn’t sufficient.

Forcing a custom query

Let’s say we have a custom WP_Query on a page that FacetWP isn’t able to auto-detect.

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
$args = [
  'post_type' => 'event',
  'posts_per_page' => 10,
  'facetwp' => true, // we added this
];
$query = new WP_Query( $args );

By adding facetwp => true to the query arguments, FacetWP will use this query for filtering unless another query has already been chosen.

How to ignore archive queries

On WP archive pages (such as post type archives, category, term or /shop/ archives), FacetWP by default will always prioritize the archive query ahead of any other query on the page.

If you are using a custom WP Query or a shortcode template (made with the Listing Builder) on a WP archive page, you have to tell FacetWP explicitly which query (not) to use, otherwise unexpected things will happen.

Using this hook, it is possible to force FacetWP to ignore the archive query, and use the custom query or shortcode query instead. 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_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 );

How to ignore archive queries conditionally

If you need to ignore the archive query only on specific archive templates, you can apply the above code conditionally:

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 ) {

  $uri = FWP()->helper->get_uri();
  $is_desired_page = in_array( $uri, [ 'some/page', 'some/other/page', 'also/this/page'] );

  if ( $query->is_archive() && $query->is_main_query() && $is_desired_page ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

For the condition, you can also use regular WordPress conditional tags, for example is_category('events').

How to ignore other queries

In some cases, FacetWP’s automatic query detection latches on to the wrong query on the page. This example tells FacetWP to ignore queries with the post_type set to tribe_events:

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 ( 'tribe_events' == $query->get( 'post_type' ) ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 10, 2 );

More examples

See also