Filter Custom Queries

Introduction#Introduction

WP Grid Builder offers the possibility to filter custom queries without the need to use a grid made with the plugin. This means that you can use facets in your pages to filter post results.

If you are using Elementor, Oxygen, Beaver Builder or Bricks plugin, you should use the corresponding WP Grid Builder add-ons instead of using the following method.

Depending on the theme or site builder you use, it may not work or create conflicts, especially if the results are layout with JavaScript.

Limitations#Limitations

This method may not work in all cases because it will depend on a third-party content whose parameters WP Grid Builder can not fully control.

In most cases, the pagination will be in conflict with the facets. To avoid conflicts, you should use the pagination facet instead of the default pagination.

Principle#Principle

In order to filter a query, you need to add the query argument wp_grid_builder set to wpgb-content. If you want to filter several queries in a page, you must add a suffix to identify each query as follows: wpgb-content-1, wpgb-content-2, etc.

$the_query_1 = new WP_Query(
	[
		'post_type'       => 'post',
		'posts_per_page'  => 10,
		'wp_grid_builder' => 'wpgb-content-1',
	]
);

To indicate to the plugin where the content to be refreshed in the page is located, you need to add a class on the content wrapper of your posts. The class name (prefixed by wpgb-content) must be the same as the one used in wp_grid_builder query argument.

if ( $the_query_1->have_posts() ) {

	echo '<ul class="wpgb-content-1">';
	while ( $the_query_1->have_posts() ) { ... }
	echo '</ul>';

}

To filter content with facets, you need to set as grid name, in the facet shortcode or PHP function, the same value you defined in the wp_grid_builder query argument.

wpgb_render_facet( [ 'id' => 1, 'grid' => 'wpgb-content-1' ] );
wpgb_render_facet( [ 'id' => 2, 'grid' => 'wpgb-content-1' ] );

Example#Example

To filter content from a page (except archive pages) made with Gutenberg or a page builder for example, the same principle must be used. This means that you have to define a custom query argument and add a class on the content to be filtered thanks to your page builder.

Not all page builders provide an easy way to configure custom query arguments in WP_Query. In this case, you can place a shortcode just before the content/query to be filtered in order to define the query argument (the query ID must be prefixed by wpgb-content).

[wpgb_query id="wpgb-content"]

In addition to this shortcode, you can also enable Filter Custom Content option in the plugin settings panel to automatically locate the content to be filtered in the page.

Now, to filter the content you just need to add facet blocks or shortcodes with as grid name the query ID (prefixed by wpgb-content) set in the previous shortcode:

[wpgb_facet id="1" grid="wpgb-content"]
[wpgb_facet id="2" grid="wpgb-content"]

If you use a page builder that let you setup query arguments and add a class name on the content to filter you do not need to use the [wpgb_query] shortcode.