Overview

With this hook you can customize the initial bucket of post IDs, after the WP_Query has been executed but before any facets have been processed.

This hook can be used to remove a single or multiple posts from the page, or pass a custom array of post IDs, overruling the WP_Query entirely.

Using this hook can be an alternative to using post__in or post__not_in, either in the original query arguments, or added later with a pre_get_posts hook, or a facetwp_query_args hook.

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 before facet choices are processed, not before 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, no matter if facets are being used or not.

In Listing Builder templates, if you filter out post IDs with this hook, the posts will be removed before and after filtering. (Note: in other listing template types only after filtering). If you need to change the returned post IDs only after facet filtering, use the facetwp_filtered_post_ids hook instead. That hook can be made to run only if any (or specific) facets are in use, or even only if specific facet choices have been made. Another way to customize filtered posts for specific facets, is the facetwp_facet_filter_posts hook.

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.

See the code examples below for ways to use this.

Where to use this hook

In Listing Builder listing templates, this hook changes the results on the first page load and after facet filtering. 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' );

A usage example can be found in our sticky posts tutorial, where the facetwp_pre_filtered_post_ids hook is used to float sticky posts to the top of the listing when they are already in the results, and the facetwp_preload_force_query hook is needed to make sure this also happens on first page load, on WP archive or custom WP_Query listing templates.

Parameters

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

Usage examples

Remove one post ID

This example prevents post ID = 42 from appearing in the results, 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_pre_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'books' == $class->ajax_params['template'] ) { // Change 'books' to the name of your listing
    if ( false !== ( $key = array_search( 42, $post_ids ) ) ) { // Remove post ID 42
      unset( $post_ids[ $key ] );
    }
  }
  return $post_ids;
}, 10, 2 );

Remove multiple post IDs

This example prevents multiple post IDs from appearing in the results 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_pre_filtered_post_ids', function( $post_ids, $class ) {
  if ( 'recipes/vegetarian' == $class->http_params['uri'] ) { // Change 'recipes/vegetarian' to your page URI
    $remove_ids = [42,43,44]; // Remove these post IDs
    $post_ids = array_diff( $post_ids, $remove_ids );
  }
  return $post_ids;
}, 10, 2 );

Keep only a selection of post IDs

To display only a selection of post IDs in the results, 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_pre_filtered_post_ids', function( $post_ids, $class ) {
 if ( 'recipes/vegetarian' == $class->http_params['uri'] ) { // Change 'recipes/vegetarian' to your page URI
    $post_ids = [42,43,44]; // Only show these post IDs
  }
  return $post_ids;
}, 10, 2 );

Note that this does not influence filtering: you can still filter these posts with facets. If you need to prevent this, use the facetwp_filtered_post_ids hook instead, with which you can customize returned post IDs after facet filtering.

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.

More examples

See also

Last updated: June 21, 2024