Filters

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

wp_query_engine_templates

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' );

wp_query_engine_template

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 );

wp_query_engine_args_raw

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' );

wp_query_engine_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' );

wp_query_include_loop

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.