Custom Query Guide

Setting Up a Custom Filter

In your post widget assign a unique Query ID under Content > Query > Query ID. This ID connects your post widget with your custom query filter. It is useful when you need a greater control over the post widget’s query, besides the available options.

Using the Custom Filter

After assigning a Query ID, add your custom query logic in your theme’s functions.php or a custom plugin. Use the action hook with this format:


function custom_query( $query ) {
    // Modify the posts query here
}
add_action( 'bpfwe/query/{$query_id}', 'custom_query' );

For example, if you use my_custom_filter as the Query ID, the hook you will use is bpfwe/query/my_custom_filter.

Example 1: Show Multiple Post Types in a Post Widget


function bpfwe_by_post_types( $query ) {
    $query->set( 'post_type', [ 'page', 'post', 'product' ] );
}
add_action( 'bpfwe/query/my_custom_filter', 'bpfwe_by_post_types' );

Example 2: Show Posts with Multiple Statuses at Once


function bpfwe_by_post_status( $query ) {
    $query->set( 'post_status', [ 'publish', 'draft'] );
}
add_action( 'bpfwe/query/my_custom_filter', 'bpfwe_by_post_status' );

Example 3: Order Posts by Most Popular Post by Comment Count


function bpfwe_by_different_order( $query ) {
    $query->set( 'orderby', 'comment_count' );
}
add_action( 'bpfwe/query/my_custom_filter', 'bpfwe_by_different_order' );

Notes

Replace my_custom_filter with your actual Query ID.
Refer to the pre_get_posts from WordPress documentation for more advanced query options.

Setting Up a Custom Args Filter

In your filter widget assign a unique Query ID under Content > Query > Filter Query ID. This ID connects your filter widget with your custom args filter. It is useful when you need to directly modify the $args array passed be the filter before the query runs.

Using the Custom Args Filter

After assigning a Query ID, add your custom query logic in your theme’s functions.php or a custom plugin. Use the filter hook with this format:

add_filter( 'bpfwe/filter_query_args/{$query_id}', function( $args, $widget ) {
    // Modify the $args array here
    return $args;
}, 10, 2 );

For example, if you use my_custom_filter as the Query ID, the hook you will use is bpfwe/filter_query_args/my_custom_filter.

Example 1: Filter Posts by Meta Value

add_filter( 'bpfwe/filter_query_args/my_custom_filter', function( $args, $widget ) {
    // Show posts where meta key 'highlight' equals 'yes'
    $args['meta_query'][] = [
        'key'     => 'highlight',
        'value'   => 'yes',
        'compare' => '=',
    ];
    return $args;
}, 10, 2 );

Example 2: Filter Posts by Taxonomy Term

add_filter( 'bpfwe/filter_query_args/my_custom_filter', function( $args, $widget ) {
    // Add the new taxonomy condition for 'events' category
    $args['tax_query'][] = [
        'taxonomy' => 'category',
        'field'    => 'slug',
        'terms'    => 'events',
    ];

    // Optional: enforce relation if combining multiple conditions
    if ( count( $args['tax_query'] ) > 1 ) {
        $args['tax_query']['relation'] = 'AND';
    }

    return $args;
}, 10, 2 );

Example 3: Order Posts by Custom Date Meta

add_filter( 'bpfwe/filter_query_args/my_custom_filter', function( $args, $widget ) {
    // Order posts by meta key 'event_date' descending
    $args['meta_key'] = 'event_date';
    $args['orderby']  = 'meta_value';
    $args['order']    = 'DESC';
    return $args;
}, 10, 2 );