WP Query Engine provides several filters that allow you to customize many aspects of operation.


Output templates can be added, removed, or modified using the wp_query_engine_templates filter.

Template registration is not required for use in a shortcode, but is required to add custom templates to select lists, such as in the Beaver Builder module or sidebar widget.

function register_templates( $templates ) {
    $templates['My Custom Template'] = get_stylesheet_directory() . '/templates/my_custom_template.php';
    return $templates;
add_filter( 'wp_query_engine_templates', 'register_templates' );


Force the use of a specific template, regardless of which template is selected. The wp_query_engine_template filter allows developers to select a template programmatically at the time of output, instead of specifying beforehand.

function force_template( $template_name, $atts, $query ) {
	if( $atts['context'] === 'my_custom_context' ) {
		$template_name = 'templates/my_custom_template.php';
    return $template_name;
add_filter( 'wp_query_engine_template', 'force_template', 10, 3 );


Filter the query arguments before they are processed. This allows you to add additional arguments, or control the arguments within your code, instead of the shortcode or other means.

function force_query_args( $args ) {
    if( isset( $args['post_type'] ) && $args['post_type'] === 'recipe' ) {
        $args['tag__in'] = array( 'featured' );
    return $args;
add_filter( 'wp_query_engine_args_raw', 'force_query_args' );


Filter the query arguments after processing. This allows developers to apply some specific formatting to the arguments after they've been normalized, but before being passed to WP_QUERY. At this point, the post id's that will be queried is already set, so fewer arguments can be applied.

function force_query_args( $args ) {
    if( isset( $args['post_type'] ) && $args['post_type'] === 'recipe' ) {
        $args['post_per_page'] = -1;
    return $args;
add_filter( 'wp_query_engine_args', 'force_query_args' );


By default, the template includes a loop with specific template actions already defined. The loop uses the template name to define custom actions.

The template name is normalized by removing spaces, dashes, and .php. If a template is defined by name, such as My Custom Template, it will be normalized to my_custom_template. A name specified by path, such as templates/homepage_loop.php, it will be normalized to templates_homepage_loop.

If you do not wish to include the default loop, and instead want to define your own loop in your custom template files, you can using the wp_query_include_loop filter.

function dont_include_wp_query_loop( $include, $atts ) {
	if( $atts['template'] === 'My Custom Template' ) {
		return false;
	return true;
add_action( 'wp_query_include_loop', 'dont_include_wp_query_loop' );

The loop is includes after the template files, however. So it can be defined inside specific templates, with a simpler function

add_action( 'wp_query_include_loop', '__return_false' );

Be careful, however, not to define this globally in your functions.php file unless an alternative loop is provided for the default templates, or they will not output.

Last updated