Overview

With this hook you can customize the returned post IDs, after the WP_Query has been executed and after any facets have been processed.

This hook can be used to customize the returned post IDs after facet filtering. For this to work, the hook needs to run with a condition that checks if any facet is filtering, or if a specific facet, or even a specific facet choice is filtering. If used in this way, the hook can be used on any type of listing template.

How this hook works

To understand what this hook does exactly, be aware that – despite what the name suggests – it runs in the rendering process after facet choices are processed, not after facets are actually filtering: also facets with no selections are processed. So this hook will run on each page load, also on the first page load (if used on a Listing Builder listing template), and also when no facets are filtering.

It is not recommended to use this hook “bare”, meaning without any extra checks for facets being in use. In that case, it will do the same as its sister hook: facetwp_pre_filtered_post_ids, but it will cause issues in some specific use cases. So make sure to only use it with those extra checks, as shown in the examples below.

Within the hook, you have access to information about the page, listing template and facets used, via the FacetWP_Renderer class. This can be used to let the code run only in certain conditions. For example, you can check:

  • if a specific Listing Builder template is used (with $class->ajax_params['template']).
  • if the page has a specific URI (with $class->http_params['uri']). Note that the “URI” is the part of the URL without the domain name and the query variables, and without beginning or ending slashes.
  • if specific facets or facet choices are currently in use (with $class->facets[ $facet_name ]['selected_values']).

See the code examples below for ways to use this.

Parameters

  • $post_ids | array | An array of post IDs
  • $class | object | The FacetWP_Renderer class (see /includes/class-renderer.php)

Usage examples

Customize post IDs after any facet filtering

The following examples show how to customize the returned post IDs after any facets are filtering:

Remove one post ID after facet filtering

This example prevents post ID = 42 from appearing in the results after any facet filtering, if the Listing Builder listing template is named “books”. The listing template name is available in the ajax_params object within the FacetWP_Renderer class:

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_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'books' == $class->ajax_params['template'] ) { // Change 'books' to the name of your listing
    if ( $post_ids !== FWP()->unfiltered_post_ids ) { // Is only true after facet filtering
      if ( false !== ( $key = array_search( 42, $post_ids ) ) ) { // Remove post ID 42 after facet filtering
        unset( $post_ids[ $key ] );
      }
    }
  }
  return $post_ids;
}, 10, 2 );

Remove multiple post IDs after facet filtering

This example prevents multiple post IDs from appearing in the results after any facet filtering, on a page where the URI is recipes/vegetarian. The URI is available in the http_params object within the FacetWP_Renderer class:

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_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'recipes/vegetarian' == $class->http_params['uri'] ) { // Change 'recipes/vegetarian' to your page URI
    if ( $post_ids !== FWP()->unfiltered_post_ids ) { // Is only true after facet filtering
      $remove = [42,43,44]; // Remove these post IDs after facet filtering
      $post_ids = array_diff($post_ids, $remove);
    }
  }
  return $post_ids;
}, 10, 2 );

Keep a specific post ID after facet filtering

This example prevents post ID = 42 from being filtered out after any facet filtering. Note that this post ID needs to be present when no facets are in use.

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_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'recipes/vegetarian' == $class->http_params['uri'] ) { // Change 'recipes/vegetarian' to your page URI
    if ( $post_ids !== FWP()->unfiltered_post_ids ) { // Is only true after facet filtering
      $newPostID = 42; // Keep post ID 42 after facet filtering
      if ( ! in_array( $newPostID, $post_ids ) ) {
        $post_ids[] = $newPostID;
      }
    }
  }
  return $post_ids;
}, 10, 2 );

Keep only a selection of post IDs after facet filtering

To display only a selection of post IDs in the results after any facet filtering, you can pass them in an array:

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_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'recipes/vegetarian' == $class->http_params['uri'] ) { // Change 'recipes/vegetarian' to your page URI
    if ( $post_ids !== FWP()->unfiltered_post_ids ) { // Is only true after facet filtering
      $post_ids = [ 42, 43, 44 ];  // Only show these post IDs
    }
  }
  return $post_ids;
}, 10, 2 );

This will effectively disable filtering logic entirely, because no matter what filters you use, the results will only contain the post IDs in the array. So this example is not very practical, unless you extend it with more conditions to check for certain facets and/or facet choices:

Customize post IDs if a specific facet is filtering

The facets and their selected values are available via $class->facets. This can be used to add extra conditions that check if a specific facet is currently filtering, or even if that facet has a specific choice selected. Two examples:

Remove one post ID if a specific facet is filtering

Prevent post ID = 42 from appearing in the results if the specified facet has any choice(s) selected:

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_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'recipes/vegetarian' == $class->http_params['uri'] ) { // Change 'recipes/vegetarian' to your page URI
    $facet_name = 'my_facet_name'; // Replace 'my_facet_name' with the name of your facet
    if ( $post_ids !== FWP()->unfiltered_post_ids ) { // Is only true after facet filtering
      if ( isset( $class->facets[ $facet_name ] ) ) { // If this facet is present
        $selected = $class->facets[ $facet_name ]['selected_values'];
        if ( ! empty( $selected ) ) { // If this facet has any selected choices
          if ( false !== ( $key = array_search( 42, $post_ids ) ) ) { // Remove post ID 42
            unset( $post_ids[ $key ] );
          }
        }
      }
    }
  }
  return $post_ids;
}, 10, 2 );

Remove one post ID if a specific facet is filtering with a specific choice

Prevent post ID = 42 from appearing in the results if the specified facet has one or more specific choices selected:

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_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'recipes/vegetarian' == $class->http_params['uri'] ) { // Change 'recipes/vegetarian' to your page URI
    $facet_name = 'my_facet_name'; // Replace 'my_facet_name' with the name of your facet
    if ( $post_ids !== FWP()->unfiltered_post_ids ) { // Is only true after facet filtering
      if ( isset( $class->facets[ $facet_name ] ) ) { // If this facet is present
        $selected = $class->facets[ $facet_name ]['selected_values'];
        $facet_values = array(
          'my_facet_choice',
          'my_other_facet_choice'
        ); // Replace with one or more facet choices. Use the facet value (as displayed in the URL when that choice is selected).
        if ( count( array_intersect( $selected, $facet_values ) ) > 0 ) {
          if ( false !== ( $key = array_search( 42, $post_ids ) ) ) { // Remove post ID 42
            unset( $post_ids[ $key ] );
          }
        }
      }
    }
  }
  return $post_ids;
}, 10, 2 );

Float sticky posts to the top

Another example can be found in our sticky posts tutorial, where this hook is used to float sticky posts to the top of the listing when they are already in the results, after facet filtering, or after (not) using a specific facet.

Using this hook on non-Listing-Builder listings

As explained above, it is not recommended to use this hook “bare”, meaning without any extra checks for facets being in use. However, if you have a use case for running it this way, be aware that it will change results on the first page load and after filtering only in Listing Builder listing templates. For performance reasons, in other types of listing templates (like WP archives and custom WP_Query templates), this hook is prevented from changing the query on the first page load and will only affect the results after facet filtering.

To make this hook also run on the first page load in these other listing types, you can combine it with the following hook in 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_preload_force_query', '__return_true' );

More examples

See also

Last updated: June 21, 2024