Overview

Custom Query Guide

Custom Query Filter for Posts Widget

Setting Up a Custom Filter

In your post widget assign a unique Query ID under Content > Query > Query ID. This ID connects your 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.

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

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:

add_action( 'bpfwe/query/{$query_id}', function( \WP_Query $query, $widget ) {
    // Modify the query here
}, 10, 2 );

Example 1: Filter Posts by Meta Value

add_action( 'bpfwe/query/my_custom_filter', function( $query ) {
    // Show posts where meta key 'highlight' equals 'yes'
    $query->set( 'meta_key', 'highlight' );
    $query->set( 'meta_value', 'yes' );
}, 10, 2 );

Example 2: Filter Posts by Taxonomy Term

add_action( 'bpfwe/query/my_custom_filter', function( $query ) {
    // Show posts only in the 'events' category
    $query->set( 'tax_query', [
        [
            'taxonomy' => 'category',
            'field'    => 'slug',
            'terms'    => 'events',
        ],
    ] );
}, 10, 2 );

Example 3: Order Posts by Custom Date Meta

add_action( 'bpfwe/query/my_custom_filter', function( $query ) {
    // Order posts by meta key 'event_date' descending
    $query->set( 'meta_key', 'event_date' );
    $query->set( 'orderby', 'meta_value' );
    $query->set( 'order', 'DESC' );
}, 10, 2 );

Notes

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

Custom Query Args Filter for Filter Widget

Setting Up a Custom Args Filter

In your filter widget assign a unique Query ID under Content > Additional Options > Filter Query ID. This ID connects your 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.

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.

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

Example 1: Filter Posts by Meta Value

add_filter( 'bpfwe/filter_query_args/my_custom_filter', function( $args ) {
    // 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 ) {
    // 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 ) {
    // Order posts by meta key 'event_date' descending
    $args['meta_key'] = 'event_date';
    $args['orderby']  = 'meta_value';
    $args['order']    = 'DESC';
    return $args;
}, 10, 2 );

Notes

  • Replace my_custom_filter with your actual Query ID.
  • This filter works at the $args level after passing the arguments from the filter.
  • Refer to the WP_Query documentation for a full list of arguments you can use.