For all types listing templates, FacetWP will automatically try to find the right query. This usually works great, but sometimes FacetWP needs some extra guidance on which query to use.

The WordPress loop

FacetWP tries to automatically add a facetwp-template CSS class to an element surrounding the Loop. But due to a myriad of circumstances, sometimes it needs to be done manually.

If so, wrap the CSS class around both the if ( have_posts() ) and else statements, as shown below).

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
?>
<div class="facetwp-template">
    <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
        <?php get_template_part( 'content', 'post' ); ?>
    <?php endwhile; else : ?>
        <p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
    <?php endif; ?>
</div>

The file to edit depends on several factors. As a general rule:

Search page: search.php
Main archive: archive.php
Category archive: category.php
Blog home: home.php
WooCommerce shop: archive-product.php

See WordPress’ built-in Template Hierarchy.

No results

FacetWP was unable to auto-detect the post listing

If you’re seeing this error it’s because FacetWP can’t find a suitable query. This usually happens when you have a custom WP_Query on a standard WordPress page. To let FacetWP detect the custom query, you have to add facetwp => true to the query arguments. See this section for more information.

This FAQ question list more scenarios in which this error can happen.

Turn on Debug Mode

If FacetWP isn’t filtering correctly, it’s because FacetWP is using the wrong query.

To find which query FacetWP is using, go to Settings > FacetWP > Settings, and turn on Debug Mode.

Finding the query

To find the query FacetWP is using, browse to your facet listing, open your browser’s code inspector, go to the Console tab, and type:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. More info
FWP.settings.debug

This will return lots of debugging data, including the query arguments and SQL. You can click open each item to get more information:

debugging

The quickest way to see if FacetWP is detecting the right query is to compare what you have set in the query arguments of your listing template with the SQL that FacetWP is using. You can directly see the used SQL by typing this in the Console:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. More info
FWP.settings.debug.sql

Things to look for in the SQL are:

  • The post type(s) retrieved. Look for AND wp_posts.post_type =.
  • The set order. Check if theORDER BY clause is using the right order.
  • The posts per page. Check if the LIMIT clause is showing the correct posts per page. For example, if you have set posts_per_page to 9, the SQL will show as LIMIT 0, 9.

If anything in the SQL is off, then FacetWP may be detecting the wrong query.

Another handy command in the Console is:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. More info
FWP.settings.pager

This will show the number posts per page (per_page), total number of posts (total_rows), and total number of pages (total_pages). If this is not what you expect, FacetWP is likely detecting the wrong query.

If you think FacetWP is detecting the wrong query, the first thing to do is to enable “Strict query detection” in FacetWP’s settings. If that does not help, you can try to let FacetWP ignore the detected query:

Ignore irrelevant queries

Let’s say you’ve determine that FacetWP is incorrectly using a query with post_type = edd_wish_list. We’ll just tell FacetWP to ignore the query, using the facetwp_is_main_query filter:

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

See the facetwp_is_main_query hook page for more examples.

See also

Last updated: May 21, 2024